Installation
- pip
- uv
- npm
- yarn
- pnpm
pip install "pandaprobe[openai-agents]"
uv add "pandaprobe[openai-agents]"
npm install pandaprobe @openai/agents
yarn add pandaprobe @openai/agents
pnpm add pandaprobe @openai/agents
Setup
- Python
- TypeScript
Python
from pandaprobe.integrations.openai_agents import OpenAIAgentsAdapter
adapter = OpenAIAgentsAdapter(
session_id="conversation-123",
user_id="user-abc",
tags=["production"],
)
adapter.instrument()
TypeScript
import { OpenAIAgentsAdapter } from "pandaprobe/integrations/openai-agents";
const adapter = new OpenAIAgentsAdapter({
sessionId: "conversation-123",
userId: "user-abc",
tags: ["production"],
});
await adapter.instrument();
instrument() once during application startup, before running agents.We recommend using UUIDs for
session_id and user_id so traces can be grouped reliably across runs.Usage
Python
from agents import Agent, Runner
agent = Agent(
name="my-assistant",
instructions="You are a helpful assistant.",
model="gpt-5.4",
)
result = Runner.run_sync(agent, "What is PandaProbe?")
print(result.final_output)
TypeScript
import { Agent, run } from "@openai/agents";
const agent = new Agent({
name: "my-assistant",
instructions: "You are a helpful assistant.",
model: "gpt-5.6-terra",
});
const result = await run(agent, "What is PandaProbe?");
console.log(result.finalOutput);
What gets traced
| SDK Span Type | PandaProbe Kind | Description |
|---|---|---|
agent | AGENT | Agent execution with tools, handoffs, output_type metadata |
handoff | AGENT | Agent handoff with from_agent / to_agent metadata |
response | LLM | Responses API call with input, output, model, usage, reasoning |
generation | LLM | Chat Completions call with messages, model, usage |
function | TOOL | Function tool call with JSON-parsed input/output |
guardrail | OTHER | Guardrail check with triggered metadata |
custom | OTHER | Custom span with custom_data metadata |
I/O propagation
The adapter automatically propagates input/output from LLM spans to their parent agent and the root trace:- First LLM input becomes the agent span’s input
- Last LLM output becomes the agent span’s output
- Last user message becomes the trace input; last assistant message becomes the trace output
Token usage mapping
| OpenAI Agents Field | PandaProbe Field |
|---|---|
input_tokens / prompt_tokens | prompt_tokens |
output_tokens / completion_tokens | completion_tokens |
total_tokens | total_tokens |
input_tokens_details.cached_tokens | cache_read_tokens |
output_tokens_details.reasoning_tokens | reasoning_tokens |
Example
Python
import asyncio
import uuid
from agents import Agent, Runner, function_tool
import pandaprobe
from pandaprobe.integrations.openai_agents import OpenAIAgentsAdapter
SESSION_ID = str(uuid.uuid4())
USER_ID = "user_1"
@function_tool
def get_weather(city: str) -> str:
"""Get the current weather for a city."""
weather_data = {
"london": "Cloudy, 15°C, 70% humidity",
"tokyo": "Sunny, 28°C, 45% humidity",
"new york": "Partly cloudy, 22°C, 55% humidity",
"paris": "Rainy, 12°C, 85% humidity",
}
return weather_data.get(city.lower(), f"No weather data for {city}")
@function_tool
def get_population(city: str) -> str:
"""Get the approximate population of a city."""
populations = {
"london": "8.8 million",
"tokyo": "13.9 million",
"new york": "8.3 million",
"paris": "2.2 million",
}
return populations.get(city.lower(), f"Unknown population for {city}")
async def main():
adapter = OpenAIAgentsAdapter(
session_id=SESSION_ID,
user_id=USER_ID,
tags=["tool-agent", "example"],
)
adapter.instrument()
agent = Agent(
name="City Info Agent",
instructions=(
"You are a helpful assistant with access to weather and population tools. "
"Use the tools to answer questions about cities."
),
model="gpt-5.4-nano",
tools=[get_weather, get_population],
)
result = await Runner.run(agent, "What's the weather in London and what's its population?")
print(f"Agent: {result.final_output}")
pandaprobe.flush()
pandaprobe.shutdown()
print(f"\nTrace sent to PandaProbe backend (session={SESSION_ID}).")
if __name__ == "__main__":
asyncio.run(main())
TypeScript
import { Agent, run } from "@openai/agents";
import { flush } from "pandaprobe";
import { OpenAIAgentsAdapter } from "pandaprobe/integrations/openai-agents";
const adapter = new OpenAIAgentsAdapter({ tags: ["openai-agents"] });
await adapter.instrument();
const agent = new Agent({
name: "Assistant",
instructions: "You are concise.",
model: "gpt-5.6-terra",
});
const result = await run(agent, "What is the capital of France?");
console.log(result.finalOutput);
await flush();
CHAIN (root) → AGENT (City Info Agent) → LLM (model call) → TOOL (get_weather) → TOOL (get_population) → LLM (final response).