> ## Documentation Index
> Fetch the complete documentation index at: https://docs.latitude.so/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

***

## Requirements

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

***

## Steps

<Steps>
  <Step title="Install">
    <Tabs>
      <Tab title="TypeScript">
        <CodeGroup>
          ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark"}}
          npm install @latitude-data/telemetry @openai/agents
          ```

          ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark"}}
          pnpm add @latitude-data/telemetry @openai/agents
          ```

          ```bash yarn theme={"theme":{"light":"github-light","dark":"github-dark"}}
          yarn add @latitude-data/telemetry @openai/agents
          ```

          ```bash bun theme={"theme":{"light":"github-light","dark":"github-dark"}}
          bun add @latitude-data/telemetry @openai/agents
          ```
        </CodeGroup>
      </Tab>

      <Tab title="Python">
        <CodeGroup>
          ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark"}}
          pip install latitude-telemetry openai-agents
          ```

          ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark"}}
          uv add latitude-telemetry openai-agents
          ```

          ```bash poetry theme={"theme":{"light":"github-light","dark":"github-dark"}}
          poetry add latitude-telemetry openai-agents
          ```
        </CodeGroup>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Initialize and use">
    <Tabs>
      <Tab title="TypeScript">
        ```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
        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()
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
        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()
        ```
      </Tab>
    </Tabs>
  </Step>
</Steps>

***

## 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