huggingface /smolagents
🤗 smolagents: a barebones library for agents that think in code.
★ 30,384⑂ 3,221👁 137⑃ 2,035● 984▤ 36
+16
日增长
+185
周增长
+585
月增长
30,384
stars
3,221
forks
137
watchers
2,035
prs
984
issues
36
releases
README
--
Agents that think in code!
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 (see agents.py). We kept abstractions to their minimal shape above raw code!
🧑💻 First-class support for Code Agents. Our CodeAgent writes its actions in code (as opposed to "agents being used to write code"). To make it secure, we support executing in sandboxed environments via Blaxel, E2B, Modal, or Docker.
🤗 Hub integrations: you can share/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 local transformers or ollama model, one of many providers on the Hub, or any model from OpenAI, Anthropic and many others via our LiteLLM integration.
👁️ Modality-agnostic: Agents support text, vision, video, even audio inputs! Cf this tutorial for vision.
🛠️ Tool-agnostic: you can use tools from any MCP server, from LangChain, you can even use a Hub Space as a tool.
Full documentation can be found here.
[!NOTE]
Check out our launch blog post to learn more about smolagents!
Quick demo
First install the package with a default set of tools:
bash
pip install "smolagents[toolkit]"
Then define your agent, give it the tools it needs and run it!
py
from smolagents import CodeAgent, WebSearchTool, InferenceClientModel
model = 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?")
https://github.com/user-attachments/assets/84b149b4-246c-40c9-a48d-ba013b08e600
You can even share your agent to the Hub, as a Space repository:
py
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.
InferenceClientModel, gateway for all inference providers supported on HF
py
from smolagents import InferenceClientModel
model = InferenceClientModel(
model_id="deepseek-ai/DeepSeek-R1",
provider="together",
)
LiteLLM to access 100+ LLMs
py
from smolagents import LiteLLMModel
model = LiteLLMModel(
model_id="anthropic/claude-4-sonnet-latest",
temperature=0.2,
api_key=os.environ["ANTHROPIC_API_KEY"]
)
OpenAI-compatible servers: Together AI
py
import os
from smolagents import OpenAIModel
model = OpenAIModel(
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.
)
OpenAI-compatible servers: OpenRouter
py
import os
from smolagents import OpenAIModel
model = OpenAIModel(
model_id="openai/gpt-4o",
api_base="https://openrouter.ai/api/v1", Leave this blank Top issues
#201Repeatedly getting "Error in code parsing: Your code snippet is invalid"39 comments · 2025-01-15#2117ENH: Add pre-tool-call authorization layer to MultiStepAgent33 comments · 2026-03-23#2654ENH: [Feature] Governance middleware hooks for tool/code execution (PII blocking, cost caps, tool authorization)16 comments · 2026-08-18#153Does smolagents offer structured outputs (constrained decoding not implicit)15 comments · 2025-01-11#805userinputtool() Prompts Not Displaying in Gradio Interface12 comments · 2025-02-26#655[BUG] Sambanova, Groq and Cerebras models not found after update to 1.9.112 comments · 2025-02-14#1460Feature Proposal: MCP Resource Support11 comments · 2025-06-20#1159[BUG] `ValueError: I/O operation on closed pipe` `with ToolCollection.from_mcp(...) as tool_collection: ` using StdioServer11 comments · 2025-04-08
Discussions
#3174Chopper: a small open model that cuts only the needed sentences out of retrieved text0 comments · 2026-11-15#3172187 of 189 pages follow dark mode: a small interactive check from ArtiGram0 comments · 2026-11-14#3171epistemic-guard: Catch unexecuted tool claims in Python on CPU (~11 ms, 0 VRAM, MIT)2 comments · 2026-11-14#3167Approval, spend caps and safe retries for CodeAgent tools: free MIT patterns1 comments · 2026-11-13#3158mcp-slim: Zero-dependency MCP stdio proxy for smolagents ToolCollection.from_mcp (-50% to -98% tokens & SecretGuard)0 comments · 2026-11-12#3122Sandbox containment and revoked tool authority: ARQUIA-EVAL-001 open fixture0 comments · 2026-11-07#3087Carbon Forge over MCP: a shared, versioned record smolagents can read and write0 comments · 2026-10-28#3086OpenAIModel + any OpenAI-compatible endpoint: when to use ToolCallingAgent vs CodeAgent, and which knobs fix gateway quirks0 comments · 2026-10-28
Latest release
v1.26.0 v1.26.0 2026-05-29What's Changed Bump dev version: v1.26.0.dev0 by @albertvillanova in https://github.com/huggingface/smolagents/pull/2273 Add new possible error message to test of LiteLLM providers w/o key by @albertvillanova in https://github.com/huggingface/smolagents/pull/2275 Fix typo cleanups across docs, examples, and tests by @luojiyin1987 in https://github.com/huggingface/smolagents/pull/2208 fix: correct f-string escaping in ToolSerializer.dumps error message by @Ricardo-M-L in https://github.com/huggingface/smolagents/pull/2134 Revert fix: correct f-string escaping by @albertvillanova in ht