◆ AI Agent Frameworks

smolagents

v1.26.0 open-source

from smolagents import CodeAgent, FinalAnswerStep

def on_final(step: FinalAnswerStep):
    print('Final answer:', step.final_answer)

agent = CodeAgent(tools=[], model=model, step_callbacks=[on_final])
agent.run('What is 2 + 2?')
smolagents --dialog
result = agent.run('Summarize this document', return_full_result=True)
print(result.token_usage)
print(result.steps)
from smolagents.executors import DockerExecutor

with open('Dockerfile', 'rb') as f:
    executor = DockerExecutor(custom_dockerfile=f)
agent = CodeAgent(tools=[], model=model, executor=executor)
agent.run('Analyze the dataset')
from smolagents import Tool

my_tool = Tool.from_hub('lysandre/hf-model-downloads')
print(my_tool.to_code_prompt())
print(my_tool.to_tool_calling_prompt())
from smolagents import MCPClient

client = MCPClient(
    server_url='http://localhost:8080',
    adapter_kwargs={'timeout': 30, 'verify': False}
)
from smolagents import CodeAgent, HfApiModel

model = HfApiModel()
with CodeAgent(tools=[], model=model) as agent:
    result = agent.run('Compute 2 + 2')
# agent resources are released automatically on exit
from smolagents import CodeAgent, HfApiModel

model = HfApiModel()
agent = CodeAgent(tools=[], model=model)
agent.run('Print the first 5 Fibonacci numbers')
for step in agent.memory.steps:
    if hasattr(step, 'code_output'):
        print(step.code_output)
from smolagents import ApiWebSearchTool, ToolCallingAgent

search_tool = ApiWebSearchTool(headers={"Authorization": "Bearer <token>"})
agent = ToolCallingAgent(tools=[search_tool], model=model)
agent.run("What are the latest CVEs affecting OpenSSH?")
from smolagents import CodeAgent

agent = CodeAgent(model=model, tools=[...])
run_result = agent.run('Find the top 5 CVEs disclosed this week.')
print(run_result)
smolagents --api_base http://localhost:8000 --api_key sk-localkey
from smolagents import ToolCollection

tools = ToolCollection.from_mcp("<mcp_server_url>", trust_remote_code=True)
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[],
    model=HfApiModel(),
    additional_authorized_imports=["numpy"],  # numpy.random, numpy.linalg, etc. are now also authorized
)
from smolagents import CodeAgent, VLLMModel

model = VLLMModel(model_id="meta-llama/Llama-3.1-8B-Instruct")
agent = CodeAgent(tools=[], model=model)
agent.run("Summarize the OWASP Top 10 for 2024.")
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(tools=[], model=HfApiModel(), executor="docker")
agent.run("List all files in /tmp and return their sizes.")
smolagents --api-base https://my-llm-proxy.example.com/v1 --api-key $MY_API_KEY 'Summarize the latest news on AI safety'
from smolagents import CodeAgent, MLXModel

model = MLXModel('mlx-community/Qwen2.5-Coder-7B-Instruct-4bit')
agent = CodeAgent(tools=[], model=model)
agent.run('Compute the first 10 Fibonacci numbers.')
from smolagents import CodeAgent, GradioUI, HfApiModel

agent = CodeAgent(tools=[], model=HfApiModel())
GradioUI(agent).launch(share=True)
from smolagents import CodeAgent, HfApiModel

model = HfApiModel()
sub_agent = CodeAgent(tools=[], model=model, name='researcher', description='Searches and summarizes web content')
orchestrator = CodeAgent(tools=[sub_agent], model=model)
webagent "Find me a cheap train from Paris to Torino before Thursday"
agent.replay()
from smolagents import DuckDuckGoSearchTool

tool = DuckDuckGoSearchTool(ddgs_kwargs={"proxies": "http://proxy.corp:8080", "region": "us-en"})
results = tool("latest CVE disclosures")
from smolagents import TransformersModel

model = TransformersModel(
    model_id="org/custom-model",
    trust_remote_code=True
)
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[],
    model=HfApiModel(),
    verbosity_level=2  # 0=silent, 1=normal, 2=verbose
)
agent.run('Summarize the latest CVE advisories.')
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[],
    model=HfApiModel(),
    additional_authorized_imports=['*']
)
agent.run('Use the requests library to fetch and parse the NVD feed.')
from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="meta-llama/Llama-3-8b-instruct",
    api_base="http://localhost:8000/v1",
    api_key="none"
)

Summary

smolagents is an open-source library that enables running agents via code, licensed under the Apache License, Version 2.0. It requires no payment to use and operates as a library imported into other code, targeting application developers. The README calls it an alternative to specialized agent frameworks, and it sits within the ai-agent-frameworks category. The project was last updated via a release badge, indicating ongoing maintenance.

What smolagents answers

What level of code is required to define agent logic?

agent logic fits in a relatively small amount of code.

What kind of dependencies are required to execute agent functions?

it operates as a library imported into existing code.

What are the prerequisites for running the agents?

the only requirement is the library being imported into code.

How easily can I adapt existing code structures?

the library is designed to fit into application code.

What is the scope of the agent's execution environment?

the agent runs within the application code where it is imported.

What is the legal framework governing usage?

it is distributed under the Apache License, Version 2.0.

Command line

composed command

option surface across analysed releases

options at that release added, per release removed, per release

option	found in	since	description

Values are placeholders taken from each option’s declared default. Nothing is executed here — the output shown is a recording of a run that already happened.

Release history

v1.26.0 May 29, 2026 · issue -082

smolagents v1.26.0 adds Exa as a search engine option in WebSearchTool and removes the remote WasmExecutor.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.26.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.26.0
```
- ›Adds Exa as a supported search engine option in WebSearchTool.
└──▷ BREAKING ON UPGRADE
- !The remote WasmExecutor has been removed; any setup relying on it will break on upgrade.
v1.24.0 Jan 16, 2026 · issue -213

smolagents v1.24.0 adds FinalAnswerStep callbacks, additional apply_chat_template params, and a robust Python execution timeout mechanism.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.24.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.24.0
```
└──▷ USE IT
Capture the agent's final answer in a callback — useful for logging or post-processing the result without parsing the full step stream.
python
```
from smolagents import CodeAgent, FinalAnswerStep

def on_final(step: FinalAnswerStep):
    print('Final answer:', step.final_answer)

agent = CodeAgent(tools=[], model=model, step_callbacks=[on_final])
agent.run('What is 2 + 2?')
```
- ›Adds FinalAnswerStep as a supported type in step_callbacks, enabling callbacks that fire on the agent's final answer step.
- ›Supports passing additional params to apply_chat_template, giving callers finer control over prompt formatting.
- ›Implements a robust timeout mechanism for Python code execution in the local sandbox.
- ›Coerces tool calls from external APIs into the internal ChatMessageToolCall format, broadening compatibility with third-party model APIs.
- ›Extends the no-stop-sequence model list to support gpt-5.2* model variants.
v1.23.0 Nov 17, 2025 · issue -273

smolagents v1.23.0 adds a dialog-mode CLI, Blaxel remote execution, custom Python executors, and exponential-backoff retries.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.23.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.23.0
```
└──▷ TRY IT
Run an interactive multi-turn agent session from the terminal using the new dialog mode CLI.
```
$ smolagents --dialog
```
- ›Adds dialog mode to the CLI (smolagents CLI with dialog mode), enabling interactive multi-turn conversations from the command line.
- ›Supports custom Python code executors in CodeAgent, letting practitioners plug in their own execution backend instead of the default LocalPythonExecutor.
- ›Adds Blaxel integration as a remote code execution sandbox option for CodeAgent.
- ›Adds exponential backoff with jitter for model call retries, including automatic retry on rate-limit errors.
- ›Changes the default InferenceClient model to Qwen/Qwen3-Next-80B-A3B-Thinking.
+6 moreshow less
- ›Adds support for parsing anyOf type schemas from MCP tools, broadening MCP tool compatibility.
- ›Adds support for nested dict comprehensions (dictcomp) and set comprehensions (setcomp) in LocalPythonExecutor.
- ›Optimizes comprehension evaluation in LocalPythonExecutor using a generator-based approach.
- ›Makes additional_args nullable for managed agents.
- ›Migrates vLLM structured output from guided_options_request to structured_outputs.
- ›Updates final answer checks to accept the agent instance, enabling richer validation logic.
└──▷ BREAKING ON UPGRADE
- !The default model used by InferenceClient changes to Qwen/Qwen3-Next-80B-A3B-Thinking; any code relying on the previous default model will silently switch targets on upgrade.
- !vLLM integration moves from guided_options_request to structured_outputs for structured output; configurations or wrappers that reference guided_options_request will break.
v1.22.0 Sep 25, 2025 · issue -325

smolagents v1.22.0 adds Modal remote execution, custom Dockerfiles, MCP structured output, and user-configurable model parameter overrides.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.22.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.22.0
```
└──▷ USE IT
Retrieve the full run result — including token usage and intermediate steps — directly from a single run call.
python
```
result = agent.run('Summarize this document', return_full_result=True)
print(result.token_usage)
print(result.steps)
```
Use a custom Dockerfile in DockerExecutor to pre-install project-specific dependencies in the sandbox environment.
python
```
from smolagents.executors import DockerExecutor

with open('Dockerfile', 'rb') as f:
    executor = DockerExecutor(custom_dockerfile=f)
agent = CodeAgent(tools=[], model=model, executor=executor)
agent.run('Analyze the dataset')
```
- ›Adds return_full_result parameter directly to the agent run method, enabling callers to retrieve the full RunResult object inline.
- ›Adds support for custom Dockerfile in DockerExecutor, letting users supply their own build context instead of the default image.
- ›Adds support for user-configurable parameter overrides for model completion parameters, allowing callers to override defaults passed to the underlying model completion call.
- ›Adds ModalRemoteExecutor for running agent code on Modal's remote infrastructure.
- ›Adds support for MCP structured output and output schema in MCP tool integrations.
+2 moreshow less
- ›Makes RunResult JSON-serializable, enabling downstream logging and persistence pipelines.
- ›Supports e2b-code-interpreter v2 in E2BExecutor.
v1.21.0 Aug 7, 2025 · issue -363

smolagents v1.21.0 adds Tool prompt methods, model_kwargs support for TransformersModel, Amazon Bedrock API key auth, and hardened LocalPythonExecutor.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.21.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.21.0
```
└──▷ USE IT
Generate a prompt string from a Tool object to inspect or inject its description into a custom prompt.
python
```
from smolagents import Tool

my_tool = Tool.from_hub('lysandre/hf-model-downloads')
print(my_tool.to_code_prompt())
print(my_tool.to_tool_calling_prompt())
```
- ›Adds model_kwargs pass-through to TransformersModel for fine-grained inference control.
- ›Adds to_code_prompt() and to_tool_calling_prompt() methods to Tool for generating prompt representations of tools.
- ›Adds Amazon Bedrock API key authentication support to AmazonBedrockServerModel.
- ›Supports passing plain dict messages as direct input to models.
- ›Hardens LocalPythonExecutor security by blocking dunder (double-underscore) method calls.
+2 moreshow less
- ›Resets agent memory when the clear button is clicked in GradioUI.
- ›Uses gr.Number for integer and number type components in launch_gradio_demo for more accurate input handling.
└──▷ BREAKING ON UPGRADE
- !The deprecated grammar parameter has been removed.
- !The deprecated token count attributes have been removed.
- !The deprecated agent logs attribute has been removed.
- !The deprecated default sse transport has been removed.
v1.20.0 Jul 10, 2025 · issue -364

smolagents v1.20.0 adds a remote Python WasmExecutor, post-planning callbacks, rate limiting across API models and search tools, and image output for Tool.from_space.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.20.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.20.0
```
└──▷ USE IT
Pass custom adapter kwargs to MCPClient when connecting to an MCP server that requires non-default transport options.
python
```
from smolagents import MCPClient

client = MCPClient(
    server_url='http://localhost:8080',
    adapter_kwargs={'timeout': 30, 'verify': False}
)
```
- ›Adds adapter_kwargs parameter to MCPClient for passing custom adapter configuration.
- ›Adds CodeOutput class as an analog to ToolOutput for structured code output from agents.
- ›Adds ApiWebSearchTool to the public __all__ export list, making it directly importable from the package.
- ›Adds import validation in the LocalPythonExecutor constructor, checking authorized imports at instantiation time rather than at execution time.
- ›Enforces type annotations on ChatMessage roles via the MessageRole enum.
+8 moreshow less
- ›Implements a remote Python WasmExecutor for sandboxed, browser-compatible agent code execution.
- ›Supports callbacks after the planning step via step_callbacks, extending the existing callback mechanism.
- ›Supports multiple callbacks per step type in the step_callbacks dict.
- ›Implements rate limit mechanism in ApiWebSearchTool and DuckDuckGoSearchTool.
- ›Sets a default api_key_name in ApiWebSearchTool, reducing required configuration.
- ›Enables image output for tools created via Tool.from_space.
- ›Supports multiple types in tool argument validation, allowing union-typed inputs.
- ›Allows markdown or custom formatting for code blocks in agent output.
v1.19.0 Jun 24, 2025 · issue -365

smolagents v1.19.0 adds managed-agent support in ToolCallingAgent, context-manager cleanup, GradioUI memory reset, and CodeAgent output tracking.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.19.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.19.0
```
└──▷ USE IT
Clean up agent resources deterministically at the end of a task using a context manager.
python
```
from smolagents import CodeAgent, HfApiModel

model = HfApiModel()
with CodeAgent(tools=[], model=model) as agent:
    result = agent.run('Compute 2 + 2')
# agent resources are released automatically on exit
```
Inspect intermediate code execution results stored in each step after a CodeAgent run.
python
```
from smolagents import CodeAgent, HfApiModel

model = HfApiModel()
agent = CodeAgent(tools=[], model=model)
agent.run('Print the first 5 Fibonacci numbers')
for step in agent.memory.steps:
    if hasattr(step, 'code_output'):
        print(step.code_output)
```
- ›Supports reset_agent_memory in GradioUI, letting users clear conversation history from the UI between sessions.
- ›Stores CodeAgent code outputs in ActionStep, making intermediate code execution results available for downstream inspection.
- ›Supports managed agents in ToolCallingAgent, enabling multi-agent orchestration through the tool-calling interface.
- ›Supports context managers for agent cleanup, allowing with blocks to reliably tear down agent resources.
- ›Transfers streaming event aggregation off the Model class, enabling more flexible streaming architectures.
v1.18.0 Jun 10, 2025 · issue -365

smolagents v1.18.0 adds parallel tool calls, streaming output, and a new ApiWebSearchTool to ToolCallingAgent
└──▷ GET THIS VERSION
```
$ git clone --branch v1.18.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.18.0
```
└──▷ USE IT
Use the new ApiWebSearchTool to give an agent live web search capability via API, with a custom header for authentication.
python
```
from smolagents import ApiWebSearchTool, ToolCallingAgent

search_tool = ApiWebSearchTool(headers={"Authorization": "Bearer <token>"})
agent = ToolCallingAgent(tools=[search_tool], model=model)
agent.run("What are the latest CVEs affecting OpenSSH?")
```
- ›Adds ApiWebSearchTool class for structured web search capabilities via API, with support for custom headers and params.
- ›Adds configurable tool_choice support in prepare_completion_kwargs for fine-grained control over model tool selection.
- ›Enables ToolCallingAgent to execute multiple tool calls in parallel, improving performance on complex multi-tool tasks.
- ›Adds streaming output support to ToolCallingAgent for improved responsiveness during multi-step tool interactions.
- ›Adds support for passing additional params to MLXModel load and tokenizer.apply_chat_template.
+1 moreshow less
- ›Makes Agent.system_prompt a read-only property.
v1.17.0 May 27, 2025 · issue -366

smolagents v1.17.0 adds structured generation in CodeAgent, RunResult from Agent.run(), and streamable HTTP MCP server support.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.17.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.17.0
```
└──▷ USE IT
Capture rich execution metadata after an agent run to inspect results programmatically.
python
```
from smolagents import CodeAgent

agent = CodeAgent(model=model, tools=[...])
run_result = agent.run('Find the top 5 CVEs disclosed this week.')
print(run_result)
```
- ›Adds optional structured generation to CodeAgent via use_structured_outputs_internally, enabling more reliable and consistent code generation patterns.
- ›Agent.run() now returns a RunResult object, providing richer metadata about agent execution.
- ›Adds support for streamable HTTP MCP servers, expanding compatibility beyond standard MCP implementations.
- ›Improves LaTeX rendering in GradioUI with extended delimiter support.
└──▷ BREAKING ON UPGRADE
- !The deprecated from_hf_api methods have been removed.
v1.16.0 May 16, 2025 · issue -366

smolagents v1.16.0 adds Bing search, custom executor functions, code timeouts, and local web agent CLI support
└──▷ GET THIS VERSION
```
$ git clone --branch v1.16.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.16.0
```
└──▷ TRY IT
Run a web agent locally against a self-hosted or third-party OpenAI-compatible endpoint instead of Hugging Face Inference.
```
$ smolagents --api_base http://localhost:8000 --api_key sk-localkey
```
- ›Adds executor_kwargs parameter to LocalPythonExecutor for initialization customization of the local Python executor.
- ›Adds timeout mechanism for code execution in the local Python executor.
- ›Enables local web agents via api_base and api_key CLI arguments.
- ›Supports passing custom functions to the local Python executor.
- ›Adds Bing as a supported search engine in WebSearchTool.
+1 moreshow less
- ›Changes the default value of the provider argument in InferenceClientModel from 'hf-inference' to 'auto', automatically selecting the first available provider per the user's configured priority.
└──▷ BREAKING ON UPGRADE
- !The default value of the provider argument in InferenceClientModel has changed from 'hf-inference' to 'auto'; existing setups relying on the hf-inference provider by default will now use whichever provider is ranked first in the user's inference-provider settings at https://hf.co/settings/inference-providers.
v1.15.0 May 7, 2025 · issue -366

smolagents v1.15.0 adds streaming model output, a LiteLLM Router model, and a new WebSearchTool.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.15.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.15.0
```
- ›Adds LiteLLMRouterModel to support LiteLLM Router as a model backend, enabling load-balanced or fallback routing across LLM providers.
- ›Adds WebSearchTool, replacing DuckDuckGoSearchTool as the recommended built-in web search tool.
- ›Adds streaming model output support, including streaming Gradio chatbot outputs; introduces ChatMessageStreamDelta as the stream delta type.
- ›Moves MCPClient to the root-level library and manages its dependencies as optional.
└──▷ BREAKING ON UPGRADE
- !CompletionDelta is renamed to ChatMessageStreamDelta; code referencing CompletionDelta will break.
v1.14.0 Apr 18, 2025 · issue -367

smolagents v1.14.0 adds MCPClient for MCP server connections, Amazon Bedrock native support, and star-pattern import authorization.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.14.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.14.0
```
- ›Adds MCPClient class to manage connections to one or more MCP servers, enabling flexible multi-server integration within smolagents.
- ›Introduces star-pattern-based import authorization for fine-grained control over which modules agents are permitted to import, improving sandboxed execution security.
- ›Adds client_kwargs pass-through for VLLMModel to supply model client parameters to the underlying vLLM client.
- ›Adds api_key argument to HfApiModel / InferenceClientModel for explicit key configuration.
- ›Implements Tool.from_dict and Agent.from_dict for deserializing tools and agents from dictionary representations.
+4 moreshow less
- ›Supports Literal type annotations in the @tool decorator for defining enum-constrained arguments.
- ›Adds custom Docker image support and enhanced configuration options for DockerExecutor.
- ›Makes MultiStepAgent an abstract class, enabling cleaner subclassing for custom agent types.
- ›Supports class docstrings and annotated assignments in LocalPythonExecutor, broadening the Python syntax handled during sandboxed code execution.
└──▷ BREAKING ON UPGRADE
- !HfApiModel is renamed to InferenceClientModel; any code importing or instantiating HfApiModel by that name will break.
v1.13.0 Apr 2, 2025 · issue -367

smolagents v1.13.0 adds agent interruption, image observation logging in the Gradio UI, and automatic submodule import authorization.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.13.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.13.0
```
└──▷ USE IT
Load an MCP tool collection while explicitly trusting remote code — useful when working with third-party MCP servers.
python
```
from smolagents import ToolCollection

tools = ToolCollection.from_mcp("<mcp_server_url>", trust_remote_code=True)
```
Authorize a top-level package and rely on automatic submodule authorization instead of listing every subpackage.
python
```
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[],
    model=HfApiModel(),
    additional_authorized_imports=["numpy"],  # numpy.random, numpy.linalg, etc. are now also authorized
)
```
- ›Adds trust_remote_code parameter to ToolCollection.from_mcp for controlling remote code trust when loading MCP tool collections.
- ›Authorizes submodule imports automatically when a top-level package is listed in additional_authorized_imports — e.g. additional_authorized_imports=["numpy"] now also permits numpy.random and other subpackages without listing each one explicitly.
- ›Adds agent interruption support, allowing a running agent to be interrupted mid-execution.
- ›Gradio UI now logs images observed by the agent during a run, making multimodal agent traces visible in the interface.
- ›Exposes the underlying Gradio app object so users can retrieve and customize it directly.
+3 moreshow less
- ›Adds WikipediaSearchTool to the default tools available in smolagents.
- ›Introduces distinct AgentToolCallError and AgentToolExecutionError exception types, separating tool-call failures from tool-execution failures.
- ›Streaming run now yields PlanningSteps, making planning activity visible during streamed agent runs.
v1.12.0 Mar 20, 2025 · issue -368

smolagents v1.12.0 adds MCP SSE server support and cuts planning step model calls in half.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.12.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.12.0
```
- ›Adds support for MCP SSE servers, enabling agents to connect to Server-Sent Events-based Model Context Protocol tool servers.
- ›Reduces model calls in planning_step from 2 to 1, halving LLM API usage per planning cycle.
v1.11.0 Mar 14, 2025 · issue -368

smolagents v1.11.0 adds VLLMModel, tightens sandbox security with module whitelisting, and expands E2B and OpenAI server options.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.11.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.11.0
```
└──▷ USE IT
Run an agent backed by a locally-served vLLM endpoint without leaving the smolagents API.
python
```
from smolagents import CodeAgent, VLLMModel

model = VLLMModel(model_id="meta-llama/Llama-3.1-8B-Instruct")
agent = CodeAgent(tools=[], model=model)
agent.run("Summarize the OWASP Top 10 for 2024.")
```
- ›Adds VLLMModel class for running inference against vLLM-served models directly from smolagents.
- ›Adds flatten_messages_as_text kwarg support to OpenAIServerModel for controlling message serialization behavior.
- ›Supports passing arbitrary kwargs to E2BExecutor Sandbox constructor, unlocking full E2B sandbox configuration from the agent layer.
- ›Forbids all modules by default in the local executor except those explicitly listed in authorized_imports, hardening sandboxed code execution.
- ›Forbids access to all dunder attributes by default in the local executor, closing a class of sandbox escape vectors.
+4 moreshow less
- ›Switches dangerous-code detection from pattern matching to module-level checking, improving accuracy of sandbox security enforcement.
- ›Adds mlx-lm to the all extras group, making Apple Silicon local inference available via a single install target.
- ›Raises agent generation errors as exceptions instead of silently swallowing them, making failure modes visible to callers.
- ›Logs agent thoughts when verbosity_level is set to high, giving practitioners full reasoning traces during debugging.
└──▷ BREAKING ON UPGRADE
- !Default model_id is removed from all model classes — callers that previously relied on the default must now pass an explicit model_id.
- !All modules are now forbidden in the local executor by default; only those in authorized_imports are allowed — existing agents that imported modules without declaring them in authorized_imports will break.
v1.10.0 Mar 5, 2025 · issue -368

smolagents v1.10.0 adds a Docker sandbox executor, Serper search support, custom final-answer handling, and --api-base/--api-key CLI arguments.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.10.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.10.0
```
└──▷ USE IT
Run an agent in a Docker sandbox to isolate arbitrary code execution from the host environment.
python
```
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(tools=[], model=HfApiModel(), executor="docker")
agent.run("List all files in /tmp and return their sizes.")
```
Point the smolagents CLI at a self-hosted or third-party OpenAI-compatible endpoint without editing config files.
```
$ smolagents --api-base https://my-llm-proxy.example.com/v1 --api-key $MY_API_KEY 'Summarize the latest news on AI safety'
```
- ›Adds executor="docker" argument to agent initialization, running generated code inside a Docker sandbox for isolated execution.
- ›Adds --api-base and --api-key arguments to the CLI for configuring model endpoints directly from the command line.
- ›Adds support for Serper as a search backend, expanding the available web-search tools.
- ›Enables custom final_answer handling in CodeAgent and via agent __init__, letting callers override how the agent surfaces its final result.
- ›Hardens the local Python interpreter by blocking access to builtins and dangerous modules at return time, reducing sandbox-escape risk without additional configuration.
+1 moreshow less
- ›Supports running an Open DeepResearch demo, including compatibility with models beyond o1 and Python ≥ 3.13 dependencies.
v1.9.0 Feb 14, 2025 · issue -369

smolagents v1.9.0 adds MLX model support, agent sharing, Gradio share passthrough, and a PromptTemplates typed dict.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.9.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.9.0
```
└──▷ USE IT
Run a smolagents CodeAgent on Apple Silicon using a local MLX-format model for fully offline, GPU-accelerated agentic workflows.
python
```
from smolagents import CodeAgent, MLXModel

model = MLXModel('mlx-community/Qwen2.5-Coder-7B-Instruct-4bit')
agent = CodeAgent(tools=[], model=model)
agent.run('Compute the first 10 Fibonacci numbers.')
```
Share an agent's Gradio UI publicly (e.g., for a demo or remote colleague) by passing the Gradio share flag through.
python
```
from smolagents import CodeAgent, GradioUI, HfApiModel

agent = CodeAgent(tools=[], model=HfApiModel())
GradioUI(agent).launch(share=True)
```
- ›Adds MLXModel class, enabling local inference on Apple Silicon via the MLX framework.
- ›Adds share parameter passthrough for Gradio, allowing agents to be exposed via a public Gradio link.
- ›Adds PromptTemplates typed dict, providing structured, type-checked prompt template definitions.
- ›Adds 'Share full agents' capability, enabling agents to be published and shared with others.
- ›Adds default value for max_new_tokens parameter in TransformersModel, removing the requirement to set it explicitly.
+3 moreshow less
- ›LiteLLMModel now auto-detects message flattening requirements based on model information.
- ›Extends the sandboxed Python interpreter to support non-bool comparison operators (e.g., returning non-boolean values from comparisons).
- ›Plan user prompt moved to YAML, making plan prompt customization accessible via configuration.
v1.8.0 Feb 7, 2025 · issue -369

smolagents v1.8.0 adds agent tree visualization, simplified managed agents via name/description attributes, and Open Deep Research.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.8.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.8.0
```
└──▷ USE IT
Turn any agent into a managed agent without wrapping it in the now-removed ManagedAgents class.
python
```
from smolagents import CodeAgent, HfApiModel

model = HfApiModel()
sub_agent = CodeAgent(tools=[], model=model, name='researcher', description='Searches and summarizes web content')
orchestrator = CodeAgent(tools=[sub_agent], model=model)
```
- ›Agents now accept name and description attributes directly to function as managed agents, replacing the removed ManagedAgents class.
- ›New visualization method to display an agent's structure as a tree.
- ›Releases Open Deep Research as a built-in example/capability.
└──▷ BREAKING ON UPGRADE
- !The ManagedAgents class has been removed; agents must now be configured as managed agents by setting name and description attributes directly on the agent object.
- !The prompts_path argument has been deleted; use prompt_templates instead.
v1.7.0 Jan 31, 2025 · issue -370

smolagents v1.7.0 adds smolagent and webagent CLI commands, a persistent memory attribute, and an agent.replay() function.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.7.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.7.0
```
└──▷ TRY IT
Quickly kick off a web research task from the terminal without writing any Python.
```
$ webagent "Find me a cheap train from Paris to Torino before Thursday"
```
Replay the last agent run to inspect its reasoning steps without triggering new LLM calls.
python
```
agent.replay()
```
- ›Adds smolagent CLI command to run agents directly from the terminal (e.g. smolagent "Your task!").
- ›Adds webagent CLI command to launch a web browser agent from the terminal (e.g. webagent "Find me a cheap train from Paris to Torino before Thursday").
- ›Adds a memory attribute to agents for persistent storage of run history across steps.
- ›Adds agent.replay() method to replay the last agent run from stored memories without making additional LLM calls.
- ›Code execution outputs are now stored to memory even when an error is raised later, improving CodeAgent performance.
+1 moreshow less
- ›Supports third-party inference providers in HfApiModel.
v1.6.0 Jan 28, 2025 · issue -370

smolagents v1.6.0 adds VLM auto-detection, DuckDuckGo kwargs, richer Gradio chatbot metrics, and makes transformers an optional dependency.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.6.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.6.0
```
└──▷ USE IT
Pass custom DDGS options (e.g. a proxy or region) directly through the tool constructor instead of patching the client manually.
python
```
from smolagents import DuckDuckGoSearchTool

tool = DuckDuckGoSearchTool(ddgs_kwargs={"proxies": "http://proxy.corp:8080", "region": "us-en"})
results = tool("latest CVE disclosures")
```
- ›Adds ddgs_kwargs parameter to the DuckDuckGoSearchTool constructor, allowing callers to pass arbitrary keyword arguments to the underlying DDGS client.
- ›Adds additional parameters support for the OpenAI client integration.
- ›Adds kwargs passthrough to gradio launch, enabling full control over Gradio server startup options.
- ›TransformersModel now auto-detects Vision-Language Models (VLMs), removing the need for manual configuration when loading a VLM.
- ›Makes transformers an optional dependency, reducing the mandatory install footprint for users who do not need local transformer inference.
+1 moreshow less
- ›Gradio chatbot now displays step duration, step number, and token counts, and supports rendering nested thoughts.
v1.5.0 Jan 24, 2025 · issue -370

smolagents v1.5.0 adds VLM support, Azure OpenAI integration, and tightened local interpreter security
└──▷ GET THIS VERSION
```
$ git clone --branch v1.5.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.5.0
```
- ›Adds Azure OpenAI support as a model backend.
- ›Adds VLM (vision-language model) support, enabling agents to process image inputs.
- ›Hardens local interpreter security: builtin functions are now blocked unless explicitly added as tools.
- ›Supports any and none tool types in tool call handling.
v1.4.1 Jan 17, 2025 · issue -370

smolagents v1.4.1 adds MCP server support via ToolCollection, kwargs passthrough to all models, and new TransformersModel options.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.4.1 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.4.1
```
└──▷ USE IT
Load a model that requires custom remote code, such as a fine-tuned model with non-standard architecture.
python
```
from smolagents import TransformersModel

model = TransformersModel(
    model_id="org/custom-model",
    trust_remote_code=True
)
```
- ›Adds trust_remote_code argument to TransformersModel for loading custom model code from remote repositories.
- ›Adds MCP (Model Context Protocol) server support via ToolCollection, making thousands of MCP-compatible tools usable with smolagents.
- ›Allows passing arbitrary kwargs to all model classes, enabling fine-grained control over inference parameters at call time.
- ›Makes the openai package an optional dependency, reducing mandatory install footprint.
- ›Adds a max-length parameter for print outputs as an agent-level setting to cap verbose tool output.
+1 moreshow less
- ›Adds a resizable option to the Gradio UI component for improved usability.
v1.3.0 Jan 15, 2025 · issue -370

smolagents v1.3.0 adds OpenTelemetry tracing, multi-GPU support, wildcard imports, and granular verbosity control.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.3.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.3.0
```
└──▷ USE IT
Control how much output an agent emits during a run — useful for CI pipelines (level 0) or deep debugging (level 2).
python
```
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[],
    model=HfApiModel(),
    verbosity_level=2  # 0=silent, 1=normal, 2=verbose
)
agent.run('Summarize the latest CVE advisories.')
```
Allow an agent to import any Python library inside its sandbox — helpful when tool code relies on arbitrary third-party packages.
python
```
from smolagents import CodeAgent, HfApiModel

agent = CodeAgent(
    tools=[],
    model=HfApiModel(),
    additional_authorized_imports=['*']
)
agent.run('Use the requests library to fetch and parse the NVD feed.')
```
- ›Adds verbosity_level=0/1/2 parameter to agent initialization, replacing the old verbose=True/False boolean for finer-grained log control.
- ›Enables unrestricted code-sandbox imports via additional_authorized_imports=['*'] on agent initialization.
- ›Adds OpenTelemetry instrumentation support for tracing and inspecting agent runs.
- ›Adds multi-GPU support for TransformersModel.
- ›Adds file upload capability to GradioUI.
└──▷ BREAKING ON UPGRADE
- !The verbose=True/False agent initialization parameter is replaced by verbosity_level=0/1/2; existing code using verbose= will need to be updated.
v1.2.0 Jan 10, 2025 · issue -370

smolagents v1.2.0 adds OpenAIServerModel, OpenTelemetry observability, Hugging Chat integration, and halves import time by dropping torch.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.2.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.2.0
```
└──▷ USE IT
Connect smolagents to a locally running vLLM or TGI server instead of a hosted model provider.
python
```
from smolagents import OpenAIServerModel

model = OpenAIServerModel(
    model_id="meta-llama/Llama-3-8b-instruct",
    api_base="http://localhost:8000/v1",
    api_key="none"
)
```
- ›Adds OpenAIServerModel class, enabling use of any OpenAI-format-compatible inference server (TGI, vLLM, etc.) as a model backend.
- ›Simplifies the Model base class to a single __call__ method: passing tools_to_call_from returns a tool call; omitting it returns a plain string.
- ›Adds OpenTelemetry support for agent observability and tracing.
- ›Integrates smolagents tools into Hugging Chat, enabling agent tool use directly from the chat interface.
- ›Halves library import time by removing the torch dependency.
v1.1.0 Jan 6, 2025 · issue -370

smolagents v1.1.0 adds max_results to DDGS tool, device param for TransformerModel, and broader LiteLLMModel kwargs support.
└──▷ GET THIS VERSION
```
$ git clone --branch v1.1.0 https://github.com/huggingface/smolagents.git
# already have the repo? check out this version:
$ git checkout v1.1.0
```
- ›Adds max_results keyword argument to the DDGS (DuckDuckGo Search) tool to control the number of results returned.
- ›Adds device parameter to TransformerModel in models.py for explicit device placement.
- ›Adds support for additional keyword arguments (kwargs) in LiteLLMModel, enabling pass-through of provider-specific options.
- ›Adds a warning to CodeAgent when required imports are missing at runtime.
└──▷ BREAKING ON UPGRADE
- !The max_iterations argument to agent initialization is renamed to max_steps; any code constructing an agent with max_iterations=... will break.

smolagents

Summary

What smolagents answers

Examples

Command line

Release history