> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://www.comet.com/docs/opik/_mcp/server.

# Observability for Smolagents with Opik

> Start here to integrate Opik into your Smolagents-based genai application for end-to-end LLM observability, unit testing, and optimization.

[Smolagents](https://huggingface.co/docs/smolagents/en/index) is a framework from HuggingFace that allows you to create AI agents with various capabilities.

The framework provides a simple way to build agents that can perform tasks like coding, searching the web, and more with built-in support for multiple tools and LLM providers.

## Account Setup

[Comet](https://www.comet.com/site?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=smolagents\&utm_campaign=opik) provides a hosted version of the Opik platform, [simply create an account](https://www.comet.com/signup?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=smolagents\&utm_campaign=opik) and grab your API Key.

> You can also run the Opik platform locally, see the [installation guide](https://www.comet.com/docs/opik/self-host/overview/?from=llm\&utm_source=opik\&utm_medium=colab\&utm_content=smolagents\&utm_campaign=opik) for more information.

## Getting Started

### Installation

To use the Smolagents integration with Opik, you will need to have Smolagents and the required OpenTelemetry packages installed:

```bash
pip install --upgrade opik 'smolagents[telemetry,toolkit]' opentelemetry-sdk opentelemetry-exporter-otlp
```

### Configuring Smolagents

In order to use Smolagents, you will need to configure your LLM provider API keys. For this example, we'll use OpenAI. You can [find or create your API keys in these pages](https://platform.openai.com/settings/organization/api-keys):

You can set them as environment variables:

```bash
export OPENAI_API_KEY="YOUR_API_KEY"
```

Or set them programmatically:

```python
import os
import getpass

if "OPENAI_API_KEY" not in os.environ:
    os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")
```

### Configuring OpenTelemetry

You will need to set the following environment variables to configure OpenTelemetry to send data to Opik:

#### Opik Cloud

If you are using Opik Cloud, you will need to set the following
environment variables:

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=https://www.comet.com/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
```

> **Tip**
>
> To log the traces to a specific project, you can add the
> `projectName` parameter to the `OTEL_EXPORTER_OTLP_HEADERS`
> environment variable:
>
> ```bash wordWrap
> export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default,projectName=<your-project-name>'
> ```
>
> You can also update the `Comet-Workspace` parameter to a different
> value if you would like to log the data to a different workspace.

#### Enterprise deployment

If you are using an Enterprise deployment of Opik, you will need to set the following
environment variables:

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<comet-deployment-url>/opik/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default'
```

> **Tip**
>
> To log the traces to a specific project, you can add the
> `projectName` parameter to the `OTEL_EXPORTER_OTLP_HEADERS`
> environment variable:
>
> ```bash wordWrap
> export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=default,projectName=<your-project-name>'
> ```
>
> You can also update the `Comet-Workspace` parameter to a different
> value if you would like to log the data to a different workspace.

#### Self-hosted instance

If you are self-hosting Opik, you will need to set the following environment
variables:

```bash
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5173/api/v1/private/otel
```

> **Tip**
>
> To log the traces to a specific project, you can add the `projectName`
> parameter to the `OTEL_EXPORTER_OTLP_HEADERS` environment variable:
>
> ```bash
> export OTEL_EXPORTER_OTLP_HEADERS='projectName=<your-project-name>'
> ```

## Using Opik with Smolagents

To track your Smolagents applications, you will need to configure OpenTelemetry to instrument the framework:

```python
# Import telemetry components
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

# Import SmolAgents instrumentation
from openinference.instrumentation.smolagents import SmolagentsInstrumentor

# Import OTLP exporter
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

# Set up the tracer provider with span processor
trace_provider = TracerProvider()
trace_provider.add_span_processor(
    SimpleSpanProcessor(OTLPSpanExporter())
)

# Instrument SmolAgents
SmolagentsInstrumentor().instrument(tracer_provider=trace_provider)

# Now use SmolAgents as usual
from smolagents import CodeAgent, WebSearchTool, OpenAIServerModel

model = OpenAIServerModel(model_id="gpt-4o")
agent = CodeAgent(
    tools=[WebSearchTool()],
    model=model,
    stream_outputs=True
)

agent.run("How many seconds would it take for a leopard at full speed to run through Pont des Arts?")
```

![Smolagents tracing](https://fdr-prod-docs-files-public.s3.us-east-1.amazonaws.com/opik.docs.buildwithfern.com/5b116a8944ec6322262ccd79a27c1ab91866efdff6309bd1bc42c28f840ab59c/img/cookbook/smolagents_trace_cookbook.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIA6KXJSKKNFOCF7G4B%2F20260925%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260925T151933Z&X-Amz-Expires=604800&X-Amz-Signature=76d18c1a41834f6c1a41c7425705d33672166e39ad45d3314f15833bb75548c2&X-Amz-SignedHeaders=host&x-amz-checksum-mode=ENABLED&x-id=GetObject)

## Further improvements

If you would like to see us improve this integration, simply open a new feature
request on [Github](https://github.com/comet-ml/opik/issues).