# huggingface/smolagents architecture

> Architecture diagram of the GitHub repository huggingface/smolagents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/huggingface/smolagents
- Repository: https://github.com/huggingface/smolagents

## Overview

smolagents is a Python library for building and running multimodal, tool-using LLM agents. The principal workflow accepts a task through the Python API or CLI, lets an agent plan and request model responses, dispatches tool calls or code for execution, and returns a result while recording run steps. Major documented branches include browser agents, model and tool integrations, Hub sharing, and sandboxed code execution. Edges are limited to relationships visible in excerpts, the source index, or README; some documented integrations have unsampled implementations.

Main entry points: [`src/smolagents/agents.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py) (Agent runtime), [`src/smolagents/tools.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/tools.py) (Tool framework), [`src/smolagents/remote_executors.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py) (Remote executors), [`src/smolagents/models.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/models.py) (Model adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Agent orchestration"]
  node_agent["Agent runtime<br/>[agents.py]"]
  node_memory["Run memory<br/>[memory.py]"]
  node_monitor["Monitoring<br/>[monitoring.py]"]
end

subgraph group_execution["Tools and execution"]
  node_tools["Tool framework<br/>[tools.py]"]
  node_defaults["Default tools<br/>[default_tools.py]"]
  node_validation["Tool validation<br/>[tool_validation.py]"]
  node_hints["Type hints"]
  node_localexec["Local code executor"]
  node_remoteexec["Remote executors"]
end

subgraph group_integrations["Models and integrations"]
  node_models["Model adapters<br/>[models.py]"]
  node_mcp["MCP client<br/>[mcp_client.py]"]
  node_types["Multimodal types<br/>[agent_types.py]"]
  node_serialization["Serialization<br/>[serialization.py]"]
end

subgraph group_interfaces["Interfaces and run state"]
  node_cli["CLI<br/>[cli.py]"]
  node_browser["Web browser agent"]
  node_gradio["Gradio interface<br/>[gradio_ui.py]"]
end

node_user(("User"))
node_provider{{"LLM providers"}}
node_sandbox{{"Sandbox services"}}
node_hub{{"Hugging Face Hub"}}

node_user -->|"submits task"| node_cli
node_user -->|"submits task"| node_agent
node_user -.->|"sends messages"| node_gradio
node_cli -->|"runs agent"| node_agent
node_browser -->|"uses runtime"| node_agent
node_gradio -->|"streams run"| node_agent
node_agent -->|"requests responses"| node_models
node_models -.->|"queries model"| node_provider
node_agent -->|"dispatches calls"| node_tools
node_agent -->|"records steps"| node_memory
node_agent -->|"tracks run"| node_monitor
node_agent -->|"executes code"| node_localexec
node_agent -->|"uses executor"| node_remoteexec
node_remoteexec -.->|"runs remotely"| node_sandbox
node_tools -->|"validates tools"| node_validation
node_tools -->|"uses type hints"| node_hints
node_defaults -->|"defines tools"| node_tools
node_mcp -->|"creates tools"| node_tools
node_agent -->|"handles inputs"| node_types
node_remoteexec -->|"serializes results"| node_serialization
node_tools -.->|"loads tools"| node_hub
node_agent -.->|"shares agent"| node_hub

click node_cli "https://github.com/huggingface/smolagents/blob/main/src/smolagents/cli.py"
click node_browser "https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py"
click node_agent "https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py"
click node_memory "https://github.com/huggingface/smolagents/blob/main/src/smolagents/memory.py"
click node_monitor "https://github.com/huggingface/smolagents/blob/main/src/smolagents/monitoring.py"
click node_models "https://github.com/huggingface/smolagents/blob/main/src/smolagents/models.py"
click node_tools "https://github.com/huggingface/smolagents/blob/main/src/smolagents/tools.py"
click node_defaults "https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py"
click node_mcp "https://github.com/huggingface/smolagents/blob/main/src/smolagents/mcp_client.py"
click node_validation "https://github.com/huggingface/smolagents/blob/main/src/smolagents/tool_validation.py"
click node_hints "https://github.com/huggingface/smolagents/blob/main/src/smolagents/_function_type_hints_utils.py"
click node_localexec "https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py"
click node_remoteexec "https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py"
click node_types "https://github.com/huggingface/smolagents/blob/main/src/smolagents/agent_types.py"
click node_serialization "https://github.com/huggingface/smolagents/blob/main/src/smolagents/serialization.py"
click node_gradio "https://github.com/huggingface/smolagents/blob/main/src/smolagents/gradio_ui.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agent,node_memory,node_monitor,node_user toneBlue
class node_tools,node_defaults,node_validation,node_hints,node_localexec,node_remoteexec toneAmber
class node_models,node_mcp,node_types,node_serialization toneMint
class node_cli,node_browser,node_gradio toneRose
class node_provider,node_sandbox,node_hub toneIndigo
```

## Components

### Agent orchestration

- [Agent runtime](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py): `src/smolagents/agents.py`
- [Run memory](https://github.com/huggingface/smolagents/blob/main/src/smolagents/memory.py): `src/smolagents/memory.py`
- [Monitoring](https://github.com/huggingface/smolagents/blob/main/src/smolagents/monitoring.py): `src/smolagents/monitoring.py`

### Tools and execution

- [Tool framework](https://github.com/huggingface/smolagents/blob/main/src/smolagents/tools.py): `src/smolagents/tools.py`
- [Default tools](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py): `src/smolagents/default_tools.py`
- [Tool validation](https://github.com/huggingface/smolagents/blob/main/src/smolagents/tool_validation.py): `src/smolagents/tool_validation.py`
- [Type hints](https://github.com/huggingface/smolagents/blob/main/src/smolagents/_function_type_hints_utils.py): `src/smolagents/_function_type_hints_utils.py`
- [Local code executor](https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py): `src/smolagents/local_python_executor.py`
- [Remote executors](https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py): `src/smolagents/remote_executors.py`

### Models and integrations

- [Model adapters](https://github.com/huggingface/smolagents/blob/main/src/smolagents/models.py): `src/smolagents/models.py`
- [MCP client](https://github.com/huggingface/smolagents/blob/main/src/smolagents/mcp_client.py): `src/smolagents/mcp_client.py`
- [Multimodal types](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agent_types.py): `src/smolagents/agent_types.py`
- [Serialization](https://github.com/huggingface/smolagents/blob/main/src/smolagents/serialization.py): `src/smolagents/serialization.py`

### Interfaces and run state

- [CLI](https://github.com/huggingface/smolagents/blob/main/src/smolagents/cli.py): `src/smolagents/cli.py`
- [Web browser agent](https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py): `src/smolagents/vision_web_browser.py`
- [Gradio interface](https://github.com/huggingface/smolagents/blob/main/src/smolagents/gradio_ui.py): `src/smolagents/gradio_ui.py`

### Other components

- **User**
- **LLM providers**
- **Sandbox services**
- **Hugging Face Hub**

## Connections

- User → CLI: submits task (evidence: `README.md`)
- User → Agent runtime: submits task (evidence: `README.md`)
- User → Gradio interface: sends messages
- CLI → Agent runtime: runs agent (evidence: `src/smolagents/cli.py`)
- Web browser agent → Agent runtime: uses runtime (evidence: `src/smolagents/vision_web_browser.py`)
- Gradio interface → Agent runtime: streams run (evidence: `src/smolagents/gradio_ui.py`)
- Agent runtime → Model adapters: requests responses (evidence: `src/smolagents/agents.py`)
- Model adapters → LLM providers: queries model (evidence: `README.md`)
- Agent runtime → Tool framework: dispatches calls (evidence: `src/smolagents/agents.py`)
- Agent runtime → Run memory: records steps (evidence: `src/smolagents/agents.py`)
- Agent runtime → Monitoring: tracks run (evidence: `src/smolagents/agents.py`)
- Agent runtime → Local code executor: executes code (evidence: `src/smolagents/agents.py`)
- Agent runtime → Remote executors: uses executor (evidence: `src/smolagents/agents.py`)
- Remote executors → Sandbox services: runs remotely (evidence: `README.md`)
- Tool framework → Tool validation: validates tools (evidence: `src/smolagents/tools.py`)
- Tool framework → Type hints: uses type hints (evidence: `src/smolagents/tools.py`)
- Default tools → Tool framework: defines tools (evidence: `src/smolagents/default_tools.py`)
- MCP client → Tool framework: creates tools (evidence: `src/smolagents/mcp_client.py`)
- Agent runtime → Multimodal types: handles inputs (evidence: `src/smolagents/agents.py`)
- Remote executors → Serialization: serializes results (evidence: `src/smolagents/remote_executors.py`)
- Tool framework → Hugging Face Hub: loads tools (evidence: `README.md`)
- Agent runtime → Hugging Face Hub: shares agent (evidence: `README.md`)
