How to run a first smolagents agent

Hugging Face’s guided tour for smolagents shows how to build an agent, run it, and adjust it for a use case. The library comes with two agent classes. The difference is how actions are specified and executed: code generation versus structured tool calling. A first run needs a model and a tools list. That list can be empty.

Start with CodeAgent

The tour’s minimal construction uses CodeAgent. That class generates tool calls as Python snippets, and tools are exposed as Python functions. The tour calls this highly expressive: complex logic and control flow, combining tools, looping, transforming, and reasoning. It is flexible because every action does not have to be predefined, and the agent can dynamically generate new actions or tools. The tour also treats it as a fit for multi-step problems or dynamic logic.

The listed limitations are syntax errors and exceptions, outputs that are less predictable or unsafe, and the need for a secure execution environment.

Use CodeAgent when you need reasoning, chaining, or dynamic composition, or when the tools are functions that can be combined, such as parsing, math, and querying. The tour describes that role as a problem solver or programmer.

Construct a model and call run

Initializing a minimal agent takes two arguments. model is the text-generation model that powers the agent. The agent is a system that uses an LLM as its engine, not the LLM alone. tools is a list of tools and can be empty. Pass add_base_tools=True to add the default toolbox on top of your list.

The Inference Providers example uses InferenceClientModel. It leverages a huggingface_hub.InferenceClient under the hood and supports Inference Providers on the Hub. Inference Providers need an HF_TOKEN to authenticate. A free Hugging Face account already comes with included credits. To access gated models, or to raise rate limits with a PRO account, set the environment variable HF_TOKEN or pass token when you initialize InferenceClientModel. The tour says you can get the token from your settings page. A comment in the example also says you can omit model_id and use a default model. This page does not name that default.

Copy the documented construction. Leave the token placeholder until you replace it:

from smolagents import CodeAgent, InferenceClientModel

model_id = "meta-llama/Llama-3.3-70B-Instruct"

model = InferenceClientModel(model_id=model_id, token="<YOUR_HUGGINGFACEHUB_API_TOKEN>") # You can choose to not pass any model_id to InferenceClientModel to use a default model
# you can also specify a particular provider e.g. provider="together" or provider="sambanova"
agent = CodeAgent(tools=[], model=model, add_base_tools=True)

agent.run(
    "Could you give me the 118th number in the Fibonacci sequence?",
)

agent.run receives the task. By default an agent continues until it calls the final_answer function or reaches the maximum number of steps. The tour does not state that maximum here.

The same model argument can instead be a TransformersModel, LiteLLMModel, AzureOpenAIModel, AmazonBedrockModel, or MLXModel. All model classes accept extra keyword arguments at instantiation, such as temperature, max_tokens, and top_p, and forward them to the underlying completion calls. Skip those until the first prompt works.

If smolagents is installed with the toolkit extra, add_base_tools=True adds a default toolbox: DuckDuckGo web search, a Python code interpreter, and a Whisper-Turbo transcriber. The interpreter is added only on ToolCallingAgent, because a code agent already executes Python. The tour’s search-tool example begins with the comment # !pip install 'smolagents[toolkit]'.

Local execution, and the import warning

By default, the Python code execution is done in your local environment. The tour says this should be safe because the only functions that can be called are the tools you provided, especially if those are only tools by Hugging Face, and a set of predefined safe functions like print or functions from the math module. The interpreter also does not allow imports by default outside of a safe list. Submodule access is forbidden unless that submodule is explicitly authorized in the import list.

You authorize more modules by passing additional_authorized_imports, a list of strings, when you initialize CodeAgent. Do not do that on a first run. The tour’s warning is explicit: "The LLM can generate arbitrary code that will then be executed: do not add any unsafe imports!" Execution stops at any code trying to perform an illegal operation, or if the generated code raises a regular Python error.

Blaxel, E2B, or Docker can replace the local interpreter. For Blaxel, set the BL_API_KEY and BL_WORKSPACE environment variables, then pass executor_type="blaxel". For E2B, set E2B_API_KEY, then pass executor_type="e2b". For Docker, pass executor_type="docker". The tour points to its code-execution tutorial for that setup. Keep the first agent on the local default, with no extra imports.

Take the shorter ToolCallingAgent path

ToolCallingAgent writes tool calls as structured JSON. The tour describes that as the common format used in many frameworks, including the OpenAI API, so tools can be called without executing code. Tools are defined with a JSON schema: name, description, parameter types, and similar fields. An example of that shape in the tour is:

{
  "tool_call": {
    "name": "search_docs",
    "arguments": {
      "query": "What is the capital of France?"
    }
  }
}

The tour lists this path as more reliable and safer: outputs are structured and validated, arguments are strictly checked, and arbitrary code does not run. It is also easier to map to external APIs. The limitations are low expressivity, no easy way to combine or transform results or to run complex control flow, and no code synthesis. Every action has to be defined in advance.

Use ToolCallingAgent for simple, atomic tools, such as calling an API or fetching a document, when you want reliability and clear validation. The tour compares that role to a dispatcher or controller.

It is initialized like CodeAgent, without additional_authorized_imports, because it does not execute code. The documented snippet expects a model you have already built, and it uses WebSearchTool from the toolkit extra:

from smolagents import ToolCallingAgent, WebSearchTool

agent = ToolCallingAgent(tools=[WebSearchTool()], model=model)
agent.run("Could you get me the title of the page at url 'https://huggingface.co/blog'?")

Each tool needs a name, a description, input types and descriptions, and an output type. On initialization those attributes are written into the agent’s system prompt so the model knows what it can call.

Use the smolagent CLI for one prompt

The guided tour’s command-line examples use smolagent. One form takes a prompt and options. The other launches when no prompt is provided and guides argument selection:

# Run with direct prompt and options
smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7."  --model-type "InferenceClientModel" --model-id "Qwen/Qwen2.5-Coder-32B-Instruct" --imports "pandas numpy" --tools "web_search"

# Run in interactive mode: launches when no prompt is provided, will guide you through argument selection
smolagent

The imports in that command are pandas and numpy, as written. Do not extend that imports option with anything unsafe. Whenever generated code will run, keep the tour’s warning in mind: do not add any unsafe imports.

Inspect the run

After a run, agent.logs stores fine-grained logs. Every step is a dictionary appended to that list. agent.write_memory_to_messages() writes memory as chat messages: the system prompt and task in separate messages, then for each step the LLM output and the tool-call output. Use it for a higher-level view. Not every log is transcribed.

Run the Fibonacci prompt with the CodeAgent example before you change imports or the executor. If that call returns, reuse the same model in the ToolCallingAgent snippet, or run smolagent with no prompt and follow the interactive setup. Before you authorize extra imports or leave the local interpreter, read the code-execution tutorial linked from the guided tour.

Sources

• Agents - Guided tour