Docs Integrations

OpenAI Agents SDK

Register one trace processor in Python and every OpenAI Agents SDK trace becomes a Runback run, handoffs and guardrails included. About five minutes.

Before you begin

A Runback account and a Send only key. In the app, open Settings › Keys and access › API key, keep Send only selected, select Generate API key and copy it (it is shown once and starts rb_cloud_). The quickstart walks through it.
Python 3.9 or later (python3 --version).
An OpenAI API key.

Steps

Install the SDK with the Agents extra
terminalShell
```
pip install "runback-sdk[openai-agents]"
```
Expected output
pip ends with a Successfully installed line and no errors.
Set your keys
Runback reads its key from RUNBACK_API_KEY; the model client reads its own.
terminalShell
```
export RUNBACK_API_KEY="<RUNBACK_API_KEY>"
export OPENAI_API_KEY="sk-..."
```
Expected output
Nothing is printed. echo $RUNBACK_API_KEY should print your key.

Register the processor and run an agent

One line, before you run any agent, sends every trace to Runback. It replaces the Agents SDK's default trace exporter. Save this as agent.py and run python agent.py.

agent.pyPython

# agent.py: pip install "runback-sdk[openai-agents]"
import asyncio

from agents import Agent, Runner, function_tool, set_trace_processors
from runback.openai_agents import RunbackTracingProcessor

set_trace_processors([RunbackTracingProcessor()])  # replaces the SDK's default exporter


@function_tool
def get_weather(city: str) -> str:
    """Weather for a city."""
    return f"Sunny in {city}"


agent = Agent(name="Weather bot", instructions="Answer weather questions.", tools=[get_weather])


async def main() -> None:
    result = await Runner.run(agent, "What's the weather in Paris?")
    print(result.final_output)


asyncio.run(main())

Expected output

The agent's answer, e.g. Sunny in Paris, and no [runback] line.

Check the run arrived
Open Runs in the app. Your run is at the top, named Agent workflow (the Agents SDK's default trace name). Open it to step through what the agent did.

Troubleshooting

You see	What it means	Fix
`[runback] no RUNBACK_API_KEY set — dropped 3 events`	The key is not set in the terminal you ran the agent from.	Export `RUNBACK_API_KEY` in the same terminal (a new tab starts without it), then run the agent again.
`[runback] ingest failed 401 {"error":"Invalid API key"}`	Runback rejected the key: mistyped, revoked or expired.	Copy the whole key again, or create a new one in Settings › Keys and access › API key.
`ModuleNotFoundError: No module named 'runback'`	The package went into a different Python environment.	Activate the virtual environment you installed into, or install with the same `python` you run the agent with: `python -m pip install …`.
`openai.OpenAIError: Missing credentials`	`OPENAI_API_KEY` (or your provider's key) is not set.	Run the agent with the provider key set, e.g. `OPENAI_API_KEY=sk-... python agent.py`.
The agent ran, but the run is not in Runs	The key belongs to a different workspace, or you are looking at the shared demo.	Check the workspace name in the top right of the app is the one the key came from.

Your agent never fails because of Runback: if recording fails, the model call still returns and Runback prints one [runback] line saying why.

What Runback records

One run per Agents SDK trace. Model calls become model steps attributed to their agent, function tools become tool steps, and handoffs and guardrails become steps of their own. A tripped guardrail marks the run as an error. The processor observes only: it cannot stop a tool call.

RunbackTracingProcessor on the OpenAI Agents SDK, with a handoff and a guardrail, scripted model. 10 events, captured 9 Oct 2026.

Runstart · Agent workflow

{
  "error": null,
  "input": null,
  "metadata": {
    "framework": "openai-agents",
    "trace_id": "trace_bbe1d07f31904922b8ca690748c297e2"
  },
  "name": "Agent workflow",
  "output": null,
  "parent_span_id": null,
  "phase": "start",
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 0,
  "span_id": "01M4G4WRA7J5NH0AQTDDHA5HCA",
  "status": "running",
  "ts_end": null,
  "ts_start": "2026-10-09T10:56:10.055Z",
  "type": "run"
}

Stepagent

{
  "label": "agent",
  "parent_span_id": "01M4G4WRA7J5NH0AQTDDHA5HCA",
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 1,
  "span_id": "01M4G4WRA9VV69YPR98S8KRYEK",
  "text": "[agent] Triage",
  "ts_end": "2026-10-09T10:56:10.057Z",
  "ts_start": "2026-10-09T10:56:10.057Z",
  "type": "reasoning"
}

Stepguardrail

{
  "label": "guardrail",
  "parent_span_id": "01M4G4WRA7J5NH0AQTDDHA5HCA",
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 2,
  "span_id": "01M4G4WRA9VV69YPR98S8KRYEM",
  "text": "[guardrail] no_profanity: passed",
  "ts_end": "2026-10-09T10:56:10.057Z",
  "ts_start": "2026-10-09T10:56:10.057Z",
  "type": "reasoning"
}

Modelgpt-4.1 → transfer_to_weather_agent17 tokens · 333 ms · called a tool

{
  "error": null,
  "latency_ms": 333,
  "metadata": {
    "agent": "Triage",
    "framework": "openai-agents"
  },
  "model": {
    "model_id": "gpt-4.1",
    "provider": "openai"
  },
  "parent_span_id": "01M4G4WRA7J5NH0AQTDDHA5HCA",
  "request": {
    "messages": [
      {
        "content": "Weather in Paris? cc [redacted:email]",
        "role": "user"
      }
    ],
    "params": {
      "temperature": 1,
      "top_p": 1
    },
    "system": "Route the user.",
    "tools": [
      {
        "description": "Handoff to the Weather agent agent to handle the request. ",
        "name": "transfer_to_weather_agent",
        "parameters": {
          "additionalProperties": false,
          "properties": {},
          "required": [],
          "type": "object"
        }
      }
    ]
  },
  "response": {
    "finish_reason": "tool_calls",
    "reasoning": null,
    "text": null,
    "tool_calls": [
      {
        "input": {},
        "tool_call_id": "call_17",
        "tool_name": "transfer_to_weather_agent"
      }
    ]
  },
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 3,
  "span_id": "01M4G4WRMRKB9FP4J53KF33Y2Z",
  "ts_end": "2026-10-09T10:56:10.393Z",
  "ts_start": "2026-10-09T10:56:10.058Z",
  "type": "llm",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 5,
    "total_tokens": 17
  }
}

Stephandoff

{
  "label": "handoff",
  "parent_span_id": "01M4G4WRMRKB9FP4J53KF33Y2Z",
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 4,
  "span_id": "01M4G4WRMVN37MAX1E5RYK8GHA",
  "text": "[handoff] Triage → Weather agent",
  "ts_end": "2026-10-09T10:56:10.395Z",
  "ts_start": "2026-10-09T10:56:10.395Z",
  "type": "reasoning"
}

Stepagent

{
  "label": "agent",
  "parent_span_id": "01M4G4WRMRKB9FP4J53KF33Y2Z",
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 5,
  "span_id": "01M4G4WRMWWK3AY8083NM55DD5",
  "text": "[agent] Weather agent",
  "ts_end": "2026-10-09T10:56:10.396Z",
  "ts_start": "2026-10-09T10:56:10.396Z",
  "type": "reasoning"
}

Modelgpt-4.1 → get_weather17 tokens · 4 ms · called a tool

{
  "error": null,
  "latency_ms": 4,
  "metadata": {
    "agent": "Weather agent",
    "framework": "openai-agents"
  },
  "model": {
    "model_id": "gpt-4.1",
    "provider": "openai"
  },
  "parent_span_id": "01M4G4WRA7J5NH0AQTDDHA5HCA",
  "request": {
    "messages": [
      {
        "content": "Weather in Paris? cc [redacted:email]",
        "role": "user"
      },
      {
        "content": [
          {
            "input": {},
            "toolCallId": "call_17",
            "toolName": "transfer_to_weather_agent",
            "type": "tool-call"
          }
        ],
        "role": "assistant"
      },
      {
        "content": [
          {
            "output": {
              "assistant": "Weather agent"
            },
            "toolCallId": "call_17",
            "type": "tool-result"
          }
        ],
        "role": "tool"
      }
    ],
    "params": {
      "temperature": 1,
      "top_p": 1
    },
    "system": "Answer weather questions.",
    "tools": [
      {
        "description": "Weather for a city.",
        "name": "get_weather",
        "parameters": {
          "additionalProperties": false,
          "properties": {
            "city": {
              "title": "City",
              "type": "string"
            }
          },
          "required": [
            "city"
          ],
          "title": "get_weather_args",
          "type": "object"
        }
      }
    ]
  },
  "response": {
    "finish_reason": "tool_calls",
    "reasoning": null,
    "text": null,
    "tool_calls": [
      {
        "input": {
          "city": "Paris"
        },
        "tool_call_id": "call_20",
        "tool_name": "get_weather"
      }
    ]
  },
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 6,
  "span_id": "01M4G4WRN1QE8MZ6ZJAGQ9VYXZ",
  "ts_end": "2026-10-09T10:56:10.401Z",
  "ts_start": "2026-10-09T10:56:10.396Z",
  "type": "llm",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 5,
    "total_tokens": 17
  }
}

Toolget_weather

{
  "error": null,
  "input": {
    "city": "Paris"
  },
  "latency_ms": 0,
  "metadata": {
    "agent": "Weather agent",
    "framework": "openai-agents"
  },
  "output": {
    "city": "Paris",
    "forecast": "sunny"
  },
  "parent_span_id": "01M4G4WRN1QE8MZ6ZJAGQ9VYXZ",
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 7,
  "span_id": "01M4G4WRN3Y0APXKDSMV6AMZNS",
  "tool_call_id": "call_20",
  "tool_name": "get_weather",
  "ts_end": "2026-10-09T10:56:10.403Z",
  "ts_start": "2026-10-09T10:56:10.402Z",
  "type": "tool"
}

Modelgpt-4.128 tokens · 4 ms · finished

{
  "error": null,
  "latency_ms": 4,
  "metadata": {
    "agent": "Weather agent",
    "framework": "openai-agents"
  },
  "model": {
    "model_id": "gpt-4.1",
    "provider": "openai"
  },
  "parent_span_id": "01M4G4WRA7J5NH0AQTDDHA5HCA",
  "request": {
    "messages": [
      {
        "content": "Weather in Paris? cc [redacted:email]",
        "role": "user"
      },
      {
        "content": [
          {
            "input": {},
            "toolCallId": "call_17",
            "toolName": "transfer_to_weather_agent",
            "type": "tool-call"
          }
        ],
        "role": "assistant"
      },
      {
        "content": [
          {
            "output": {
              "assistant": "Weather agent"
            },
            "toolCallId": "call_17",
            "type": "tool-result"
          }
        ],
        "role": "tool"
      },
      {
        "content": [
          {
            "input": {
              "city": "Paris"
            },
            "toolCallId": "call_20",
            "toolName": "get_weather",
            "type": "tool-call"
          }
        ],
        "role": "assistant"
      },
      {
        "content": [
          {
            "output": {
              "city": "Paris",
              "forecast": "sunny"
            },
            "toolCallId": "call_20",
            "type": "tool-result"
          }
        ],
        "role": "tool"
      }
    ],
    "params": {
      "temperature": 1,
      "top_p": 1
    },
    "system": "Answer weather questions.",
    "tools": [
      {
        "description": "Weather for a city.",
        "name": "get_weather",
        "parameters": {
          "additionalProperties": false,
          "properties": {
            "city": {
              "title": "City",
              "type": "string"
            }
          },
          "required": [
            "city"
          ],
          "title": "get_weather_args",
          "type": "object"
        }
      }
    ]
  },
  "response": {
    "finish_reason": "completed",
    "reasoning": null,
    "text": "It is sunny in Paris.",
    "tool_calls": []
  },
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 8,
  "span_id": "01M4G4WRN9YEHXS03WJ0CBY12C",
  "ts_end": "2026-10-09T10:56:10.409Z",
  "ts_start": "2026-10-09T10:56:10.404Z",
  "type": "llm",
  "usage": {
    "input_tokens": 20,
    "output_tokens": 8,
    "total_tokens": 28
  }
}

Runend · Agent workflowsucceeded

{
  "error": null,
  "input": null,
  "metadata": {
    "cassette_digest": "dfe948b755473d201c094d57babc90acfb100d4566f7686afc85baa0d6cb869a",
    "cassette_entries": 4,
    "redaction_by_type": {
      "email": 3
    },
    "redaction_count": 3
  },
  "name": "Agent workflow",
  "output": null,
  "parent_span_id": "01M4G4WRA7J5NH0AQTDDHA5HCA",
  "phase": "end",
  "run_id": "01M4G4WRA7J5NH0AQTDDHA5HC9",
  "schema_version": 1,
  "seq": 9,
  "span_id": "01M4G4WRNA2QZZFRZ090SGSSNE",
  "status": "success",
  "ts_end": "2026-10-09T10:56:10.410Z",
  "ts_start": "2026-10-09T10:56:10.410Z",
  "type": "run"
}

The events this integration really sent, redacted in its own process, from a run in Runback's test suite. The model is scripted, so its name and its answers are the test's. The suite re-checks them on every change.

What it can and cannot do

OpenAI Agents SDK

Question	Answer	Why
Context	Full	Instructions, input items and tools; handoffs and guardrails as steps of their own.
Redaction	In your process	On by default.
Stop before it runs	No	The SDK's trace processor only observes.
Replay	Re-issue only	A model step can be re-sent to a live model. The whole run can't be re-run with the same tool results: they aren't kept.
Signed record	Yes	Each run is hash-chained and can be exported as a signed record.

Next steps

See what a run holds: Capture.
Re-send a recorded model step to another model: Replay.

#Before you begin

#Steps

Install the SDK with the Agents extra

Set your keys

Register the processor and run an agent

Check the run arrived

#Troubleshooting

#What Runback records

#What it can and cannot do