Skip to content
Back to integrations

§ INTEGRATION · OPENAI AGENTS SDK

OpenAI Agents SDK tracing processor

Install the optional extra, register the processor once, and every agent, generation, tool, handoff, and guardrail span is governed and traced — no decorators, no wrappers.

§ 01

Prerequisites

  • Execlave account with an active API key — Settings → API keys.
  • A registered agent in Execlave. Use the agent's lowercase-kebab agent_id when constructing the processor.
  • Python >=3.10 and openai-agents >=0.0.1.
  • JavaScript is not yet supported for the Agents SDK — use the LangChain handler for JS workloads.
§ 02

Install

The processor is behind a Python extra so the default SDK install does not pull openai-agents as a transitive dependency.

Python

pip install 'execlave-sdk[openai-agents]'
§ 03

Instant setup with a copilot

Paste this prompt into your AI coding assistant. It will register the tracing processor at startup without touching any Agent, tool, or guardrail definitions.

§ Copy prompt · paste into your AI coding assistant
You are adding Execlave (an AI agent governance platform) to an existing Python project that uses the OpenAI Agents SDK. Do not rewrite existing Agent/Runner code — only register a tracing processor. Rules you MUST follow:1. Install the correct extra: `pip install 'execlave-sdk[openai-agents]'`. Add it to requirements.txt / pyproject.toml.2. Read `EXECLAVE_API_KEY` from environment variables. Never hardcode keys. Add it to `.env.example`.3. Create exactly ONE Execlave client per process and reuse it: `exe = Execlave(api_key=os.environ["EXECLAVE_API_KEY"])`.4. Register the processor at startup, ONCE, before any `Runner.run` / `Runner.run_sync` call:   ```python   from agents import set_trace_processors   from execlave.integrations.openai_agents import ExeclaveTracingProcessor   set_trace_processors([ExeclaveTracingProcessor(exe, agent_id="<stable-kebab-id>")])   ```   The `agent_id` is a stable string identifying this agent in the Execlave dashboard. It is NOT the OpenAI Agent's runtime name.5. `set_trace_processors` REPLACES the default processor list. If the project already calls `add_trace_processor` with its own processor, use `add_trace_processor(ExeclaveTracingProcessor(...))` instead of `set_trace_processors` to preserve it.6. Wrap `Runner.run_sync` / `Runner.run` calls in try/except for `execlave.errors.PolicyBlockedError`. On block, return a structured 4xx payload containing `exc.violations`. Do NOT swallow the error silently.7. Do NOT manually call `exe.enforce_policy` before tools — the processor already enforces on every `FunctionSpanData` before the tool is invoked.8. On process shutdown (ASGI lifespan / SIGTERM handler), call `exe.flush()` so in-flight spans are not dropped. The processor's own `shutdown()`/`force_flush()` is also wired to this.9. JavaScript is NOT supported for the OpenAI Agents SDK yet. If the project is Node/TS, stop and tell me — use the LangChain handler instead. Deliverables:- Edit only the startup/bootstrap file (usually `main.py`, `app.py`, or the ASGI factory). Show one diff per file.- Do not touch existing Agent definitions, tools, guardrails, or handoffs.- Add `EXECLAVE_API_KEY` and optional `EXECLAVE_BASE_URL` to `.env.example`. Reference: https://www.execlave.com/docs/integrations/openai-agentsAPI reference: https://www.execlave.com/docs/sdk-reference
§ 04

Quick start

Register one ExeclaveTracingProcessor at startup. Every subsequent Runner.run / Runner.run_sync call is traced and governed.

Python

from agents import Agent, Runner, set_trace_processorsfrom execlave import Execlavefrom execlave.integrations.openai_agents import ExeclaveTracingProcessor exe = Execlave(api_key="exe_live_...") # Register ONCE at process startup. Every subsequent Runner.run* call is# traced and governed without any further code change.set_trace_processors([    ExeclaveTracingProcessor(exe, agent_id="support-bot"),]) agent = Agent(name="support", instructions="Answer the user question.")result = Runner.run_sync(agent, "Summarize our Q3 pipeline")
§ 05

Span mapping

Every Agents-SDK span type maps to a corresponding Execlave span kind so the dashboard shows the full run tree under one trace id.

Agents SDK spanExeclave span kindNotes
AgentSpanDataagentAgent-level planning step.
GenerationSpanData / ResponseSpanDatallmModel name, input, output, and token usage.
FunctionSpanDatatoolTool calls — enforcement runs before the span opens so a block short-circuits the run.
HandoffSpanDatahandoffAgent-to-agent handoffs preserve parent relationships.
GuardrailSpanDataguardrailAgents-SDK guardrails are recorded alongside Execlave policy spans.
§ 06

Tool enforcement

Tool-allowlist and input-matching policies run the moment the SDK emits a FunctionSpanData — before the tool is invoked. A blocked tool aborts the SDK run with PolicyBlockedError; the span tree up to that point still ships to the dashboard.

Catching a block

from execlave.errors import PolicyBlockedError try:    Runner.run_sync(agent, user_input)except PolicyBlockedError as exc:    # A block-mode policy matched a tool call; the SDK run aborts    # BEFORE the tool was executed. exc.violations holds the matches.    return {"error": "blocked", "violations": exc.violations}
§ 07

Operational guarantees

The processor is designed to fail soft on non-enforcement errors; enforcement exceptions always propagate so blocks are never silently ignored.

Guarantees

  • on_span_start and on_span_end swallow unexpected exceptions and log them — they never crash the SDK run.
  • Enforcement exceptions (PolicyBlockedError, PolicyDeniedError, AgentPausedError, ApprovalTimeoutError, EnforcementUnavailableError) re-raise unchanged so block-mode policies halt the run as expected.
  • shutdown() and force_flush() delegate to Execlave.flush() so no spans are dropped on process exit.
  • Mapping is keyed on type(span_data).__name__ so patch releases of openai-agents do not require an Execlave SDK bump.
§ 08

What's next