Smolagents (tracing) | Respan Docs

Smolagents is HuggingFace’s lightweight agent framework that lets you build agents with code-based actions. It focuses on simplicity and supports both code agents and tool-calling agents. Respan gives you full observability over every agent run, planning step, code execution, tool call, and LLM generation — and gateway routing through the OpenAI-compatible Respan endpoint.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

Run npx @respan/cli setup to set up with your coding agent.

Use Respan Gateway

See Smolagents gateway setup to route this integration through the Respan gateway.

Example projects

Example projects root

Setup

Install packages

pip install respan-ai respan-instrumentation-smolagents

Set environment variables

export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

OPENAI_API_KEY is used for LLM requests. RESPAN_API_KEY is used to export traces to Respan.

Initialize and run

from respan import Respan, workflow
from respan_instrumentation_smolagents import SmolagentsInstrumentor
from smolagents import CodeAgent, DuckDuckGoSearchTool, LiteLLMModel
respan = Respan(instrumentations=[SmolagentsInstrumentor()])
model = LiteLLMModel(model_id="openai/gpt-4o-mini")
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool()],
    model=model,
)
@workflow(name="smolagents_code_agent_workflow")
def run_agent():
    return agent.run("What is the latest news about AI agents?")
result = run_agent()
print(result)
respan.shutdown()

View your trace

Open the Traces page to see your Smolagents workflow, identified by smolagents_code_agent_workflow, with planning steps, code execution, tool calls, and LLM generations.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate (e.g. `SmolagentsInstrumentor()`).
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag (e.g. `"production"`).

Attributes

In Respan()

Set defaults at initialization — these apply to all spans.

from respan import Respan
from respan_instrumentation_smolagents import SmolagentsInstrumentor
respan = Respan(
    instrumentations=[SmolagentsInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "smolagents-api", "version": "1.0.0"},
)

With propagate_attributes

Override per-request using a context scope.

from respan import Respan, propagate_attributes
from respan_instrumentation_smolagents import SmolagentsInstrumentor
respan = Respan(instrumentations=[SmolagentsInstrumentor()])
def handle_request(user_id: str, message: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        print(agent.run(message))

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.