Smolagents

Agents generate 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 reasoning steps by ~30% compared to JSON-based tool calling by allowing the LLM to express complex multi-step logic in a single code block, with full access to Python's standard library and imported tools within the execution environment.

Coordinates multiple agents through a planning-based orchestration system that decomposes tasks at configurable planning intervals, allowing agents to hand off work, share context, and execute in sequence or parallel. The framework manages agent memory state across handoffs and provides hooks for custom planning strategies via callbacks, enabling complex multi-agent workflows without explicit workflow DSLs.

Provides a built-in Gradio web interface for interacting with agents, monitoring execution, and inspecting memory traces. The UI allows users to input tasks, view agent reasoning step-by-step, inspect tool calls and observations, and replay agent execution. This is useful for debugging, demonstration, and non-technical user interaction with agents.

Integrates with OpenTelemetry for distributed tracing, metrics collection, and logging of agent execution. Agent steps, tool calls, and errors are automatically instrumented with OpenTelemetry spans, allowing integration with observability platforms (Datadog, New Relic, Jaeger, etc.). This enables production monitoring, performance analysis, and debugging of agent systems.

Defines a custom exception hierarchy (e.g., ToolExecutionError, CodeExecutionError, ModelError) that captures different failure modes in agent execution. Agents can catch and handle specific exceptions, implement retry logic, and provide meaningful error messages to users. The exception hierarchy enables fine-grained error handling without catching all exceptions broadly.

Provides a CLI tool for running agents from the command line, specifying model, tools, and task via arguments or configuration files. The CLI supports both interactive mode (REPL-style) and batch mode (single task execution), with options for logging, debugging, and output formatting. This enables non-Python users to interact with agents and integrate agents into shell scripts and automation workflows.

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.

Defines tools as Python functions with type hints that are automatically serialized into structured schemas for LLM consumption. The Tool interface validates inputs against type annotations, supports custom serialization via tool_input_variables, and integrates with both CodeAgent (direct Python execution) and ToolCallingAgent (JSON schema-based calling). Built-in tools (web search, file operations, etc.) are provided alongside extensibility for custom tools.

Implements the ReAct (Reasoning + Acting) loop as the core agent execution pattern in MultiStepAgent, cycling through LLM reasoning, tool execution, and observation collection. Agent memory is maintained as a list of (action, observation) tuples accessible via callbacks at each step, enabling custom logging, monitoring, human-in-the-loop interventions, and memory inspection. Callbacks fire at agent lifecycle events (step start/end, error, completion) for extensibility.

Executes generated Python code via LocalPythonExecutor (in-process with optional sandboxing) or custom RemotePythonExecutor subclasses (e.g., Docker, Kubernetes, cloud functions). The execution environment is isolated from the agent process, with configurable resource limits, timeout handling, and error capture. Security model relies on executor implementation; LocalPythonExecutor can use RestrictedPython or similar for sandboxing, while remote executors provide process isolation.

Abstracts LLM interactions through a unified Model interface that supports API-based models (OpenAI, Anthropic, HuggingFace Inference API) and local inference models (Ollama, vLLM, custom). Models are instantiated with provider-specific configuration and expose a forward() method that handles prompt formatting, token counting, and response parsing. The abstraction allows agents to switch models without code changes, supporting both streaming and non-streaming responses.

ToolCallingAgent emits structured tool calls as JSON objects with tool name and arguments, which are validated against auto-generated JSON schemas derived from tool type hints. The agent parses LLM output to extract tool calls, validates arguments, and invokes Tool.forward() directly. This paradigm is compatible with models that support function calling (OpenAI, Anthropic) and provides stricter input validation than code-first execution.

Integrates with MCP servers to dynamically load and invoke tools via the Model Context Protocol, allowing agents to access external tool ecosystems (e.g., Anthropic's MCP ecosystem) without hardcoding tool definitions. MCP tools are wrapped as smolagents Tool objects and can be used with both CodeAgent and ToolCallingAgent, providing a bridge to standardized tool protocols.

Saves and loads agent configurations, tool definitions, and execution state to/from Hugging Face Hub, enabling agent versioning, sharing, and reproducibility. Agents can be serialized to Hub with their model configuration, tools, and system prompts, and restored in other environments. This integration provides a centralized registry for agent artifacts and enables collaborative agent development.

Supports streaming agent responses and real-time updates via callback hooks that fire as the agent generates output, enabling progressive UI updates and real-time monitoring. Streaming is implemented at the model level (for models that support it) and propagated through callbacks, allowing clients to display agent reasoning and results as they become available rather than waiting for completion.