Repository files navigation

smolagents is a library that enables you to run powerful agents in a few lines of code. It offers:

✨Simplicity: the logic for agents fits in ~1,000 lines of code (seeagents.py). We kept abstractions to their minimal shape above raw code!

🧑‍💻First-class support for Code Agents. OurCodeAgent writes its actions in code (as opposed to "agents being used to write code"). To make it secure, we support executing in sandboxed environments viaE2B, Docker, or Pyodide+Deno WebAssembly sandbox.

🤗Hub integrations: you canshare/pull tools or agents to/from the Hub for instant sharing of the most efficient agents!

🌐Model-agnostic: smolagents supports any LLM. It can be a localtransformers orollama model, one ofmany providers on the Hub, or any model from OpenAI, Anthropic and many others via ourLiteLLM integration.

👁️Modality-agnostic: Agents support text, vision, video, even audio inputs! Cfthis tutorial for vision.

🛠️Tool-agnostic: you can use tools from anyMCP server, fromLangChain, you can even use aHub Space as a tool.

Full documentation can be foundhere.

First install the package with a default set of tools:

pip install smolagents[toolkit]

Then define your agent, give it the tools it needs and run it!

fromsmolagentsimportCodeAgent,WebSearchTool,InferenceClientModelmodel=InferenceClientModel()agent=CodeAgent(tools=[WebSearchTool()],model=model,stream_outputs=True)agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")

You can even share your agent to the Hub, as a Space repository:

agent.push_to_hub("m-ric/my_agent")# agent.from_hub("m-ric/my_agent") to load an agent from Hub

Our library is LLM-agnostic: you could switch the example above to any inference provider.

fromsmolagentsimportInferenceClientModelmodel=InferenceClientModel(model_id="deepseek-ai/DeepSeek-R1",provider="together",)

fromsmolagentsimportLiteLLMModelmodel=LiteLLMModel(model_id="anthropic/claude-3-5-sonnet-latest",temperature=0.2,api_key=os.environ["ANTHROPIC_API_KEY"])

importosfromsmolagentsimportOpenAIServerModelmodel=OpenAIServerModel(model_id="deepseek-ai/DeepSeek-R1",api_base="https://api.together.xyz/v1/",# Leave this blank to query OpenAI servers.api_key=os.environ["TOGETHER_API_KEY"],# Switch to the API key for the server you're targeting.)

importosfromsmolagentsimportOpenAIServerModelmodel=OpenAIServerModel(model_id="openai/gpt-4o",api_base="https://openrouter.ai/api/v1",# Leave this blank to query OpenAI servers.api_key=os.environ["OPENROUTER_API_KEY"],# Switch to the API key for the server you're targeting.)

fromsmolagentsimportTransformersModelmodel=TransformersModel(model_id="Qwen/Qwen2.5-Coder-32B-Instruct",max_new_tokens=4096,device_map="auto")

importosfromsmolagentsimportAzureOpenAIServerModelmodel=AzureOpenAIServerModel(model_id=os.environ.get("AZURE_OPENAI_MODEL"),azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),api_key=os.environ.get("AZURE_OPENAI_API_KEY"),api_version=os.environ.get("OPENAI_API_VERSION")    )

importosfromsmolagentsimportAmazonBedrockServerModelmodel=AmazonBedrockServerModel(model_id=os.environ.get("AMAZON_BEDROCK_MODEL_ID") )

You can run agents from CLI using two commands:smolagent andwebagent.

smolagent is a generalist command to run a multi-stepCodeAgent that can be equipped with various tools.

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"

Meanwhilewebagent is a specific web-browsing agent usinghelium (read morehere).

For instance:

webagent"go to xyz.com/men, get to sale section, click the first clothing item you see. Get the product details, and the price, return them. note that I'm shopping from France" --model-type"LiteLLMModel" --model-id"gpt-4o"

OurCodeAgent works mostly like classical ReAct agents - the exception being that the LLM engine writes its actions as Python code snippets.

flowchart TB    Task[User Task]    Memory[agent.memory]    Generate[Generate from agent.model]    Execute[Execute Code action - Tool calls are written as functions]    Answer[Return the argument given to 'final_answer']    Task -->|Add task to agent.memory| Memory    subgraph ReAct[ReAct loop]        Memory -->|Memory as chat messages| Generate        Generate -->|Parse output to extract code action| Execute        Execute -->|No call to 'final_answer' tool => Store execution logs in memory and keep running| Memory    end        Execute -->|Call to 'final_answer' tool| Answer    %% Styling    classDef default fill:#d4b702,stroke:#8b7701,color:#ffffff    classDef io fill:#4a5568,stroke:#2d3748,color:#ffffff        class Task,Answer io

Actions are now Python code snippets. Hence, tool calls will be performed as Python function calls. For instance, here is how the agent can perform web search over several websites in one single action:

requests_to_search= ["gulf of mexico america","greenland denmark","tariffs"]forrequestinrequests_to_search:print(f"Here are the search results for{request}:",web_search(request))

Writing actions as code snippets is demonstrated to work better than the current industry practice of letting the LLM output a dictionary of the tools it wants to call:uses 30% fewer steps (thus 30% fewer LLM calls) andreaches higher performance on difficult benchmarks. Head toour high-level intro to agents to learn more on that.

Especially, since code execution can be a security concern (arbitrary code execution!), we provide options at runtime:

• a secure python interpreter to run code more safely in your environment (more secure than raw code execution but still risky)
• a sandboxed environment usingE2B or Docker (removes the risk to your own system).

AlongsideCodeAgent, we also provide the standardToolCallingAgent which writes actions as JSON/text blobs. You can pick whichever style best suits your use case.

We strived to keep abstractions to a strict minimum: the main code inagents.py has <1,000 lines of code.Still, we implement several types of agents:CodeAgent writes its actions as Python code snippets, and the more classicToolCallingAgent leverages built-in tool calling methods. We also have multi-agent hierarchies, import from tool collections, remote code execution, vision models...

By the way, why use a framework at all? Well, because a big part of this stuff is non-trivial. For instance, the code agent has to keep a consistent format for code throughout its system prompt, its parser, the execution. So our framework handles this complexity for you. But of course we still encourage you to hack into the source code and use only the bits that you need, to the exclusion of everything else!

We've createdCodeAgent instances with some leading models, and compared them onthis benchmark that gathers questions from a few different benchmarks to propose a varied blend of challenges.

Find the benchmarking code here for more detail on the agentic setup used, and see a comparison of using LLMs code agents compared to vanilla (spoilers: code agents works better).

This comparison shows that open-source models can now take on the best closed models!

Security is a critical consideration when working with code-executing agents. Our library provides:

• Sandboxed execution options usingE2B, Docker, or Pyodide+Deno WebAssembly sandbox
• Best practices for running agent code securely

For security policies, vulnerability reporting, and more information on secure agent execution, please see ourSecurity Policy.

Everyone is welcome to contribute, get started with ourcontribution guide.

If you usesmolagents in your publication, please cite it by using the following BibTeX entry.

@Misc{smolagents,title ={`smolagents`: a smol library to build great agentic systems.},author ={Aymeric Roucher and Albert Villanova del Moral and Thomas Wolf and Leandro von Werra and Erik Kaunismäki},howpublished ={\url{https://github.com/huggingface/smolagents}},year ={2025}}