Skip to Content
These docs describe donkey-kit v0.2.1. Release notes
FrameworksOpenAI Agents SDK

Live

OpenAI Agents SDK

The OpenAI Agents SDK (pip package openai-agents) gets a governed OpenAIChatCompletionsModel backed by a pre-built AsyncOpenAI client. The adapter builds that client itself, with the SDK’s shared HTTP client and proxy headers, and hands it to the Agents SDK ready-made. It is a deep adapter (BG §1.8, promoted by Phase 1 demand in #223): like LangGraph, it runs the full conformance suite in CI.

What you get

  • A native agents.OpenAIChatCompletionsModel.
  • Full header and transport injection — both travel together in one AsyncOpenAI object.
  • Per-run correlation IDs that reach the agent’s dynamic instructions, its function_tools, and every model request.
  • Typed gateway refusals (PIIDetected, TokenBudgetExceeded, …) out of Runner.run, inside typed_refusals().
  • A conformance suite you can run against your own agent.

Turn off the Agents SDK’s own tracing. The Agents SDK traces every run by default. Its default exporter posts those traces, including each model call’s input and output, to OpenAI’s trace ingest endpoint (https://api.openai.com/v1/traces/ingest) whenever an OpenAI API key is available, for example OPENAI_API_KEY in the environment. That export does not go through the gateway, so the gateway’s PII and content policies never see it. DDK leaves the setting alone, because flipping it would be a hidden process-wide change. Turn it off yourself with any one of these:

  • agents.set_tracing_disabled(True), once at startup, for the whole process;
  • Runner.run(agent, input, run_config=RunConfig(tracing_disabled=True)), per run;
  • OPENAI_AGENTS_DISABLE_TRACING=1 in the environment.

DDK’s own OpenTelemetry spans still cover every governed model call, and they leave message content off by default.

Install

pip install "donkey-kit[openai-agents]"

Quickstart

from donkey_kit.integrations.openai_agents import model llm = model("gpt-4o")

llm is a real agents.OpenAIChatCompletionsModel instance — pass it to Agent(model=...) as you would any other Agents SDK model.

Three ways to construct

1. Off a shared Donkey instance:

from donkey_kit import Donkey async with Donkey.from_env() as donkey: llm = donkey.openai_agents.model("gpt-4o")

2. Module-level factory (shortest):

from donkey_kit.integrations.openai_agents import model llm = model("gpt-4o")

3. Governed kwargs, native constructor:

from donkey_kit import Donkey from agents import OpenAIChatCompletionsModel async with Donkey.from_env() as donkey: llm = OpenAIChatCompletionsModel( model="gpt-4o", **donkey.openai_agents.connection_kwargs(), )

Manual equivalent

from openai import AsyncOpenAI from agents import OpenAIChatCompletionsModel async_client = AsyncOpenAI( base_url=..., # from DONKEY_LLM_PROXY_URL, no /v1 suffix api_key=..., default_headers=..., # client_id / client_secret header pair http_client=..., # the shared client (an httpx2 bridge on openai 3.x) ) llm = OpenAIChatCompletionsModel( model="gpt-4o", openai_client=async_client, )

connection_kwargs() returns exactly one key, openai_client, holding this pre-built AsyncOpenAI instance.

donkey.last_call

Every model call goes through the SDK’s shared HTTP client, so the SDK records it. last_call is contextvar-scoped, though, and Runner sends a run’s first turn from a task of its own (run_streamed sends every turn that way). After a one-turn Runner.run, or any run_streamed, the caller reads UNOBSERVED. After a longer Runner.run it reads the last turn’s call. To read every call, use RunHooks.on_llm_end, which runs in the same task as the call:

from agents import Agent, RunHooks, Runner class LastCallHooks(RunHooks): async def on_llm_end(self, context, agent, response): r = donkey.last_call print(r.request_id, r.input_tokens, r.output_tokens) agent = Agent(name="assistant", model=donkey.openai_agents.model("gpt-4o")) await Runner.run(agent, "hello", hooks=LastCallHooks())

Run the conformance suite against your own agent

The suite that tests this adapter is also a pytest plugin you can point at your own agent:

pytest --donkey-conformance --donkey-agent=my_app:build

build returns an object with an awaitable run(text). The suite checks that it doesn’t retry a budget refusal, surfaces PIIDetected typed, carries the correlation ID into its logs, and tolerates a response with no budget headers. The examples/openai_agents factory has exactly this shape: it wraps Runner.run in typed_refusals(). Support triage with the OpenAI Agents SDK walks through it end to end. See Testing.

The SDK’s internal conformance matrix records no exemption for the Agents SDK, approval round trip included. An @donkey.tool(approval="required") wrapped with donkey_kit.integrations.openai_agents.function_tool sets the Agents SDK’s own needs_approval, so Runner.run pauses with the call in result.interruptions. pending_approvals inspects the calls; approve and reject record the decision on the RunState, and Runner.run(agent, state) resumes (#213). Each helper returns an Approval; approve and reject return it with the RunState on native. See Human approval.

A serialised RunState does not preserve DDK’s in-process requester evidence. DDK registers that evidence in the initial needs_approval callback, under the scope running the agent. pending_approvals() only inspects pauses: repeated inspection preserves retained evidence without another pending event, and inspection of restored state never reconstructs missing evidence. With retained evidence, inspection and decisions keep the initial pause’s correlation ID and timestamp, even outside the scope that paused the run. Approval arguments are the Agents SDK’s validated Python values, including defaults and nested built-in containers. For example, JSON 1 becomes 1.0 for a float parameter before review; the resumed call must match that validated snapshot exactly. Custom objects, including Pydantic models, are refused before the pause. Use built-in data annotations for approval-gated tools. After a restart, another process or eviction, a native resume raises AuthError without running the gated tool. Request a fresh approval in the requester’s context; changed approval arguments raise ConfigError.

Notes

  • A pre-built client is the preferred integration point. When a framework accepts a ready-made AsyncOpenAI instead of loose kwargs, the shared transport and every proxy header travel together as one object, with no risk of a kwarg being dropped. That’s why injection is full here even though the model object never sees base_url or default_headers directly.
  • openai-agents is distinct from the plain openai package: agents.OpenAIChatCompletionsModel lives in the Agents SDK. Installing donkey-kit[openai-agents] pulls it in for you. For the raw governed client with no framework, use donkey.openai() (from donkey-kit[llm]) instead.

See the error taxonomy for how proxy rejections surface as typed exceptions, and the verification ledger  for the current status of every constructor signature this adapter depends on.

Last updated on