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
AsyncOpenAIobject. - Per-run correlation IDs that reach the agent’s dynamic instructions, its
function_tools, and every model request. - Typed gateway refusals (
PIIDetected,TokenBudgetExceeded, …) out ofRunner.run, insidetyped_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=1in 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
Python
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:buildbuild 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
AsyncOpenAIinstead 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 seesbase_urlordefault_headersdirectly. openai-agentsis distinct from the plainopenaipackage:agents.OpenAIChatCompletionsModellives in the Agents SDK. Installingdonkey-kit[openai-agents]pulls it in for you. For the raw governed client with no framework, usedonkey.openai()(fromdonkey-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.