OpenAI Agents SDK

Connect your OpenAI Agents SDK application to Latitude for observability.

Overview

This guide shows you how to integrate Latitude Telemetry into an application that uses the OpenAI Agents SDK (@openai/agents for TypeScript, openai-agents for Python).

Latitude includes dedicated instrumentation for the OpenAI Agents SDK, so agent runs, generations, function calls, handoffs, and guardrails appear as traces.

You’ll keep calling the Agents SDK exactly as you do today. Telemetry observes agent runs, tool calls, and handoffs as they happen.

---

Requirements

• A Latitude account and API key
• A Latitude project slug
• A project that uses the OpenAI Agents SDK

---

Steps

1. Install

   TypeScript

   npm

   npm install @latitude-data/telemetry @openai/agents
   

   Python

   pip

   pip install latitude-telemetry openai-agents
   
2. Initialize and use

   TypeScript

   import { Latitude, capture } from "@latitude-data/telemetry"
   import { Agent, run, tool } from "@openai/agents"
   import * as OpenAIAgentsSDK from "@openai/agents"
   import { z } from "zod"
   
   const latitude = new Latitude({
     apiKey: process.env.LATITUDE_API_KEY!,
     project: process.env.LATITUDE_PROJECT_SLUG!,
     instrumentations: { "openai-agents": OpenAIAgentsSDK },
   })
   
   
   const getWeather = tool({
     name: "get_weather",
     description: "Returns the current weather for a city.",
     parameters: z.object({ city: z.string() }),
     execute: async ({ city }) => `The weather in ${city} is sunny.`,
   })
   
   const agent = new Agent({
     name: "Weather agent",
     instructions: "Answer weather questions using get_weather.",
     tools: [getWeather],
     model: "gpt-4o-mini",
   })
   
   await capture("weather-agent-run", () =>
     run(agent, "What's the weather in Barcelona?"),
   )
   
   await latitude.shutdown()
   

   Python

   import agents
   from agents import Agent, Runner
   
   from latitude_telemetry import Latitude, capture
   
   latitude = Latitude(
       api_key="your-api-key",
       project="your-project-slug",
       instrumentations={"openai-agents": agents},
   )
   
   agent = Agent(
       name="Weather agent",
       instructions="Answer weather questions concisely.",
       model="gpt-4o-mini",
   )
   
   async def weather_agent_run():
       return await Runner.run(agent, "What's the weather in Barcelona?")
   
   capture("weather-agent-run", weather_agent_run)
   
   latitude.shutdown()
   

---

What you get

Each agent run shows up as a trace with nested spans:

• Agent spans — agent name, configured tools, handoff targets, output type
• Generation / Response spans — model, input/output messages, token usage, response id
• Function spans — tool calls with input arguments and output
• Handoff spans — from_agent → to_agent
• Guardrail spans — guardrail name and whether it triggered
• MCP spans — listed tools per server

Wrap a request or job with capture() to attach a userId, sessionId, tags, or metadata to every span produced inside.

---

Seeing Your Traces

Once connected, traces appear automatically in Latitude:

1. Open your project in the Latitude dashboard
2. Each agent run shows the full hierarchy of agent → generation/response → tool calls and handoffs
3. Token usage and latency are aggregated at every level