Skip to content
Zurück zur Startseite

§ INTEGRATION · OPENAI AGENTS SDK

OpenAI Agents SDK Tracing-Prozessor

Installieren Sie das optionale Extra, registrieren Sie den Prozessor einmal, und jeder Agent-, Generation-, Tool-, Handoff- und Guardrail-Span wird gesteuert und nachverfolgt — keine Decorators, keine Wrapper.

§ 01

Voraussetzungen

  • Execlave-Konto mit aktivem API-Schlüssel — Einstellungen → API-Schlüssel.
  • Ein registrierter Agent in Execlave. Verwenden Sie die lowercase-kebab agent_id des Agents beim Erstellen des Prozessors.
  • Python >=3.10 und openai-agents >=0.0.1.
  • JavaScript wird für das Agents SDK noch nicht unterstützt — verwenden Sie für JS-Workloads den LangChain-Handler.
§ 02

Installation

Der Prozessor ist über ein Python-Extra verfügbar, sodass die Standardinstallation des SDK openai-agents nicht als transitive Abhängigkeit mitzieht.

Python

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

Sofort-Einrichtung mit einem Copilot

Fügen Sie diesen Prompt in Ihren KI-Coding-Assistenten ein. Er registriert den Tracing-Prozessor beim Start, ohne Agent-, Tool- oder Guardrail-Definitionen zu verändern.

§ 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

Schnellstart

Registrieren Sie einen ExeclaveTracingProcessor beim Start. Jeder nachfolgende Runner.run- / Runner.run_sync-Aufruf wird nachverfolgt und gesteuert.

Python

from agents import Agent, Runner, set_trace_processorsfrom execlave import Execlavefrom execlave.integrations.openai_agents import ExeclaveTracingProcessor exe = Execlave(api_key="exe_prod_...") # 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-Zuordnung

Jeder Agents-SDK-Span-Typ wird einer entsprechenden Execlave-Span-Art zugeordnet, sodass das Dashboard den vollständigen Run-Baum unter einer Trace-ID anzeigt.

Agents-SDK-SpanExeclave-Span-ArtHinweise
AgentSpanDataagentPlanungsschritt auf Agent-Ebene.
GenerationSpanData / ResponseSpanDatallmModellname, Input, Output und Token-Verbrauch.
FunctionSpanDatatoolTool-Aufrufe — die Durchsetzung läuft, bevor der Span geöffnet wird, sodass eine Blockierung den Run sofort beendet.
HandoffSpanDatahandoffAgent-zu-Agent-Übergaben behalten die übergeordneten Beziehungen bei.
GuardrailSpanDataguardrailAgents-SDK-Guardrails werden zusammen mit den Execlave-Policy-Spans erfasst.
§ 06

Tool-Durchsetzung

Tool-Allowlist- und Input-Matching-Richtlinien laufen in dem Moment, in dem das SDK eine FunctionSpanData ausgibt — bevor das Tool aufgerufen wird. Ein blockiertes Tool beendet den SDK-Run mit PolicyBlockedError; der Span-Baum bis zu diesem Punkt wird trotzdem an das Dashboard übermittelt.

Eine Blockierung abfangen

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

Betriebsgarantien

Der Prozessor ist darauf ausgelegt, bei Nicht-Durchsetzungsfehlern fehlertolerant zu bleiben; Durchsetzungsausnahmen werden immer weitergegeben, sodass Blockierungen nie stillschweigend ignoriert werden.

Garantien

  • on_span_start und on_span_end fangen unerwartete Ausnahmen ab und protokollieren sie — sie lassen den SDK-Run niemals abstürzen.
  • Durchsetzungsausnahmen (PolicyBlockedError, PolicyDeniedError, AgentPausedError, ApprovalTimeoutError, EnforcementUnavailableError) werden unverändert erneut ausgelöst, sodass Block-Modus-Richtlinien den Run wie erwartet anhalten.
  • shutdown() und force_flush() delegieren an Execlave.flush(), sodass beim Prozessende keine Spans verloren gehen.
  • Die Zuordnung erfolgt anhand von type(span_data).__name__, sodass Patch-Releases von openai-agents kein Update des Execlave SDK erfordern.
§ 08

Wie geht es weiter?

OpenAI Agents SDK Integration — Execlave Docs