PythonHandoffs · MCP · Guardrails

Monitor OpenAI Agents SDK with TraceHawk

Full observability for agents built with the OpenAI Agents SDK — handoffs, tool calls, guardrails, and costs in one place.

Install

pip install tracehawk

Initialize

Add this before any agent definitions:

import tracehawk
tracehawk.init(api_key="ao-...")

Example — Agent with tools and handoffs

Agent handoffs are captured as child spans — you can see exactly what context was passed between agents and where the latency lives.

agents.py

import tracehawk
tracehawk.init(api_key="ao-...")

from agents import Agent, Runner, tool, handoff

@tool
def get_stock_price(ticker: str) -> str:
    """Get current stock price for a ticker symbol"""
    # Your implementation
    return f"{ticker}: $150.00"

@tool
def get_news(topic: str) -> str:
    """Get latest news about a topic"""
    return f"Latest news about {topic}..."

# Specialist agents
research_agent = Agent(
    name="Research Agent",
    instructions="You research financial data and news",
    tools=[get_stock_price, get_news],
)

summary_agent = Agent(
    name="Summary Agent",
    instructions="You create concise investment summaries",
    handoffs=[handoff(research_agent)]
)

# Run — full trace including handoffs
result = Runner.run_sync(
    summary_agent,
    "Give me an investment summary for NVDA"
)

Example — with MCP server

agents_mcp.py

import tracehawk
tracehawk.init(api_key="ao-...")

import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async def run():
    async with MCPServerStdio(
        name="filesystem",
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
        }
    ) as mcp_server:
        agent = Agent(
            name="File Agent",
            instructions="Help users manage files",
            mcp_servers=[mcp_server],
        )
        # Every MCP call traced: server=filesystem, tool=read_file, latency, result
        result = await Runner.run(agent, "List files in /tmp and summarize their contents")
        print(result.final_output)

asyncio.run(run())

What you see in TraceHawk

✓Full agent run as one trace with all spans nested
✓Agent handoffs as child spans — see exactly what was passed between agents
✓Tool calls with parameters and return values
✓MCP server calls with per-server analytics in MCP dashboard
✓Guardrail evaluations with pass/fail and latency (if configured)
✓Cost breakdown: which agent spent what

Guardrail visibility

If you use guardrails, each evaluation appears as a span with the input, the guardrail's verdict, and how long it took. Failed guardrails are highlighted in the trace view and trigger the alert engine if you have rules configured.

Handoff tracing

Each handoff from one agent to another creates a parent-child span relationship. In the TraceHawk decision tree view you can see the full handoff chain — which agent delegated to which, with what input, and how long the sub-agent took.

Ready to ship?

Free tier — 50K spans/month. No credit card required.

Get started free →