# smolagents: features, protocols, quickstart

## TL;DR

smolagents is a compact Python agent library from Hugging Face whose main CodeAgent expresses each action as a Python snippet instead of a JSON tool call. It supports manager agents that delegate to named sub-agents, MCP tools and remote sandboxes. It suits Python developers who want a small, readable codebase over a large framework.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python |
| License | Apache-2.0 |
| Pricing model | Open source, free |
| Orchestration pattern | Supervisor |
| GitHub stars | 29,614 (as of 2026-10-01) |
| GitHub forks | 3,017 |
| Last push | 2026-09-30 |
| Latest release | v1.26.0 |
| Repository | [huggingface/smolagents](https://github.com/huggingface/smolagents) |
| Website | [huggingface.co](https://huggingface.co/docs/smolagents) |
| Documentation | [huggingface.co](https://huggingface.co/docs/smolagents/index) |
| Last verified | 2026-09-30 |

## Key features

- Two agent types: CodeAgent writes each step as Python code, ToolCallingAgent emits structured JSON tool calls. ([source](https://huggingface.co/docs/smolagents/guided_tour))
- Multi-agent setups by passing named agents with a description to a manager agent's managed_agents argument. ([source](https://huggingface.co/docs/smolagents/examples/multiagents))
- MCPClient loads tools from stdio or Streamable HTTP MCP servers, including structured tool output. ([source](https://huggingface.co/docs/smolagents/tutorials/tools))
- Agent-generated code can run in Blaxel, E2B, Modal or Docker sandboxes via executor_type. ([source](https://huggingface.co/docs/smolagents/tutorials/secure_code_execution))
- Agents and tools can be pushed to and loaded from the Hugging Face Hub; GradioUI gives a chat front end. ([source](https://huggingface.co/docs/smolagents/guided_tour))
- Runs are traced through OpenTelemetry instrumentation, with Phoenix and Langfuse examples. ([source](https://huggingface.co/docs/smolagents/tutorials/inspect_runs))
- Step memory can be replayed with agent.replay() and edited in place between steps. ([source](https://huggingface.co/docs/smolagents/tutorials/memory))

## Architecture and orchestration pattern

Pattern: Supervisor.

Each agent runs a ReAct-style loop: the model reads the task plus prior steps, proposes an action, the framework executes it and appends the observation, and the loop stops when the agent calls `final_answer` or hits `max_steps`. In a `CodeAgent` the action is a Python snippet run by an interpreter or remote executor; in a `ToolCallingAgent` it is a JSON tool call. An optional `planning_interval` inserts periodic planning steps.

Multi-agent work is hierarchical. A sub-agent gets a `name` and `description` and is passed to a manager through `managed_agents`; the manager then calls it much like a tool and receives its result. There is no shared blackboard or graph definition.

State lives in `agent.memory`, an ordered list of typed steps (system prompt, task, planning, action). Calling `run(..., reset=False)` keeps that memory for a follow-up run. No built-in long-term or cross-session store is documented.

### Human in the loop

The docs show human review through `step_callbacks`: a callback registered for `PlanningStep` pauses the run after a plan is written so a person can approve, edit or cancel it, and `run(task, reset=False)` resumes with memory intact. A running agent can be stopped with `agent.interrupt()` (the guided tour suggests wiring it to a button in GradioUI), and memory steps can be edited before the next step. No built-in per-tool approval gate is documented.

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://huggingface.co/docs/smolagents/tutorials/tools) | Client support: MCPClient (install the mcp extra) loads tools from stdio and Streamable HTTP MCP servers into an agent. |
| A2A | Unknown (checked 2026-09-30) | — | Searched README, docs source (docs/source/en), GitHub code search and issues for a2a / agent2agent; nothing official found. |
| AG-UI | Unknown (checked 2026-09-30) | — | Searched README, docs source, GitHub code search for ag-ui / agui, and the AG-UI README integration list; smolagents is not listed. |

## Best for

- Python developers who want agents that compose several tool calls inside one code action.
- Web research agents built as a manager plus search sub-agent, as in the official multi-agent example. ([shortlist](https://multiagentguide.top/best/research-agents.md))
- Running agents on local models through TransformersModel or Ollama via LiteLLM. ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))
- Learning how an agent loop works from a small codebase (agents.py is under 1,000 lines per the README).

## Not for

- Teams that need a TypeScript, Java or .NET SDK.
- Executing untrusted model-written code without setting up a remote or container sandbox.
- Designs that need explicit graphs, persisted checkpoints or long-term memory out of the box.

## Quickstart

```sh
pip install "smolagents[toolkit]"
```

Install verified 2026-09-30 (uv venv, Python 3.12.13, macOS arm64: `uv pip install smolagents[toolkit]` ok, `from smolagents import CodeAgent` ok, smolagents 1.26.0. Packages came from the mirrors.aliyun.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```python
from smolagents import CodeAgent, ToolCallingAgent, InferenceClientModel, WebSearchTool

model = InferenceClientModel()  # uses HF_TOKEN from the environment

searcher = ToolCallingAgent(
    tools=[WebSearchTool()],
    model=model,
    name="searcher",
    description="Looks things up on the web and reports short findings.",
    max_steps=6,
)

lead = CodeAgent(tools=[], model=model, managed_agents=[searcher])
print(lead.run("In which year was Python 3.0 released, and how many years before 2026 was that?"))
```

### Common pitfalls

- Requires Python 3.10 or newer.
- `InferenceClientModel` needs an `HF_TOKEN` for Hugging Face Inference Providers; other providers need their own keys.
- Managed agents must have both `name` and `description`, or the manager cannot call them.
- `CodeAgent` only allows whitelisted imports; add more with `additional_authorized_imports`.
- The default `LocalPythonExecutor` is not a security sandbox; use Blaxel, E2B, Modal or Docker for untrusted code.
- MCP tools need the extra: `pip install "smolagents[mcp]"`.
- With Ollama through `LiteLLMModel`, the guided tour warns that Ollama's default 2048-token context fails and sets `num_ctx=8192`.

Official quickstart: https://huggingface.co/docs/smolagents/installation

## Pros

- Small core: the README states the main agent logic in agents.py is under 1,000 lines, which keeps it readable and hackable. ([source](https://github.com/huggingface/smolagents))
- Model-agnostic: model classes cover HF Inference Providers, LiteLLM, OpenAI-compatible servers, local transformers, Azure and Bedrock. ([source](https://huggingface.co/docs/smolagents/guided_tour))
- Four documented remote or container sandboxes (Blaxel, E2B, Modal, Docker) for running generated code. ([source](https://huggingface.co/docs/smolagents/tutorials/secure_code_execution))
- Documented human-in-the-loop pattern for approving or editing plans mid-run. ([source](https://huggingface.co/docs/smolagents/examples/plan_customization))
- OpenTelemetry-based tracing with worked examples for Phoenix and Langfuse. ([source](https://huggingface.co/docs/smolagents/tutorials/inspect_runs))

## Cons

- The built-in LocalPythonExecutor is explicitly not a security boundary; an open issue reports a sandbox escape via ctypes. ([source](https://github.com/huggingface/smolagents/issues/2094))
- Sandboxing only the code snippets (executor_type) does not support multi-agent setups, per the secure execution guide. ([source](https://huggingface.co/docs/smolagents/tutorials/secure_code_execution))
- An open bug reports managed-agent hierarchies with two levels not working. ([source](https://github.com/huggingface/smolagents/issues/1061))
- An open bug reports managed agents sharing state when run in parallel. ([source](https://github.com/huggingface/smolagents/issues/1781))
- Python only; no official SDK in other languages is documented. ([source](https://huggingface.co/docs/smolagents/installation))

## Alternatives

- [Pydantic AI](https://multiagentguide.top/tools/pydantic-ai.md) ([smolagents vs Pydantic AI](https://multiagentguide.top/compare/smolagents-vs-pydantic-ai.md))
- [OpenAI Agents SDK (Python)](https://multiagentguide.top/tools/openai-agents-sdk.md)
- [Agno](https://multiagentguide.top/tools/agno.md)
- [LangGraph](https://multiagentguide.top/tools/langgraph.md)
- [CAMEL](https://multiagentguide.top/tools/camel.md)

## FAQ

### Does smolagents support MCP?

Yes, as a client. With the mcp extra installed, MCPClient loads tools from stdio or Streamable HTTP MCP servers and hands them to an agent. A2A and AG-UI support were not found in the official docs.

### Is smolagents free?

The library is Apache-2.0 licensed with no paid tier of its own. Model calls are billed by whichever provider you configure; Hugging Face Inference Providers need an HF_TOKEN.

### What language is smolagents written in?

Python. The installation guide requires Python 3.10 or newer, and no SDK for other languages is documented.

### How do multiple agents work together in smolagents?

Through a hierarchy: sub-agents with a name and description are passed to a manager agent via managed_agents, and the manager calls them as it would call a tool.

### Is it safe to let a CodeAgent run code locally?

The project warns that LocalPythonExecutor is not a security boundary. For untrusted code the docs recommend Blaxel, E2B, Modal or Docker executors.

## Sources

- [smolagents GitHub repository (README)](https://github.com/huggingface/smolagents)
- [smolagents documentation](https://huggingface.co/docs/smolagents/index)
- [Installation options](https://huggingface.co/docs/smolagents/installation)
- [Guided tour](https://huggingface.co/docs/smolagents/guided_tour)
- [Tools tutorial (MCPClient)](https://huggingface.co/docs/smolagents/tutorials/tools)
- [Orchestrate a multi-agent system](https://huggingface.co/docs/smolagents/examples/multiagents)
- [Human-in-the-loop plan customization](https://huggingface.co/docs/smolagents/examples/plan_customization)
- [Manage your agent's memory](https://huggingface.co/docs/smolagents/tutorials/memory)
- [Secure code execution](https://huggingface.co/docs/smolagents/tutorials/secure_code_execution)
- [Inspecting runs with OpenTelemetry](https://huggingface.co/docs/smolagents/tutorials/inspect_runs)
- [Issue #1061: two-level managed agent hierarchy](https://github.com/huggingface/smolagents/issues/1061)
- [Issue #1781: managed agents share state in parallel runs](https://github.com/huggingface/smolagents/issues/1781)
- [Issue #2094: sandbox escape via ctypes in LocalPythonExecutor](https://github.com/huggingface/smolagents/issues/2094)

## Unknown fields

protocols.a2a and protocols.agui are unknown: README, the docs source under docs/source/en, GitHub code search and issue search for a2a/agent2agent/ag-ui/agui returned nothing official, and the AG-UI README integration list does not include smolagents.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-10-01. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/smolagents