smolagents

HuggingFace smolagents ships two agent types: CodeAgent (the model writes and executes Python) and ToolCallingAgent (standard OpenAI tool_calls). Both use OpenAIServerModel(api_base=…) to talk to rapid-mlx.

Install

$ pip install smolagents

Config

Exact snippet from tests/integrations/test_smolagents_full.py:

from smolagents import CodeAgent, OpenAIServerModel, ToolCallingAgent, tool

model = OpenAIServerModel(
    model_id="default",
    api_base="http://localhost:8000/v1",
    api_key="not-needed",
)

CodeAgent (executes Python)

CodeAgent writes a Python program that solves the task, executes it, and returns the result. It doesn't rely on OpenAI tool_calls — the "tool" is the code execution loop itself.

agent = CodeAgent(tools=[], model=model, max_steps=3)
out = agent.run("Compute 12 * 8 and return the integer.")
# out contains "96"

CodeAgent + custom tool

@tool
def get_temp(city: str) -> str:
    """Returns the current temperature for a city.

    Args:
        city: Name of the city.
    """
    return f"The temperature in {city} is 18 degrees Celsius."

agent = CodeAgent(tools=[get_temp], model=model, max_steps=4)
out = agent.run("What is the temperature in Tokyo?")

ToolCallingAgent (OpenAI tool_calls)

@tool
def add_nums(a: int, b: int) -> int:
    """Add two integers.

    Args:
        a: first number
        b: second number
    """
    return a + b

agent = ToolCallingAgent(tools=[add_nums], model=model, max_steps=4)
out = agent.run("What is 17 + 25? Use the add_nums tool.")
# out contains "42"

Gotchas

• CodeAgent works with DeepSeek R1-Distill. Because CodeAgent parses Python out of the model's text output (not OpenAI tool_calls), R1's reasoning-only training still produces a working solution. This is why smolagents is the only framework row that's ✅ across all four Tier-1 families on the integration matrix.
• ToolCallingAgent requires a tool-trained model. DeepSeek R1-Distill will XFAIL there — use CodeAgent instead for R1.
• Docstring arg descriptions are load-bearing. smolagents derives JSON-schema from the docstring; missing Args: entries make the tool unusable at inference time.

Empirical

The smolagents row of the integration matrix is ✅ across all four Tier-1 families (Qwen 3.6, Gemma 4, DeepSeek R1-Distill, gpt-oss). Deep flow assertions in test_smolagents_full.py cover CodeAgent arithmetic, CodeAgent with custom tool, ToolCallingAgent with tool, and multi-tool ToolCallingAgent (square + double).

See also