Smolagents

Integrate Hugging Face Smolagents with Agent Kernel.

Installation

pip install agentkernel[smolagents]

Basic Usage

from smolagents import LiteLLMModel, ToolCallingAgent
from agentkernel.cli import CLI
from agentkernel.smolagents import SmolagentsModule

model = LiteLLMModel(model_id="openai/gpt-4o")

agent = ToolCallingAgent(
    tools=[],
    model=model,
    name="assistant",
    description="You are a helpful AI assistant.",
)

SmolagentsModule([agent])

if __name__ == "__main__":
    CLI.main()

Multi-Agent Setup

from smolagents import LiteLLMModel, ToolCallingAgent
from agentkernel.smolagents import SmolagentsModule

model = LiteLLMModel(model_id="openai/gpt-4o")

general_agent = ToolCallingAgent(
    tools=[],
    model=model,
    name="general",
    description="General assistant for broad user questions.",
)

math_agent = ToolCallingAgent(
    tools=[],
    model=model,
    name="math",
    description="Specialist agent for math questions.",
)

SmolagentsModule([general_agent, math_agent])

Configuration

export OPENAI_API_KEY=sk-...

If you use another LiteLLM provider, set its credentials instead.

Tool Binding

Use SmolagentsToolBuilder to bind plain Python functions as tools to your Smolagents agents:

from smolagents import LiteLLMModel, ToolCallingAgent
from agentkernel.smolagents import SmolagentsModule, SmolagentsToolBuilder

def get_weather(city: str) -> str:
    """Returns the weather for a given city."""
    return f"Weather in {city}: sunny, 25C"

model = LiteLLMModel(model_id="openai/gpt-4o")

agent = ToolCallingAgent(
    tools=SmolagentsToolBuilder.bind([get_weather]),
    model=model,
    name="weather",
    description="Use the get_weather tool for weather questions.",
)

SmolagentsModule([agent])

See Tools for the full guide on writing and binding tools.

Structured Output

SmolAgents has no first-class schema parameter; the agent returns whatever value is passed to final_answer. Agent Kernel detects the value's type: a dict or Pydantic instance is returned as an AgentReplyAny whose content is the result as a dict; anything else is stringified into an AgentReplyText as before:

from smolagents import CodeAgent
from agentkernel.smolagents import SmolagentsModule

agent = CodeAgent(
    tools=[],
    model=model,
    name="classifier",
    description="Classify the input and return a dict: {\"verdict\": ..., \"confidence\": ...}",
)

SmolagentsModule([agent])

Pydantic results are converted via model_dump(), and str(reply) returns the JSON-serialized content, so text-based consumers work unchanged. See Reply Types for how structured replies are surfaced, and Execution Hooks for how hooks receive them.

Streaming limitation

Structured output applies to non-streaming execution only. Agent Kernel's Smolagents adapter does not implement Runner.stream() yet (smolagents itself supports streaming).

Per-run context/state

Smolagents round-trips a filtered subset of the reserved framework_context session key. It is injected as agent.run(..., additional_args=...); on write-back the runner reads agent.state but keeps only the keys you pre-seeded (framework-internal entries have no clean prefix to filter on). Consequence: a tool that mutates a pre-seeded key round-trips, but a tool that adds a brand-new key has it silently dropped — pre-seed every key you intend to write.

The context is also sent to the model

additional_args is not a private state slot. Smolagents merges it into agent.state and appends it to the task text, so the whole context dict is stringified into the prompt on every turn — that is how the model learns which variables it can reference. Two implications: the prompt (and its token cost) grows with your context, and anything you put in framework_context is shown to the model. Keep credentials, tokens and PII out of it on smolagents; use a non-round-tripped session key for those instead.

Native run options

agent.run's own arguments (max_steps, images) are declared per agent with Module.run_options; Agent Kernel merges them into the call and writes the keys it owns (reset, additional_args) last:

SmolagentsModule([agent]).run_options(agent, max_steps=6)

Progress hooks need nothing from Agent Kernel here: smolagents takes step_callbacks on the agent constructor, which you already own. agent.run is called through asyncio.to_thread, which carries the context variables, so Session.current() resolves inside a step callback.

Reserved (raise ValueError at declaration): task, reset, additional_args, stream and return_full_result (the last two change the return type the adapter maps).

Features

• ✅ ToolCalling and CodeAgent support
• ✅ Managed agent delegation
• ✅ Session management via Agent Kernel runtime
• ✅ Framework-agnostic tool binding
• ✅ Structured output (dict / Pydantic final_answer → AgentReplyAny)

Example

See examples/cli/smolagents for complete examples.

For per-agent native run options, see examples/cli/smolagents-run-options (max_steps, with progress via the native step_callbacks constructor argument and a deterministic Run stats: line on every reply).