OpenAI Integration

Wrap the OpenAI client once and every API call is automatically traced. AgentLens captures the model name, token usage, cost, latency, input messages, and output completions.

Installation

terminal

pip install vectry-agentlens openai

Quick setup

main.py

import agentlens
from agentlens.integrations.openai import wrap_openai
import openai

agentlens.init(
    api_key="your-api-key",
    endpoint="https://agentlens.vectry.tech",
)

client = wrap_openai(openai.OpenAI())

# All calls are now auto-traced
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in one paragraph."},
    ],
)

What gets captured

Each OpenAI API call creates an LLM_CALL span with the following data:

Field	Description
input.model	Model name (gpt-4o, gpt-4o-mini, etc.)
input.messages	Full message array sent to the API
output.content	Response content from the model
tokenCount	Total tokens (prompt + completion)
costUsd	Estimated cost based on model pricing
durationMs	Wall-clock time for the request
metadata.finish_reason	How the model stopped (stop, length, tool_calls)

Async client

The wrapper works with both sync and async OpenAI clients:

async_example.py

from agentlens.integrations.openai import wrap_openai
import openai

async_client = wrap_openai(openai.AsyncOpenAI())

response = await async_client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

Combining with @trace

When used inside a @trace-decorated function, OpenAI calls appear as child spans of the trace:

combined.py

import agentlens
from agentlens import trace
from agentlens.integrations.openai import wrap_openai
import openai

agentlens.init(api_key="...", endpoint="...")
client = wrap_openai(openai.OpenAI())

@trace(name="research-agent")
async def research(topic: str) -> str:
    # This LLM call becomes a child span of "research-agent"
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[
            {"role": "system", "content": "Summarize the following topic."},
            {"role": "user", "content": topic},
        ],
    )
    return response.choices[0].message.content

Tool calls

When the model invokes tools (function calling), AgentLens automatically captures each tool call as a TOOL_SELECTION decision point and the tool execution as a TOOL_CALL span:

tools.py

@trace(name="tool-agent")
async def agent_with_tools(prompt: str):
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": prompt}],
        tools=[{
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get weather for a city",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "city": {"type": "string"}
                    },
                },
            },
        }],
    )
    # AgentLens captures the tool selection decision automatically
    return response

Supported API methods

chat.completions.create() — Chat completions (including streaming)
completions.create() — Legacy completions
embeddings.create() — Embedding generation