Smolagents

LLM generates executable Python code snippets instead of JSON tool calls, which are parsed by parse_code_blobs() utility and executed directly by LocalPythonExecutor or RemotePythonExecutor. This approach reduces agent steps by ~30% compared to JSON-based tool calling by allowing the LLM to compose multi-step logic in a single code block, improving reasoning efficiency and reducing token overhead from intermediate parsing cycles.

Framework supports multi-agent systems where agents can be composed hierarchically or sequentially with configurable planning intervals that determine when agents hand off to other agents or pause for human input. Agents maintain shared memory state and can observe each other's outputs, enabling collaborative problem-solving patterns where specialized agents handle subtasks and a coordinator agent manages the overall workflow.

Agents use customizable system prompts that define the agent's role, available tools, and reasoning instructions. Prompts are templates that can be overridden per-agent instance, allowing teams to tune agent behavior without code changes. System prompts include tool schemas (auto-generated from function signatures) and instructions for the agent paradigm (e.g., 'write Python code' for CodeAgent, 'call tools' for ToolCallingAgent). Prompt engineering is transparent; teams can inspect and modify prompts to improve agent performance.

Agents can be serialized and saved to Hugging Face Hub, enabling sharing and reuse of agent configurations, prompts, and tool definitions. Persistence includes agent class, model configuration, system prompt, and tool definitions. Agents can be loaded from Hub by name, automatically downloading and deserializing the configuration. This enables teams to build agent libraries and share agents across projects without code duplication.

Framework includes a Gradio-based web interface that allows non-technical users to interact with agents through a chat-like UI. The UI displays agent reasoning steps, tool calls, and results in real-time, providing visibility into agent behavior. Streaming is supported, showing agent thoughts and tool outputs as they arrive. The UI is auto-generated from agent configuration; no custom UI code required. Teams can deploy agents as web services without building custom frontends.

Agents implement error handling at the step level: if a tool call fails or code execution raises an exception, the error is captured as an observation and passed back to the LLM for recovery. The LLM can then decide to retry the tool, try a different approach, or report failure. No automatic retries; the LLM controls recovery strategy. Error messages are included in agent memory, allowing the LLM to learn from failures within a single agent run.

Framework supports async agent execution via async/await syntax, allowing agents to run concurrently with other code. Streaming is supported for real-time agent output — agents can stream intermediate results (thoughts, tool calls, observations) to the client as they execute. Streaming is implemented via callbacks that emit events as the agent progresses.

Agents can be saved to disk or pushed to Hugging Face Hub for sharing and versioning. Persistence includes agent configuration, memory, and step history. Hub integration allows agents to be discovered and reused by other developers. This enables reproducibility and collaboration on agent development.

Framework supports pausing agents at specific steps to request human input or approval. Callbacks can pause execution and wait for human feedback before continuing. This enables workflows where agents handle routine tasks but escalate decisions to humans. Human input is fed back into agent memory and used for subsequent reasoning.

Framework includes a built-in Gradio web interface for interacting with agents. The UI allows users to input tasks, view agent reasoning in real-time, and see step-by-step execution. The Gradio UI is automatically generated from agent configuration and supports streaming output. This enables non-technical users to interact with agents without writing code.

Implements the ReAct (Reasoning + Acting) loop as the core agent execution pattern in MultiStepAgent, where agents alternate between reasoning steps (LLM generates thought + action) and observation steps (tool execution + result capture). Memory is maintained as a list of (action, observation) tuples, and callback hooks (via AgentLogger and Monitor) fire at each lifecycle event (step start, tool call, error, completion), enabling observability, debugging, and custom monitoring without modifying core agent logic.

Tools are defined as Python functions with type hints and docstrings; the framework automatically extracts function signatures and docstrings to generate tool schemas (JSON Schema or OpenAI function calling format). Tool validation occurs at definition time (checking for required docstrings, type hints) and at call time (validating arguments against the schema). Both CodeAgent and ToolCallingAgent use these schemas, but CodeAgent passes them as context to the LLM while ToolCallingAgent uses them for structured output validation.

LocalPythonExecutor runs generated code in the current Python process with access to the agent's tool namespace, while RemotePythonExecutor (abstract base class) enables custom implementations for sandboxed or distributed execution. Code is executed via exec() with a restricted namespace containing only imported tools and safe builtins, preventing access to filesystem or network unless explicitly granted through tool definitions. Remote executors can implement additional security measures (containerization, timeouts, resource limits) at the cost of higher latency.

Agents accept a model parameter that implements a minimal Model interface (forward() method for inference, optional stream() for streaming). Built-in implementations support OpenAI, Anthropic, Hugging Face Inference API, and local models via Ollama or vLLM. Models are instantiated with provider-specific configuration (API keys, base URLs, model names) and handle prompt formatting, token counting, and response parsing internally. Streaming is optional and model-dependent; agents can consume streamed tokens for real-time output without waiting for full completion.

Agent memory is maintained as a simple list of (action, observation) tuples that grows with each agent step. The memory is passed to the LLM as context in the system prompt, allowing the model to reason over its previous actions and their outcomes. Memory can be inspected, replayed, or serialized for debugging. No automatic summarization or pruning; teams must implement custom memory management (e.g., sliding windows, importance-based truncation) if context length becomes a bottleneck.

ToolCallingAgent instructs the LLM to emit structured tool calls (JSON objects with tool_name and arguments) instead of code. The framework parses these structured outputs, validates arguments against the tool schema, and calls Tool.forward() directly. This approach works with models that support function calling APIs (OpenAI, Anthropic) and is safer than code execution because tool calls are validated before execution. Tool definitions must implement a forward() method that accepts validated arguments.

Framework supports loading tools from MCP servers, which expose tools via a standardized protocol. MCP tools are wrapped into the smolagents Tool interface, allowing agents to use MCP-provided tools alongside native Python tools. This enables integration with external tool ecosystems (e.g., Anthropic's MCP server ecosystem) without reimplementing tools in Python. MCP tool loading is transparent; agents treat MCP tools identically to native tools.

AgentLogger captures agent lifecycle events (step started, tool called, error occurred, step completed) and logs them at configurable verbosity levels (DEBUG, INFO, WARNING, ERROR). Monitor class provides metrics collection (step count, tool call count, error rate). Both integrate with OpenTelemetry for distributed tracing and external observability platforms. Callbacks are synchronous and optional; agents work without logging but can be instrumented for debugging or production monitoring.