# https://github.com/huggingface/smolagents Project Manual

Generated at: 2026-06-13 16:06:00 UTC

## Table of Contents

- [Core Agent System and ReAct Loop](#page-1)
- [Memory and State Management](#page-2)
- [Tools, Models, and Execution Backends](#page-3)
- [Deployment, CLI, UI, Security, and Extensibility](#page-4)

<a id='page-1'></a>

## Core Agent System and ReAct Loop

### Related Pages

Related topics: [Memory and State Management](#page-2), [Tools, Models, and Execution Backends](#page-3), [Deployment, CLI, UI, Security, and Extensibility](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py)
- [src/smolagents/prompts/code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/code_agent.yaml)
- [src/smolagents/prompts/toolcalling_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/toolcalling_agent.yaml)
- [src/smolagents/prompts/structured_code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/structured_code_agent.yaml)
- [src/smolagents/default_tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py)
- [examples/plan_customization/README.md](https://github.com/huggingface/smolagents/blob/main/examples/plan_customization/README.md)
- [README.md](https://github.com/huggingface/smolagents/blob/main/README.md)
</details>

# Core Agent System and ReAct Loop

## Overview and Purpose

The smolagents core agent system is implemented in [`src/smolagents/agents.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py) and centers on the `MultiStepAgent` abstract class. This class drives an iterative **ReAct-style loop** in which a language model proposes an action, the action is executed against a tool or sandbox, the result is appended to memory, and the loop continues until the model produces a final answer or a step limit is exceeded.

Two concrete subclasses ship in the library:

| Subclass | Action format | Execution surface |
|----------|---------------|-------------------|
| `CodeAgent` | Python code blobs wrapped in tagged fences | `LocalPythonExecutor` or remote `E2BExecutor` / `DockerExecutor` / `ModalExecutor` / `BlaxelExecutor` |
| `ToolCallingAgent` | JSON tool-call payloads | The tool registry passed at construction time |

The loop is wired together with an `AgentMemory` instance that holds `TaskStep`, `SystemPromptStep`, `PlanningStep`, `ActionStep`, and `FinalAnswerStep` records. Each step is rendered into the next prompt via Jinja templates stored under `src/smolagents/prompts/` (see [code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/code_agent.yaml) and [toolcalling_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/toolcalling_agent.yaml)). Source: [src/smolagents/agents.py:1-100]()

The library advertises this pattern in [README.md](https://github.com/huggingface/smolagents/blob/main/README.md) as a lightweight, model- and tool-agnostic agent runtime backed by Hugging Face Inference Providers, LiteLLM, and MCP-compatible tool collections.

## ReAct Loop Mechanics

The driver of the loop is `MultiStepAgent.run`, which performs the following sequence per iteration until termination:

1. Build a chat messages list from `AgentMemory`, applying the `step_callbacks` for any per-step hooks (used for Human-in-the-Loop flows; see [examples/plan_customization/README.md](https://github.com/huggingface/smolagents/blob/main/examples/plan_customization/README.md)).
2. Optionally invoke a `PlanningStep` to refresh a high-level plan before continuing.
3. Call the underlying `Model` to generate either a code blob (`CodeAgent`) or a structured tool-call (`ToolCallingAgent`).
4. Parse the response. For `CodeAgent`, `extract_code_from_text` / `parse_code_blobs` strip fences; for `ToolCallingAgent`, the model's native JSON tool-call surface is consumed.
5. Execute the action via the appropriate executor, producing an `ActionOutput` or `ToolOutput` dataclass defined in [src/smolagents/agents.py:60-75]().
6. Append an `ActionStep` (with timing, token usage, and observation) to memory.
7. If the action is a final answer, stop; otherwise loop.

This sequence is reflected directly in the prompt exemplars: `Thought -> Code/Observation` cycles for `CodeAgent` and `Action/Observation` cycles for `ToolCallingAgent`. Source: [src/smolagents/prompts/code_agent.yaml:1-50]() and [src/smolagents/prompts/toolcalling_agent.yaml:1-80]()

```mermaid
flowchart TD
    A[Task received] --> B[Push TaskStep to memory]
    B --> C{planning_interval hit?}
    C -- yes --> D[Generate PlanningStep]
    C -- no --> E[Call Model]
    D --> E
    E --> F{Parse response}
    F -- code blob --> G[LocalPythonExecutor]
    F -- tool call --> H[Tool registry]
    G --> I[Observation -> ActionStep]
    H --> I
    I --> J{final_answer?}
    J -- yes --> K[Emit FinalAnswerStep]
    J -- no --> L{step limit reached?}
    L -- no --> C
    L -- yes --> M[Raise AgentMaxStepsError]
```

## Memory and Step Lifecycle

`AgentMemory` is the single source of truth for prompt construction. Step types are defined in [src/smolagents/memory.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/memory.py) (imported from agents.py) and are inserted into memory by `MultiStepAgent` at well-defined moments:

| Step type | Created when | Purpose |
|-----------|--------------|---------|
| `SystemPromptStep` | Initialization | Carries the rendered system prompt and any `custom_instructions` |
| `TaskStep` | First iteration | Holds the user task string |
| `PlanningStep` | Every `planning_interval` steps, or on demand | Stores an updated high-level plan; templates live under `planning:` in each YAML prompt |
| `ActionStep` | Each successful or failed action | Contains model output, observation, token usage, timing |
| `FinalAnswerStep` | When the agent declares termination | Captures the parsed final answer returned to the caller |

Because memory is rendered at every iteration, community feedback has consistently flagged **memory growth and persistence** as an open concern. Issue [#901](https://github.com/huggingface/smolagents/issues/901) requests automatic consolidation after N interactions; issue [#694](https://github.com/huggingface/smolagents/issues/694) asks for built-in summarization to avoid context-window overflow; and issue [#1216](https://github.com/huggingface/smolagents/issues/1216) requests first-class save/load of memory across sessions. Issue [#945](https://github.com/huggingface/smolagents/issues/945) proposes a pluggable memory backend (e.g., mem0). These concerns all map to the `AgentMemory` lifecycle described above. Source: [src/smolagents/agents.py:80-130]()

For applications that need to inject prior chat history, issue [#1579](https://github.com/huggingface/smolagents/issues/1579) tracks the recommended pattern: run the agent with `reset=False` so that pre-existing steps in `AgentMemory` are preserved across `agent.run` calls rather than re-initialized from scratch.

## Configuration, Tools, and Customization

The loop is parameterized by several `MultiStepAgent` keyword arguments consumed throughout the loop body:

- `tools` and `managed_agents`: dictionaries passed to the prompt renderer so that each tool exposes a `name`, `description`, `inputs`, and `output_type`. Tool examples such as `VisitWebpageTool`, `WikipediaSearchTool`, and `SpeechToTextTool` are defined in [src/smolagents/default_tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py). Source: [src/smolagents/default_tools.py:1-120]()
- `planning_interval`: integer step cadence at which a fresh `PlanningStep` is requested. Templates come from `PlanningPromptTemplate` (`initial_plan`, `update_plan_pre_messages`, `update_plan_post_messages`) defined in [src/smolagents/agents.py:95-115]().
- `max_steps` / `step_callbacks`: termination bound and per-step observers. `step_callbacks` is the supported extension point for Human-in-the-Loop patterns, as demonstrated by the `interrupt_after_plan` callback in [examples/plan_customization/README.md](https://github.com/huggingface/smolagents/blob/main/examples/plan_customization/README.md), which inspects `isinstance(memory_step, PlanningStep)` to gate the loop and optionally mutate the plan in memory before resuming.
- `executor_type`: selects between `LocalPythonExecutor` and remote executors imported from [`src/smolagents/remote_executors.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py) (e.g., `E2BExecutor`, `DockerExecutor`, `ModalExecutor`, `BlaxelExecutor`). Community issue [#2368](https://github.com/huggingface/smolagents/issues/2368) adds `microsandbox` to this list. Source: [src/smolagents/agents.py:30-55]()
- `prompt_templates`: overrides for any of the YAML prompt sections, enabling structured-output variants such as `structured_code_agent.yaml`.

The structured variant in [src/smolagents/prompts/structured_code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/structured_code_agent.yaml) shows the JSON-encoded ReAct schema (`{"thought": ..., "code": ...}`) that `CodeAgent` uses when `grammar`/structured-output backends are configured.

### Termination and Error Handling

The loop terminates in three ways, all surfaced as exceptions or return values:

| Outcome | Trigger | Surfaced as |
|---------|---------|-------------|
| Final answer produced | Parsed `final_answer(...)` call or matching tool call | `FinalAnswerStep` returned by `run` |
| Step exhaustion | `step_number >= max_steps` | `AgentMaxStepsError` |
| Generation/parse failure | Model returns invalid code/tool call after retries | `AgentGenerationError`, `AgentParsingError`, `AgentToolCallError`, `AgentToolExecutionError` |

These exception classes are imported from [`src/smolagents/utils.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/utils.py) at the top of `agents.py` and are used by the loop body to wrap failures into the `ActionStep.error` field rather than crashing the run. Source: [src/smolagents/agents.py:25-45]()

## See Also

- [Agent Memory and Step Types](memory-and-steps.md) — deep dive into `AgentMemory`, `ActionStep`, and persistence APIs.
- [Tools and Tool Collections](tools.md) — how tool definitions are rendered into prompts and the MCP/LangChain bridges.
- [Prompt Templates and Planning](prompt-templates.md) — overriding YAML prompts, structured outputs, and planning cadence.
- [Code Execution and Executors](code-execution.md) — `LocalPythonExecutor` vs. remote sandbox executors.

---

<a id='page-2'></a>

## Memory and State Management

### Related Pages

Related topics: [Core Agent System and ReAct Loop](#page-1), [Deployment, CLI, UI, Security, and Extensibility](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py)
- [src/smolagents/default_tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py)
- [src/smolagents/prompts/code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/code_agent.yaml)
- [src/smolagents/prompts/toolcalling_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/toolcalling_agent.yaml)
- [src/smolagents/prompts/structured_code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/structured_code_agent.yaml)
- [examples/plan_customization/README.md](https://github.com/huggingface/smolagents/blob/main/examples/plan_customization/README.md)
</details>

# Memory and State Management

## Overview

In `smolagents`, memory and state management refers to how agents persist, replay, and project their interaction history back into model prompts. Every `MultiStepAgent` (including `CodeAgent`, `ToolCallingAgent`, and the structured variant) maintains an internal list of `MemoryStep` objects that grow each time the agent reasons, acts, or observes a tool result. The full step history is serialized into chat messages before each model call, giving the LLM the illusion of an ongoing conversation. Source: [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py).

Memory in the current version (v1.26.0) is **in-memory only**. There is no built-in serialization to disk or to external stores such as Redis, SQL, or mem0. The community has repeatedly requested persistence (issue #945), save/load helpers (#1216), summarization to control growth (#694, #901), and custom chat-history insertion for multi-turn chat (#1579). These are tracked as open feature requests rather than shipped behavior.

## Memory Architecture

The agent's memory is a flat sequence of typed steps appended as the run progresses. The plan-customization example explicitly enumerates these step types:

```text
Current memory contains N steps:
  1. TaskStep
  2. PlanningStep
  3. ActionStep
  4. ActionStep
  ...
```

Source: [examples/plan_customization/README.md](https://github.com/huggingface/smolagents/blob/main/examples/plan_customization/README.md).

Each step carries metadata that is later flattened back into chat messages via `write_memory_to_messages()`. During the inner `_generate_planning_step` / `_generate_action_step` loops, the agent calls `populate_template` on the YAML prompt templates (`planning.update_plan_pre_messages`, `planning.update_plan_post_messages`) and concatenates the rendered messages with the live memory. Source: [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py).

```mermaid
flowchart LR
    A[User Task] --> B[TaskStep]
    B --> C[PlanningStep]
    C --> D[ActionStep<br/>Thought + Code + Tool]
    D --> E{Observation}
    E -->|more steps| D
    E -->|done| F[FinalAnswerStep]
    D --> G[memory.steps]
    F --> G
    G --> H[write_memory_to_messages]
    H --> I[Next LLM call]
```

The model output message, token usage, and parsed code action are written back onto the originating `ActionStep` (`memory_step.model_output_message`, `memory_step.token_usage`, `memory_step.model_output`). Source: [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py).

## Memory-to-Message Projection

Before every model call, the agent converts its memory into chat messages. Two projection modes exist:

| Mode | Purpose | What is dropped |
|------|---------|-----------------|
| Full mode | Default run-time prompt | None — all steps serialized |
| Summary mode | Plan regeneration between steps | System prompt and prior planning messages |

When a planning step is regenerated (e.g., after `step_callback` interrupts in the plan-customization example), the agent switches to summary mode by passing `summary_mode=True` to `write_memory_to_messages`. The code path is:

```python
memory_messages = self.write_memory_to_messages(summary_mode=True)
plan_update_pre = ChatMessage(role=MessageRole.SYSTEM, content=[...])
plan_update_post = ChatMessage(role=MessageRole.USER, content=[...])
input_messages = [plan_update_pre] + memory_messages + [plan_update_post]
```

Source: [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py).

For structured-output code agents, the model output is appended with the closing `code_block_tags[1]` token to nudge future generations toward the same stop sequence, and this augmented string is stored on `memory_step.model_output_message.content`. Source: [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py).

## Prompt Templates and State Carriers

The YAML prompt templates act as the canonical state descriptors that are spliced into memory messages:

- `system_prompt` establishes the Thought → Code → Observation loop and the `final_answer` convention. Source: [src/smolagents/prompts/code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/code_agent.yaml).
- `planning.initial_plan` and `planning.update_plan_*_messages` carry the facts survey + plan structure that is re-emitted whenever a planning step is regenerated. Source: [src/smolagents/prompts/toolcalling_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/toolcalling_agent.yaml).
- `managed_agent.task` defines the contract for sub-agents that are delegated to from a parent agent, including required `final_answer` sections. Source: [src/smolagents/prompts/code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/code_agent.yaml).

The structured-code variant emits JSON envelopes with `thought` and `code` keys and uses the same planning surfaces. Source: [src/smolagents/prompts/structured_code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/structured_code_agent.yaml).

## Step Callbacks and Memory Inspection

The `step_callbacks` hook (used in `examples/plan_customization/plan_customization.py`) fires after each step is appended, letting external code inspect and modify memory before the next call. The example demonstrates:

```python
print(f"Current memory contains {len(agent.memory.steps)} steps:")
for i, step in enumerate(agent.memory.steps):
    step_type = type(step).__name__
    print(f"  {i+1}. {step_type}")
```

Source: [examples/plan_customization/README.md](https://github.com/huggingface/smolagents/blob/main/examples/plan_customization/README.md).

This is the only sanctioned way to mutate memory mid-run. There is no public `save()`/`load()` helper for memory — users wanting persistence must serialize `agent.memory.steps` themselves (issue #1216).

## Known Limitations

The following limitations are reflected in the source and corroborated by community issues:

- **No built-in summarization or truncation.** The full step history is sent on every LLM call; only basic message removal is available. Long runs eventually exceed the context window. Source: [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py). Community: #694, #901.
- **No pluggable persistence layer.** Memory lives only on the agent instance. Community: #945, #1216.
- **No first-class injection of prior chat history.** Users who want to prepend past turns must manipulate `memory.steps` directly. Community: #1579.
- **No memory-consolidation hook.** Requests for a `before_consolidation` callback (for fingerprinting / observability) remain open. Community: #2129.
- **No memory-poisoning guard.** Requests to integrate OWASP-style protections for persistent memory are open. Community: #2332.

## See Also

- Agent core loop and step types: see the `MultiStepAgent` section in this wiki.
- Prompt templates referenced by memory projection: see the YAML files under `src/smolagents/prompts/`.
- Custom plan modification via step callbacks: see `examples/plan_customization/README.md`.

---

<a id='page-3'></a>

## Tools, Models, and Execution Backends

### Related Pages

Related topics: [Core Agent System and ReAct Loop](#page-1), [Deployment, CLI, UI, Security, and Extensibility](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/smolagents/models.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/models.py)
- [src/smolagents/tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/tools.py)
- [src/smolagents/default_tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py)
- [src/smolagents/local_python_executor.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py)
- [src/smolagents/remote_executors.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py)
- [src/smolagents/_function_type_hints_utils.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/_function_type_hints_utils.py)
- [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py)
</details>

# Tools, Models, and Execution Backends

`smolagents` is built around three orthogonal extension axes that an agent developer customizes at construction time: the **tools** an agent may invoke, the **model** that produces reasoning and actions, and the **execution backend** that runs any code the model emits. Because each axis is decoupled, a developer can mix, for example, a Tool-Calling model with a remote sandbox executor, or a Code Agent with locally defined tools, without touching the agent loop itself.

## 1. The Plugin Axes at a Glance

The agent constructor in [`src/smolagents/agents.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py) wires the three axes together. It imports the tool catalog from `default_tools`, the model registry from `models`, and a unified executor abstraction that supports both a local in-process interpreter and a set of remote sandboxed backends:

```python
from .default_tools import TOOL_MAPPING, FinalAnswerTool
from .local_python_executor import BASE_BUILTIN_MODULES, LocalPythonExecutor, PythonExecutor
from .models import CODEAGENT_RESPONSE_FORMAT, MODEL_REGISTRY
from .remote_executors import BlaxelExecutor, DockerExecutor, E2BExecutor, ModalExecutor
from .tools import BaseTool, Tool, validate_tool_arguments
```

Source: [src/smolagents/agents.py:1-50]()
Source: [src/smolagents/agents.py:51-80]()

The following diagram summarizes how a single agent call flows through these layers:

```mermaid
flowchart LR
    U[User Task] --> A[MultiStepAgent.run]
    A --> M[Model.generate]
    M -- Action --> A
    A -- Code blob --> E{PythonExecutor}
    A -- Tool call --> T[Tool.forward]
    E -- Observation --> A
    T -- Observation --> A
    A --> F[final_answer]
```

Source: [src/smolagents/agents.py:51-80]()
Source: [src/smolagents/default_tools.py:1-40]()

Community discussion #145 ("Making this library async", [issue #145](https://github.com/huggingface/smolagents/issues/145)) notes that most of this loop is network-bound, which is one reason execution backends are pluggable rather than hard-coded.

## 2. Tools: Authoring and Built-ins

A tool in `smolagents` is a `Tool` (or `BaseTool`) subclass that declares a name, a description, an `inputs` schema, an `output_type`, and a `forward(...)` method ([`src/smolagents/tools.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/tools.py)). For ordinary Python functions, the framework auto-derives a JSON schema from type hints and a Google-style docstring in [`src/smolagents/_function_type_hints_utils.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/_function_type_hints_utils.py); the `_parse_google_format_docstring` and `_convert_type_hints_to_json_schema` helpers are the building blocks of that conversion.

```python
class VisitWebpageTool(Tool):
    name = "webpage_visit"
    description = "Fetches and returns the content of a webpage as Markdown."
    inputs = {"url": {"type": "string", "description": "The url of the webpage to visit."}}
    output_type = "string"

    def forward(self, url: str) -> str:
        response = requests.get(url, timeout=20)
        markdown_content = markdownify(response.text).strip()
        return self._truncate_content(markdown_content, self.max_output_length)
```

Source: [src/smolagents/default_tools.py:41-90]()

The bundled `TOOL_MAPPING` ([`src/smolagents/default_tools.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py)) ships with reference implementations that exercise several integration patterns:

| Tool | Backend | Pattern |
|------|---------|---------|
| `DuckDuckGoSearchTool` | `ddgs` package | Pure HTTP wrapper |
| `VisitWebpageTool` | `requests` + `markdownify` | HTTP fetch + sanitization |
| `WikipediaSearchTool` | `wikipediaapi` | Requires user-agent policy |
| `SpeechToTextTool` | `transformers` Whisper | `PipelineTool` subclass |

Source: [src/smolagents/default_tools.py:91-160]()
Source: [src/smolagents/default_tools.py:161-230]()

`SpeechToTextTool` extends `PipelineTool`, which is the framework's adapter for `transformers` pipelines and overrides `__new__` to inject the `pre_processor_class` and `model_class` ([`src/smolagents/default_tools.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py)). Custom tool authors normally only need a `Tool` subclass; they pick `PipelineTool` when they want Hugging Face model loading behavior for free.

## 3. Models: The Unified Client Surface

Models are registered through `MODEL_REGISTRY` in [`src/smolagents/models.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/models.py). The agent imports `CODEAGENT_RESPONSE_FORMAT`, `ChatMessage`, `Model`, `agglomerate_stream_deltas`, and `parse_json_if_needed` from that module, indicating a single chat-completion abstraction regardless of vendor. Community request #449 ("Add LlamaCppModel Support", [issue #449](https://github.com/huggingface/smolagents/issues/449)) is explicitly about extending this registry with another backend.

The three shipped prompt variants in [`src/smolagents/prompts/`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/) drive different model behaviors:

- `code_agent.yaml` instructs the model to emit Python code blobs fenced with `{{code_block_opening_tag}}` ... `{{code_block_closing_tag}}`.
- `structured_code_agent.yaml` forces a JSON `{"thought": "...", "code": "..."}` envelope so untrusted code extraction is unnecessary.
- `toolcalling_agent.yaml` requests structured tool-call JSON via the `final_answer` action and the standard `Action/Observation` cycle.

Source: [src/smolagents/prompts/code_agent.yaml:1-40]()
Source: [src/smolagents/prompts/structured_code_agent.yaml:1-40]()
Source: [src/smolagents/prompts/toolcalling_agent.yaml:1-40]()

`ChatMessageStreamDelta` and `agglomerate_stream_deltas` ([`src/smolagents/models.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/models.py)) allow streaming model output to be reassembled before downstream parsing, which is what makes both code-block and JSON-typed parsers possible.

## 4. Execution Backends: Local and Remote

The third axis is where the agent's emitted code actually runs. The base class `PythonExecutor` lives in [`src/smolagents/local_python_executor.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/local_python_executor.py), with `LocalPythonExecutor` and `BASE_BUILTIN_MODULES` exported alongside it. `LocalPythonExecutor` is an in-process interpreter that sandboxes imports against `BASE_BUILTIN_MODULES` and validates every assignment, call, and attribute access against a static set of allowed operations.

```python
# from src/smolagents/agents.py
from .local_python_executor import (
    BASE_BUILTIN_MODULES,
    LocalPythonExecutor,
    PythonExecutor,
    fix_final_answer_code,
)
```

Source: [src/smolagents/agents.py:31-50]()

For deployments that require stronger isolation, [`src/smolagents/remote_executors.py`](https://github.com/huggingface/smolagents/blob/main/src/smolagents/remote_executors.py) provides four pluggable implementations imported directly in `agents.py`:

- `E2BExecutor` — runs inside an [E2B](https://e2b.dev) microVM sandbox.
- `DockerExecutor` — runs inside a local Docker container.
- `ModalExecutor` — runs on [Modal](https://modal.com) serverless infrastructure.
- `BlaxelExecutor` — runs on the [Blaxel](https://blaxel.ai) platform.

Source: [src/smolagents/agents.py:51-70]()

The executor choice is made at agent construction time (`executor=...`) so the agent loop in `agents.py` can be backend-agnostic. Community issue #2368 ("Executor support for microsandbox", [issue #2368](https://github.com/huggingface/smolagents/issues/2368)) demonstrates the extension pattern: a new executor subclass implements the `PythonExecutor` interface and is registered for selection. Issue #2372 ([#2372](https://github.com/huggingface/smolagents/issues/2372)) points out that `evaluate_python_code`'s parameters (`authorized_imports`, `max_print_outputs_length`, etc.) must stay documented in lockstep with the executor interface, since the same function powers both the local and remote paths.

## 5. Putting the Three Axes Together

A typical minimal configuration binds one value from each axis:

```python
from smolagents import CodeAgent, InferenceClientModel
from smolagents.default_tools import VisitWebpageTool

agent = CodeAgent(
    tools=[VisitWebpageTool()],
    model=InferenceClientModel(),
    executor=LocalPythonExecutor(),  # or E2BExecutor(), DockerExecutor(), ...
)
agent.run("Summarize the latest release notes on https://huggingface.co")
```

Source: [src/smolagents/agents.py:51-80]()
Source: [src/smolagents/local_python_executor.py:1-40]()
Source: [src/smolagents/default_tools.py:41-90]()

The same agent class can be retargeted to a Tool-Calling model by switching the prompt YAML and the `model=` argument, and can be hardened for production by switching `executor=` to `E2BExecutor` or `DockerExecutor`. None of those choices require modifying the agent loop, which is the design intent behind the three-axis separation.

## See Also

- Agent memory and step types — see [Agent Memory and Step Lifecycle](#)
- Prompt YAML reference — see [Prompt Templates and Planning](#)
- Sandbox security — see [Secure Code Execution](#)

---

<a id='page-4'></a>

## Deployment, CLI, UI, Security, and Extensibility

### Related Pages

Related topics: [Core Agent System and ReAct Loop](#page-1), [Memory and State Management](#page-2), [Tools, Models, and Execution Backends](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py)
- [src/smolagents/cli.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/cli.py)
- [src/smolagents/gradio_ui.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/gradio_ui.py)
- [src/smolagents/serialization.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/serialization.py)
- [src/smolagents/monitoring.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/monitoring.py)
- [src/smolagents/utils.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/utils.py)
- [src/smolagents/_function_type_hints_utils.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/_function_type_hints_utils.py)
- [src/smolagents/default_tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py)
- [src/smolagents/prompts/code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/code_agent.yaml)
- [src/smolagents/prompts/structured_code_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/structured_code_agent.yaml)
- [src/smolagents/prompts/toolcalling_agent.yaml](https://github.com/huggingface/smolagents/blob/main/src/smolagents/prompts/toolcalling_agent.yaml)
</details>

# Deployment, CLI, UI, Security, and Extensibility

smolagents exposes four concerns that sit on top of the core agent loop and let a notebook agent become a shipped product: serializing a `MultiStepAgent` to disk or the Hub, presenting it through a CLI or a Gradio UI, isolating the Python code it writes, and extending it with new tools, prompts, and models. Each of these layers is intentionally small so that the framework stays composable.

## Deployment and Serialization

The on-disk layout produced by `agent.save()` is deterministic and self-contained, which is what makes the framework loadable from another process and publishable as a Space. The implementation walks the agent's `tools`, `managed_agents`, and `prompt_templates`, emitting one Python file per tool, a `prompts.yaml`, an `agent.json` description, and a recursive `managed_agents/` subtree, plus a `requirements.txt` listing the modules the tools import (`Source: src/smolagents/agents.py`). When the agent is pushed with `agent.push_to_hub()`, the same directory is wrapped with an `app.py` that serves a Gradio interface, so a Space can be generated directly from a Python process without manual authoring (`Source: src/smolagents/agents.py`).

Prompt rendering goes through `populate_template`, which uses Jinja2 with `StrictUndefined` so that a missing template variable raises immediately instead of silently producing an empty string (`Source: src/smolagents/agents.py`). The on-disk `prompts.yaml` is written with `yaml.safe_dump` and `default_style="|"` to preserve block-literal multi-line strings (`Source: src/smolagents/agents.py`).

```mermaid
flowchart LR
    A[CodeAgent / ToolCallingAgent] -->|save| B[output_dir]
    B --> C[tools/*.py]
    B --> D[prompts.yaml]
    B --> E[agent.json]
    B --> F[managed_agents/]
    B -->|push_to_hub| G[HuggingFace Space]
    G --> H[app.py + Gradio UI]
```

## Client Interfaces: CLI and Gradio UI

Two thin front-ends let non-Python users interact with a saved agent. The `smolagents` command-line entry point lives in [src/smolagents/cli.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/cli.py) and is the canonical way to load an agent directory and run a task from the terminal. Because this path is synchronous and most agent work is network-bound, community discussion about an asynchronous API is tracked in [#145](https://github.com/huggingface/smolagents/issues/145).

The interactive surface is a Gradio app. The `app.py` emitted by `push_to_hub()` is generated by `create_agent_gradio_app_template` in [src/smolagents/utils.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/utils.py), while [src/smolagents/gradio_ui.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/gradio_ui.py) provides the reusable chat-style component used by that template. This UI layer is also where human-in-the-loop workflows land: community pattern [#52](https://github.com/huggingface/smolagents/issues/52) describes pausing a step so a human can supply missing information or approve a sensitive tool call before it executes.

## Security and Sandboxed Execution

Because the default `CodeAgent` writes and executes Python, isolation is not optional. smolagents splits this responsibility across two layers that are referenced from the agent constructor: import allow-listing in the local executor and OS-level isolation through pluggable remote executors. Tool argument validation runs before execution through `validate_tool_arguments` in [src/smolagents/tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/tools.py), which is imported alongside the executors in [src/smolagents/agents.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/agents.py).

| Layer | Mechanism | Where it is wired |
|---|---|---|
| Import allow-list | `authorized_imports` + `BASE_BUILTIN_MODULES` in `LocalPythonExecutor` | `src/smolagents/local_python_executor.py` (referenced in `src/smolagents/agents.py`) |
| OS-level isolation | `DockerExecutor`, `E2BExecutor`, `BlaxelExecutor`, `ModalExecutor` | `src/smolagents/remote_executors.py` (referenced in `src/smolagents/agents.py`) |
| Argument validation | `validate_tool_arguments` | `src/smolagents/tools.py` (referenced in `src/smolagents/agents.py`) |

Demand for additional sandboxes is active: [#2368](https://github.com/huggingface/smolagents/issues/2368) (closed) proposed `libkrun`/`microsandbox` for lightweight local isolation, which signals that the executor abstraction is the intended extension point. Memory poisoning is a separate risk called out in [#2332](https://github.com/huggingface/smolagents/issues/2332), where the suggestion is to wrap `AgentMemory` with an OWASP-style guard rather than rely on prompt engineering alone.

## Extensibility

The framework is extended at three layers.

**Tools.** A new tool subclasses `Tool` and declares a name, description, and JSON-schema `inputs`. Tool schemas can be derived from typed Python functions by `_function_type_hints_utils.get_json_schema`, which parses Google-style docstrings, raises `DocstringParsingException` when an argument is undocumented, and supports `(choices: [...])` to mark enum fields (`Source: src/smolagents/_function_type_hints_utils.py`). The default-tool catalog in [src/smolagents/default_tools.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/default_tools.py) — `VisitWebpageTool`, `WikipediaSearchTool`, `SpeechToTextTool` — shows the canonical pattern of declaring `name`, `description`, `inputs`, and `output_type` and raising `ImportError` when optional dependencies are missing.

**Prompts.** All prompt templates live in [src/smolagents/prompts/](https://github.com/huggingface/smolagents/tree/main/src/smolagents/prompts) as YAML: `code_agent.yaml`, `structured_code_agent.yaml`, and `toolcalling_agent.yaml`. They are loaded into `agent.prompt_templates` and expose slots for the system prompt, planning step, managed-agent dispatch, and final answer (`Source: src/smolagents/prompts/code_agent.yaml`, `Source: src/smolagents/prompts/toolcalling_agent.yaml`). The `PlanningPromptTemplate`, `ManagedAgentPromptTemplate`, and `FinalAnswerPromptTemplate` TypedDicts in `src/smolagents/agents.py` document the keys each slot accepts.

**Models and observability.** The model layer registers backends through `MODEL_REGISTRY`, so adding a provider means subclassing `Model` and registering it; [#449](https://github.com/huggingface/smolagents/issues/449) requests a `LlamaCppModel` and [#1848](https://github.com/huggingface/smolagents/issues/1848) requests Anthropic Claude "agent skills". Observability is handled by [src/smolagents/monitoring.py](https://github.com/huggingface/smolagents/blob/main/src/smolagents/monitoring.py), which exposes `TokenUsage`, `AgentLogger`, `Monitor`, and `LogLevel`; the v1.25.0 release notes document an MLflow integration built on top of this surface.

## See Also

- [Agents and Orchestration](agents.md)
- [Memory and Step Lifecycle](memory.md)
- [Tools and Models](tools-and-models.md)
- [Prompting and Planning](prompting-and-planning.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: huggingface/smolagents

Summary: Found 28 structured pitfall item(s), including 6 high/blocking item(s). Top priority: Maintenance risk - Maintenance risk requires verification.

## 1. Maintenance risk - Maintenance risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/huggingface/smolagents/issues/1579

## 2. Maintenance risk - Maintenance risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/huggingface/smolagents/issues/694

## 3. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Developers should check this security_permissions risk before relying on the project: [Feature Request] Memory Poisoning Protection for smolagents via OWASP Agent Memory Guard
- User impact: Developers may expose sensitive permissions or credentials: [Feature Request] Memory Poisoning Protection for smolagents via OWASP Agent Memory Guard
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/2332

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/huggingface/smolagents/issues/2129

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/huggingface/smolagents/issues/2332

## 6. Security or permission risk - Security or permission risk requires verification

- Severity: high
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/huggingface/smolagents/issues/901

## 7. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: Save/Load agent memory
- User impact: Developers may fail before the first successful local run: Save/Load agent memory
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/1216

## 8. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.21.0
- User impact: Upgrade or migration may change expected behavior: v1.21.0
- Evidence: failure_mode_cluster:github_release | https://github.com/huggingface/smolagents/releases/tag/v1.21.0

## 9. Installation risk - Installation risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this installation risk before relying on the project: v1.22.0
- User impact: Upgrade or migration may change expected behavior: v1.22.0
- Evidence: failure_mode_cluster:github_release | https://github.com/huggingface/smolagents/releases/tag/v1.22.0

## 10. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: DOC: `evaluate_python_code` docstring is missing two parameters
- User impact: Developers may misconfigure credentials, environment, or host setup: DOC: `evaluate_python_code` docstring is missing two parameters
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/2372

## 11. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Enhanced memory module with integrations
- User impact: Developers may misconfigure credentials, environment, or host setup: Enhanced memory module with integrations
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/945

## 12. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: Feature: behavioral fingerprint hook for memory consolidation events in MultiStepAgent
- User impact: Developers may misconfigure credentials, environment, or host setup: Feature: behavioral fingerprint hook for memory consolidation events in MultiStepAgent
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/2129

## 13. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: [Feature] Agent memory/history consolidation after a number of interactions
- User impact: Developers may misconfigure credentials, environment, or host setup: [Feature] Agent memory/history consolidation after a number of interactions
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/901

## 14. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this configuration risk before relying on the project: v1.20.0
- User impact: Upgrade or migration may change expected behavior: v1.20.0
- Evidence: failure_mode_cluster:github_release | https://github.com/huggingface/smolagents/releases/tag/v1.20.0

## 15. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | github_repo:898968194 | https://github.com/huggingface/smolagents

## 16. Runtime risk - Runtime risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this runtime risk before relying on the project: v1.25.0
- User impact: Upgrade or migration may change expected behavior: v1.25.0
- Evidence: failure_mode_cluster:github_release | https://github.com/huggingface/smolagents/releases/tag/v1.25.0

## 17. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Developers should check this migration risk before relying on the project: v1.24.0
- User impact: Upgrade or migration may change expected behavior: v1.24.0
- Evidence: failure_mode_cluster:github_release | https://github.com/huggingface/smolagents/releases/tag/v1.24.0

## 18. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:898968194 | https://github.com/huggingface/smolagents

## 19. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | github_repo:898968194 | https://github.com/huggingface/smolagents

## 20. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | github_repo:898968194 | https://github.com/huggingface/smolagents

## 21. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: community_evidence:github | https://github.com/huggingface/smolagents/issues/2372

## 22. Capability evidence risk - Capability evidence risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this capability risk before relying on the project: ENH: Executor support for microsandbox
- User impact: Developers may hit a documented source-backed failure mode: ENH: Executor support for microsandbox
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/2368

## 23. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: ENH: Add a way to insert custom chat history for multi-turn chat and what's the current best way?
- User impact: Developers may hit a documented source-backed failure mode: ENH: Add a way to insert custom chat history for multi-turn chat and what's the current best way?
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/1579

## 24. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: Real Memory summary for on-going conversations (avoid LLM size limits)
- User impact: Developers may hit a documented source-backed failure mode: Real Memory summary for on-going conversations (avoid LLM size limits)
- Evidence: failure_mode_cluster:github_issue | https://github.com/huggingface/smolagents/issues/694

## 25. Runtime risk - Runtime risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this performance risk before relying on the project: v1.23.0
- User impact: Upgrade or migration may change expected behavior: v1.23.0
- Evidence: failure_mode_cluster:github_release | https://github.com/huggingface/smolagents/releases/tag/v1.23.0

## 26. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:898968194 | https://github.com/huggingface/smolagents

## 27. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | github_repo:898968194 | https://github.com/huggingface/smolagents

## 28. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: Developers should check this maintenance risk before relying on the project: v1.26.0
- User impact: Upgrade or migration may change expected behavior: v1.26.0
- Evidence: failure_mode_cluster:github_release | https://github.com/huggingface/smolagents/releases/tag/v1.26.0

<!-- canonical_name: huggingface/smolagents; human_manual_source: deepwiki_human_wiki -->