subagentic.ai RSS X YouTube GitHub
AI-generated illustration

How-Tos

How to run a first smolagents CodeAgent

Official smolagents quickstart: install the toolkit extra, create a CodeAgent, and run a first code-writing task.

smolagentshugging-facecode-agents

smolagents is an open-source Python library for building and running agents in a few lines of code. The Hugging Face quickstart is the whole first run: install the toolkit extra, create a CodeAgent with InferenceClientModel, and call run on one task. This is a standing setup from the docs, not a release announcement.

What a CodeAgent does

The docs describe the library as intentionally small. Agent logic fits in about a thousand lines of code, and the abstractions stay close to raw code.

The class the quickstart uses is CodeAgent. It writes its actions in code — the page contrasts that with “agents being used to write code” — so it can call tools or run computations with ordinary Python composability: function nesting, loops, and conditionals. You pass a task string. The agent writes Python to solve it and returns a result.

The same page documents a second class, ToolCallingAgent, for the usual JSON or text tool-calling style when that pattern is a better fit. The first example does not use it.

A few other capabilities are named on the page and are out of scope for this first run. Agents and tools can be shared to and loaded from the Hub as Gradio Spaces. Models can come from Inference providers, from APIs such as OpenAI or Anthropic through a LiteLLM integration, or from a local runtime using Transformers or Ollama. Agents can take vision, video, and audio inputs, not only text. Tools can come from an MCP server, from LangChain, or from a Hub Space. The library also ships command-line utilities named smolagent and webagent. The quickstart does not show their arguments, so this article does not invent a CLI call.

Code execution can be sandboxed through Modal, Blaxel, E2B, or Docker. The minimal example below does not set that up. Treat the secure-execution tutorial as a later read, not as part of the first command sequence.

Install the toolkit extra

The documented install is a single pip command. The comment on that line says the toolkit extra includes default tools like web search, which is why the same extra covers the search-tool step later.

pip install 'smolagents[toolkit]'  # Includes default tools like web search

This page does not state a Python version, a virtual-environment recipe, or an authentication variable. If your environment needs any of those, they are unknown from the quickstart. The page points to its Installation Guide for setup with various models and tools.

Create the agent and run one task

The minimal agent uses the Hugging Face Inference API through InferenceClientModel. Constructed with no arguments, it uses a default model. The page does not name that default model id.

from smolagents import CodeAgent, InferenceClientModel

# Initialize a model (using Hugging Face Inference API)
model = InferenceClientModel()  # Uses a default model

# Create an agent with no tools
agent = CodeAgent(tools=[], model=model)

# Run the agent with a task
result = agent.run("Calculate the sum of numbers from 1 to 10")
print(result)

What that block does, as the page writes it:

  • Import CodeAgent and InferenceClientModel.
  • Build the model with InferenceClientModel(). The comment in the docs says this uses the Hugging Face Inference API and a default model.
  • Build a CodeAgent with tools set to an empty list and that model. No search tool, no custom tool.
  • Call agent.run with the task "Calculate the sum of numbers from 1 to 10".
  • Print the value run returns.

The page’s summary is the whole contract for this step: the agent uses Python code to solve the task and returns the result. No sample output is shown, so there is no documented number or trace to expect on screen.

If the call fails, this page does not document the error text or a fix. Do not add a token flag or config key that is not written here.

Add a tool as the documented next step

After the empty-tools agent, the same page shows one addition: DuckDuckGoSearchTool. The install comment is the only note tying the toolkit extra to default tools like web search. The tool class itself is introduced only in this second example.

from smolagents import CodeAgent, InferenceClientModel, DuckDuckGoSearchTool

model = InferenceClientModel()
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
)

# Now the agent can search the web!
result = agent.run("What is the current weather in Paris?")
print(result)

The model line is unchanged. The tools list is no longer empty, and the task string is "What is the current weather in Paris?" so the agent has a web question to answer. The page does not show the tool’s return shape or how to author a tool of your own. It points to a separate tutorial for building custom tools.

Swap in another model

The quickstart then shows three model constructors. They are alternatives for the model object you pass into CodeAgent, not three steps you run in order. The model ids below are copied from the page. The docs do not call them current recommended defaults.

# Using a specific model from Hugging Face
model = InferenceClientModel(model_id="meta-llama/Llama-2-70b-chat-hf")

# Using OpenAI/Anthropic (requires 'smolagents[litellm]')
from smolagents import LiteLLMModel
model = LiteLLMModel(model_id="gpt-4")

# Using local models (requires 'smolagents[transformers]')
from smolagents import TransformersModel
model = TransformersModel(model_id="meta-llama/Llama-2-7b-chat-hf")

Read the comments with the constructors. A specific Hub model stays on InferenceClientModel and sets model_id. OpenAI or Anthropic goes through LiteLLMModel and requires the extra written as 'smolagents[litellm]'. A local Transformers model uses TransformersModel and requires 'smolagents[transformers]'. The feature list also names Ollama for local runs, but this block does not include an Ollama constructor. Leave that out until a page you are following shows it.

What to run, then what to read

Run the first snippet before you add a tool: the toolkit install, InferenceClientModel() with no arguments, CodeAgent with an empty tools list, and the sum task. When that returns, add DuckDuckGoSearchTool exactly as the second example and use the Paris weather task. After that, stay on the smolagents docs. The index page points to the Guided Tour if this is your first time with agents, the Installation Guide for models and tools, the custom-tools tutorial, the secure code execution page, and the multi-agent tutorial. Every command above comes from that index.

Sources