smolagents

Overview

smolagents is Hugging Face's Python library for building agents that call tools or execute code. Confident AI allows you to trace smolagents with a single call to init() — agent runs show up in the Observatory, so you can follow their execution and inspect the model and tool calls beneath them.

Auto-Instrument

1. Install Dependencies

   Run the following command to install confident-trace along with smolagents and the model provider SDK your agent uses (the example below uses OpenAI):

   pip install confident-trace 'smolagents[openai]'

2. Setup Confident AI Key

   Get your Confident AI Project API key and set it as an environment variable, or pass it to init() directly:

   export CONFIDENT_API_KEY="<your-confident-api-key>"
   export OPENAI_API_KEY="<your-openai-key>"

3. Configure smolagents

   Call init() once at startup, before running your agent. The installed framework is detected automatically.

   import os
   
   from confident_trace import init, shutdown
   from smolagents import OpenAIModel, ToolCallingAgent
   
   init()
   
   agent = ToolCallingAgent(
       model=OpenAIModel("gpt-4o-mini", api_key=os.environ["OPENAI_API_KEY"]),
       tools=[],
   )
   
   try:
       result = agent.run("Explain OpenTelemetry in one sentence.")
       print(result)
   finally:
       shutdown()

4. Run smolagents

   Run your agent by executing the script:

   python main.py

   Done ✅. Open the Observatory in your Confident AI project to inspect the trace and its child spans.

What Gets Captured

• Agent runs — the task, final answer, timing, status, and execution hierarchy.
• Planning and steps — planning operations and execution steps for ToolCallingAgent and CodeAgent.
• Local tool calls — tool names and their input/output.
• Model calls — messages, model details, and token usage from supported provider integrations.
• Custom spans — application spans created inside local tools remain nested under those tools.

Regular and streamed runs are supported. Consume streams fully, or close them when stopping early. Tool execution inside a separate sandbox or remote process is outside the local tool instrumentation's scope.

Captured inputs, outputs, and messages follow the content policy. Model backends that bypass supported provider integrations require explicit instrumentation for LLM spans.

Set Trace Span Properties

Use a trace context to add properties you know before the call starts. It creates no extra span; the trace started by agent.run() inherits the tags, metadata, and user ID.

from confident_trace import init, trace_context

init()

with trace_context(
    tags=["support"],
    metadata={"release": "2026-09"},
    user_id="user-42",
):
    result = agent.run("Explain OpenTelemetry in one sentence.")

See trace context for every supported trace property and update behavior.

Instrumenting Multi-Turn

You do not need turn() when one smolagents entry-point call is already one conversational turn—the integration creates that turn's trace automatically. Use turn() when you want to define the boundary yourself, such as grouping two sequential smolagents calls into one turn. Reuse the same thread ID on later turns to group them into one conversation.

from confident_trace import init, turn

init()

with turn("support-turn", thread_id="chat-42"):
    context = agent.run("Find the relevant account details.")
    answer = agent.run(f"Summarize these details: {context}")

See threads for thread I/O, turn IDs, and user IDs.

Disable smolagents Instrumentation

Pass init() a list of integration identifiers to opt in to only those integrations. The identifier for smolagents is "smolagents" in Python; omit it to disable this integration. An empty list disables all automatic instrumentation:

from confident_trace import init
init(instrumentations=())
# Use ("smolagents",) to opt in; omit "smolagents" to disable it.

This turns off Confident AI's automatic instrumentation; calls made after initialization are not instrumented by this integration.

Next Steps

Now that your agent is traced, dive deeper into:

Last updated on September 11, 2026