Smolagents (tracing)

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, plus gateway routing through the OpenAI-compatible Respan endpoint.

Set up Respan

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

Paste this into your coding agent:


Help me set up Respan tracing with the Smolagents integration.
Follow https://www.respan.ai/docs/integrations/smolagents.md

Setup

Install packages

Terminal


pip install respan-ai respan-instrumentation-smolagents

Set environment variables

Terminal


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

Python


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.

Python


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.

Python


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.