Writing actions as code snippets or JSON blobs

Tool Calling Agents are the second type of agent available in smolagents. Unlike Code Agents that use Python snippets, these agents use the built-in tool-calling capabilities of LLM providers to generate tool calls as JSON structures. This is the standard approach used by OpenAI, Anthropic, and many other providers.

Let’s look at an example. When Alfred wants to search for catering services and party ideas, a CodeAgent would generate and run Python code like this:

for query in [
    "Best catering services in Gotham City", 
    "Party theme ideas for superheroes"
]:
    print(web_search(f"Search for: {query}"))

A ToolCallingAgent would instead create a JSON structure:

[
    {"name": "web_search", "arguments": "Best catering services in Gotham City"},
    {"name": "web_search", "arguments": "Party theme ideas for superheroes"}
]

This JSON blob is then used to execute the tool calls.

While smolagents primarily focuses on CodeAgents since they perform better overall, ToolCallingAgents can be effective for simple systems that don’t require variable handling or complex tool calls.

How Do Tool Calling Agents Work?

Tool Calling Agents follow the same multi-step workflow as Code Agents (see the previous section for details).

The key difference is in how they structure their actions: instead of executable code, they generate JSON objects that specify tool names and arguments. The system then parses these instructions to execute the appropriate tools.

Example: Running a Tool Calling Agent

Let’s revisit the previous example where Alfred started party preparations, but this time we’ll use a ToolCallingAgent to highlight the difference. We’ll build an agent that can search the web using DuckDuckGo, just like in our Code Agent example. The only difference is the agent type - the framework handles everything else:

from smolagents import ToolCallingAgent, DuckDuckGoSearchTool, HfApiModel

agent = ToolCallingAgent(tools=[DuckDuckGoSearchTool()], model=HfApiModel())

agent.run("Search for the best music recommendations for a party at the Wayne's mansion.")

When you examine the agent’s trace, instead of seeing Executing parsed code:, you’ll see something like:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Calling tool: 'web_search' with arguments: {'query': "best music recommendations for a party at Wayne's         │
│ mansion"}                                                                                                       │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

The agent generates a structured tool call that the system processes to produce the output, rather than directly executing code like a CodeAgent.

Now that we understand both agent types, we can choose the right one for our needs. Let’s continue exploring smolagents to make Alfred’s party a success! 🎉

Resources

• ToolCallingAgent documentation - Official documentation for ToolCallingAgent