Hugging Face's logo

smolagents documentation

Agents

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Agents

Smolagents is an experimental API which is subject to change at any time. Results returned by the agents can vary as the APIs or underlying models are prone to change.

To learn more about agents and tools make sure to read the introductory guide. This page contains the API docs for the underlying classes.

Agents

Our agents inherit from MultiStepAgent, which means they can act in multiple steps, each step consisting of one thought, then one tool call and execution. Read more in this conceptual guide.

We provide two types of agents, based on the main Agent class.

Both require arguments model and list of tools tools at initialization.

Classes of agents

class smolagents.MultiStepAgent

< >

( tools: typing.List[smolagents.tools.Tool] model: typing.Callable[[typing.List[typing.Dict[str, str]]], smolagents.models.ChatMessage] prompt_templates: typing.Optional[dict] = None max_steps: int = 6 tool_parser: typing.Optional[typing.Callable] = None add_base_tools: bool = False verbosity_level: LogLevel = <LogLevel.INFO: 1> grammar: typing.Optional[typing.Dict[str, str]] = None managed_agents: typing.Optional[typing.List] = None step_callbacks: typing.Optional[typing.List[typing.Callable]] = None planning_interval: typing.Optional[int] = None name: typing.Optional[str] = None description: typing.Optional[str] = None provide_run_summary: bool = False final_answer_checks: typing.Optional[typing.List[typing.Callable]] = None )

Parameters

  • tools (list[Tool]) — Tools that the agent can use.
  • model (Callable[[list[dict[str, str]]], ChatMessage]) — Model that will generate the agent’s actions.
  • prompt_templates (dict, optional) — Prompt templates.
  • max_steps (int, default 6) — Maximum number of steps the agent can take to solve the task.
  • tool_parser (Callable, optional) — Function used to parse the tool calls from the LLM output.
  • add_base_tools (bool, default False) — Whether to add the base tools to the agent’s tools.
  • verbosity_level (LogLevel, default LogLevel.INFO) — Level of verbosity of the agent’s logs.
  • grammar (dict[str, str], optional) — Grammar used to parse the LLM output.
  • managed_agents (list, optional) — Managed agents that the agent can call.
  • step_callbacks (list[Callable], optional) — Callbacks that will be called at each step.
  • planning_interval (int, optional) — Interval at which the agent will run a planning step.
  • name (str, optional) — Necessary for a managed agent only - the name by which this agent can be called.
  • description (str, optional) — Necessary for a managed agent only - the description of this agent.
  • provide_run_summary (bool, optional) — Whether to provide a run summary when called as a managed agent.
  • final_answer_checks (list, optional) — List of Callables to run before returning a final answer for checking validity.

Agent class that solves the given task step by step, using the ReAct framework: While the objective is not reached, the agent will perform a cycle of action (given by the LLM) and observation (obtained from the environment).

execute_tool_call

< >

( tool_name: str arguments: typing.Union[typing.Dict[str, str], str] )

Parameters

  • tool_name (str) — Name of the Tool to execute (should be one from self.tools).
  • arguments (Dict[str, str]) — Arguments passed to the Tool.

Execute tool with the provided input and returns the result. This method replaces arguments with the actual values from the state if they refer to state variables.

extract_action

< >

( model_output: str split_token: str )

Parameters

  • model_output (str) — Output of the LLM
  • split_token (str) — Separator for the action. Should match the example in the system prompt.

Parse action from the LLM output

initialize_system_prompt

< >

( )

To be implemented in child classes

planning_step

< >

( task is_first_step: bool step: int )

Parameters

  • task (str) — Task to perform.
  • is_first_step (bool) — If this step is not the first one, the plan should be an update over a previous plan.
  • step (int) — The number of the current step, used as an indication for the LLM.

Used periodically by the agent to plan the next steps to reach the objective.

provide_final_answer

< >

( task: str images: typing.Optional[list[str]] ) → str

Parameters

  • task (str) — Task to perform.
  • images (list[str], optional) — Paths to image(s).

Returns

str

Final answer to the task.

Provide the final answer to the task, based on the logs of the agent’s interactions.

replay

< >

( detailed: bool = False )

Parameters

  • detailed (bool, optional) — If True, also displays the memory at each step. Defaults to False. Careful: will increase log length exponentially. Use only for debugging.

Prints a pretty replay of the agent’s steps.

run

< >

( task: str stream: bool = False reset: bool = True images: typing.Optional[typing.List[str]] = None additional_args: typing.Optional[typing.Dict] = None )

Parameters

  • task (str) — Task to perform.
  • stream (bool) — Whether to run in a streaming way.
  • reset (bool) — Whether to reset the conversation or keep it going from previous run.
  • images (list[str], optional) — Paths to image(s).
  • additional_args (dict) — Any other variables that you want to pass to the agent run, for instance images or dataframes. Give them clear names!

Run the agent for the given task.

Example:

from smolagents import CodeAgent
agent = CodeAgent(tools=[])
agent.run("What is the result of 2 power 3.7384?")

step

< >

( memory_step: ActionStep )

To be implemented in children classes. Should return either None if the step is not final.

visualize

< >

( )

Creates a rich tree visualization of the agent’s structure.

write_memory_to_messages

< >

( summary_mode: typing.Optional[bool] = False )

Reads past llm_outputs, actions, and observations or errors from the memory into a series of messages that can be used as input to the LLM. Adds a number of keywords (such as PLAN, error, etc) to help the LLM.

class smolagents.CodeAgent

< >

( tools: typing.List[smolagents.tools.Tool] model: typing.Callable[[typing.List[typing.Dict[str, str]]], smolagents.models.ChatMessage] prompt_templates: typing.Optional[dict] = None grammar: typing.Optional[typing.Dict[str, str]] = None additional_authorized_imports: typing.Optional[typing.List[str]] = None planning_interval: typing.Optional[int] = None use_e2b_executor: bool = False max_print_outputs_length: typing.Optional[int] = None **kwargs )

Parameters

  • tools (list[Tool]) — Tools that the agent can use.
  • model (Callable[[list[dict[str, str]]], ChatMessage]) — Model that will generate the agent’s actions.
  • prompt_templates (dict, optional) — Prompt templates.
  • grammar (dict[str, str], optional) — Grammar used to parse the LLM output.
  • additional_authorized_imports (list[str], optional) — Additional authorized imports for the agent.
  • planning_interval (int, optional) — Interval at which the agent will run a planning step.
  • use_e2b_executor (bool, default False) — Whether to use the E2B executor for remote code execution.
  • max_print_outputs_length (int, optional) — Maximum length of the print outputs.
  • **kwargs — Additional keyword arguments.

In this agent, the tool calls will be formulated by the LLM in code format, then parsed and executed.

step

< >

( memory_step: ActionStep )

Perform one step in the ReAct framework: the agent thinks, acts, and observes the result. Returns None if the step is not final.

class smolagents.ToolCallingAgent

< >

( tools: typing.List[smolagents.tools.Tool] model: typing.Callable[[typing.List[typing.Dict[str, str]]], smolagents.models.ChatMessage] prompt_templates: typing.Optional[dict] = None planning_interval: typing.Optional[int] = None **kwargs )

Parameters

  • tools (list[Tool]) — Tools that the agent can use.
  • model (Callable[[list[dict[str, str]]], ChatMessage]) — Model that will generate the agent’s actions.
  • prompt_templates (dict, optional) — Prompt templates.
  • planning_interval (int, optional) — Interval at which the agent will run a planning step.
  • **kwargs — Additional keyword arguments.

This agent uses JSON-like tool calls, using method model.get_tool_call to leverage the LLM engine’s tool calling capabilities.

step

< >

( memory_step: ActionStep )

Perform one step in the ReAct framework: the agent thinks, acts, and observes the result. Returns None if the step is not final.

ManagedAgent

This class is deprecated since 1.8.0: now you simply need to pass attributes name and description to a normal agent to make it callable by a manager agent.

stream_to_gradio

smolagents.stream_to_gradio

< >

( agent task: str reset_agent_memory: bool = False additional_args: typing.Optional[dict] = None )

Runs an agent with the given task and streams the messages from the agent as gradio ChatMessages.

GradioUI

You must have gradio installed to use the UI. Please run pip install smolagents[gradio] if it’s not the case.

class smolagents.GradioUI

< >

( agent: MultiStepAgent file_upload_folder: str | None = None )

A one-line interface to launch your agent in Gradio

upload_file

< >

( file file_uploads_log allowed_file_types = ['application/pdf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'text/plain'] )

Handle file uploads, default allowed types are .pdf, .docx, and .txt

< > Update on GitHub

←Build a web browser agent using vision models Model-related objects→