Skip to main content

Documentation Index

Fetch the complete documentation index at: https://next.gentrace.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

For a complete example, see the OpenAI Agents example on GitHub.
Gentrace integrates with OpenAI Agents SDK using OpenInference instrumentation to automatically trace agent conversations, tool calls, and agent handoffs.

​
Prerequisites

​
Installation

pip install gentrace openai openinference-instrumentation-openai-agents

​
Configuration

Initialize Gentrace with OpenAI Agents instrumentation:
openai_agents_instrumentation.py
import os
from openai import OpenAI
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from gentrace import init, interaction

# Initialize Gentrace with OpenAI Agents instrumentation
init(
    api_key=os.getenv("GENTRACE_API_KEY"),
    base_url=os.getenv("GENTRACE_BASE_URL", "https://gentrace.ai/api"),
    otel_setup={
        "service_name": "openai-agents-demo",
        "instrumentations": [OpenAIAgentsInstrumentor()],
    },
)

# Define tools for your agent
def check_weather(city: str) -> str:
    """Get current weather for a city (simulated)."""
    weather_data = {
        "san francisco": "☁️ 62°F, cloudy",
        "new york": "☀️ 75°F, sunny",
        "london": "🌧️ 55°F, rainy",
    }
    return weather_data.get(city.lower(), f"No weather data for {city}")

# Define agent configuration
travel_agent = {
    "name": "Travel Assistant",
    "instructions": "You are a helpful travel agent. You can check weather and book flights for customers.",
    "tools": [{"type": "function", "function": {"name": "check_weather", "description": "Get current weather for a city"}}],
}

# Initialize OpenAI client
from openai import OpenAI
client = OpenAI()

@interaction(name="travel_planning", pipeline_id=os.getenv("GENTRACE_PIPELINE_ID", ""))
def plan_trip(request: str) -> str:
    """Handle a travel planning request - automatically traced."""
    response = client.chat.completions.create(
        model="gpt-4",
        messages=[
            {"role": "system", "content": travel_agent["instructions"]},
            {"role": "user", "content": request}
        ],
        tools=travel_agent["tools"],
    )
    return response.choices[0].message.content

# Usage
response = plan_trip("What's the weather like in San Francisco?")
print(f"Response: {response}")

​
Environment Variables

.env
GENTRACE_API_KEY=your-gentrace-api-key
GENTRACE_PIPELINE_ID=your-pipeline-id
OPENAI_API_KEY=your-openai-api-key

​
What Gets Traced

The OpenAI Agents instrumentation automatically captures:
  • Agent conversations - All messages between users and agents
  • Tool calls - Function invocations with parameters and results
  • Agent handoffs - Transfers between specialized agents
  • Context variables - Shared state between agents
  • Full message history - Complete conversation flow

​
Advanced Features

​
Multiple Agents

# Define specialized agents
weather_agent = {
    "name": "Weather Expert",
    "instructions": "You provide weather information.",
    "tools": [{"type": "function", "function": {"name": "check_weather"}}],
}

booking_agent = {
    "name": "Booking Specialist",
    "instructions": "You handle flight and hotel bookings.",
    "tools": [
        {"type": "function", "function": {"name": "book_flight"}},
        {"type": "function", "function": {"name": "book_hotel"}}
    ],
}

# Agents can coordinate through tool calls
main_agent = {
    "name": "Travel Coordinator",
    "instructions": "Route weather questions to Weather Expert and bookings to Booking Specialist.",
    "tools": [
        {"type": "function", "function": {"name": "transfer_to_weather_agent"}},
        {"type": "function", "function": {"name": "transfer_to_booking_agent"}}
    ],
}

​
Context Variables

# Pass context in the system message or as part of the conversation
context = {"user_preferences": "budget-friendly", "currency": "USD"}
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {
            "role": "system",
            "content": f"{travel_agent['instructions']}\nContext: {context}"
        },
        {"role": "user", "content": "Plan a trip to Paris"}
    ],
    tools=travel_agent["tools"],
)