smolagents

Agents generate executable Python code as their primary reasoning mechanism, where each tool call is expressed as a Python function invocation within a code block. The LLM outputs raw Python that the runtime parses and executes, enabling agents to compose tool calls with arbitrary Python logic (loops, conditionals, variable assignment) rather than being constrained to sequential JSON-based function calls. This approach treats code generation as the agent's native language for orchestration.

Provides a unified agent interface that abstracts away provider-specific API differences (OpenAI, Anthropic, Hugging Face, Ollama, etc.), allowing agents to swap LLM backends without code changes. The library handles prompt formatting, token counting, and response parsing for each provider's conventions, exposing a single agent API that works across proprietary and open-source models. This enables cost optimization and model experimentation without refactoring agent logic.

Provides detailed execution traces of agent reasoning, including generated code, tool calls, results, and LLM interactions. The library logs each step of the agentic loop (code generation, parsing, tool invocation, result processing) with structured metadata, enabling debugging, monitoring, and analysis of agent behavior. Traces can be exported to external observability platforms (e.g., Langfuse, Arize) for centralized monitoring.

Enables agents to process multimodal inputs including images, documents, and audio, allowing them to reason about visual content and extract information from documents. Agents can invoke vision tools that analyze images (OCR, object detection, scene understanding) or document processing tools that extract structured data from PDFs and scanned documents. This extends agent capabilities beyond text-only reasoning.

Agents discover and invoke tools through a registry system that validates tool schemas (input parameters, output types) before execution. Tools are registered as Python callables with type hints or JSON schemas, and the registry enforces that LLM-generated code calls tools with valid arguments, preventing runtime errors from malformed tool invocations. This enables safe tool composition and provides agents with introspectable tool metadata for reasoning about available capabilities.

Agents can invoke other agents as tools, enabling hierarchical task decomposition where complex problems are delegated to specialized sub-agents. The library treats agents as first-class tools that can be registered in the tool registry, allowing parent agents to orchestrate sub-agents' execution and aggregate their results. This pattern enables building multi-agent systems where each agent specializes in a domain (e.g., search agent, calculation agent, summarization agent) and higher-level agents coordinate their work.

Agents can stream their reasoning steps and intermediate results in real-time as they execute, rather than waiting for complete execution before returning results. The library exposes streaming APIs that yield agent steps (code generation, tool calls, results) incrementally, enabling UI updates, progressive disclosure of reasoning, and early termination if intermediate results are unsatisfactory. This is particularly useful for long-running agents where users benefit from seeing progress.

Implements a robust agentic loop that handles tool call failures, invalid code generation, and LLM errors with automatic recovery mechanisms. When agents generate invalid code or tools fail, the loop captures error messages, feeds them back to the LLM as context, and allows the agent to retry with corrected logic. This pattern reduces manual intervention and enables agents to self-correct from common failures (syntax errors, wrong argument types, tool timeouts).

Provides configurable execution environments for agent-generated code, with optional sandboxing to limit the scope of code execution. Agents can run code in isolated Python interpreters or restricted execution contexts that prevent access to sensitive resources (filesystem, network, environment variables). This is critical for security when agents are invoked by untrusted users or in multi-tenant environments where code isolation is required.

Supports dynamic prompt construction where agent system prompts, tool descriptions, and user queries are templated with context variables that are injected at runtime. This enables agents to adapt their behavior based on user context (user role, permissions, available tools), conversation history, or external state without requiring code changes. Templates support variable substitution, conditional sections, and formatting for different LLM providers.

Caches tool execution results based on input arguments, reducing redundant tool calls when agents invoke the same tool with identical inputs. The library maintains an in-memory or persistent cache of tool results, allowing agents to reuse cached results instead of re-executing expensive operations (API calls, database queries, computations). This optimization is particularly valuable for agents that explore multiple solution paths or retry operations.

Enables agents to save their execution state (current step, tool results, reasoning context) to persistent storage and resume from checkpoints, allowing long-running agents to survive interruptions or be paused and resumed later. The library serializes agent state including the execution history, intermediate results, and LLM context, enabling recovery without re-executing completed steps. This is valuable for agents that run for hours or days.