§ 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.
Voraussetzungen
- Execlave-Konto mit aktivem API-Schlüssel — Einstellungen → API-Schlüssel.
- Ein registrierter Agent in Execlave. Verwenden Sie die lowercase-kebab
agent_iddes Agents beim Erstellen des Prozessors. - Python
>=3.10undopenai-agents >=0.0.1. - JavaScript wird für das Agents SDK noch nicht unterstützt — verwenden Sie für JS-Workloads den LangChain-Handler.
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]'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.
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-referenceSchnellstart
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")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-Span | Execlave-Span-Art | Hinweise |
|---|---|---|
AgentSpanData | agent | Planungsschritt auf Agent-Ebene. |
GenerationSpanData / ResponseSpanData | llm | Modellname, Input, Output und Token-Verbrauch. |
FunctionSpanData | tool | Tool-Aufrufe — die Durchsetzung läuft, bevor der Span geöffnet wird, sodass eine Blockierung den Run sofort beendet. |
HandoffSpanData | handoff | Agent-zu-Agent-Übergaben behalten die übergeordneten Beziehungen bei. |
GuardrailSpanData | guardrail | Agents-SDK-Guardrails werden zusammen mit den Execlave-Policy-Spans erfasst. |
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}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_startundon_span_endfangen 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()undforce_flush()delegieren anExeclave.flush(), sodass beim Prozessende keine Spans verloren gehen.- Die Zuordnung erfolgt anhand von
type(span_data).__name__, sodass Patch-Releases vonopenai-agentskein Update des Execlave SDK erfordern.