Live
Strands Agents
Strands Agents gets a governed OpenAIModel pointed at the Agent Fabric LLM
proxy. The connection details travel in Strands’ client_args, which Strands
passes straight through to its underlying OpenAI client.
What you get
- A native
strands.models.openai.OpenAIModel. - Full header and transport injection through
client_args— per-run correlation IDs anddonkey.last_callwork, as with LangGraph. - Supported at
connection_kwargs().
Install
pip install "donkey-kit[strands]"Quickstart
Python
from donkey_kit.integrations.strands import model
llm = model("gpt-4o")llm is a real strands.models.openai.OpenAIModel instance — pass it to your
Agent as you would any other Strands 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.strands.model("gpt-4o")2. Module-level factory (shortest):
from donkey_kit.integrations.strands import model
llm = model("gpt-4o")3. Governed kwargs, native constructor:
from donkey_kit import Donkey
from strands.models.openai import OpenAIModel
async with Donkey.from_env() as donkey:
llm = OpenAIModel(model_id="gpt-4o", **donkey.strands.connection_kwargs())Manual equivalent
from strands.models.openai import OpenAIModel
llm = OpenAIModel(
model_id="gpt-4o",
client_args={
"base_url": ..., # from DONKEY_LLM_PROXY_URL, no /v1 suffix
"api_key": ...,
"default_headers": ..., # client_id / client_secret header pair
"http_client": ..., # sends through the SDK's shared client; closing it is a no-op
"max_retries": 0, # the SDK retries in its own transport layer
},
stream=False, # see Notes
)Everything the SDK injects lives inside the single client_args dict that
Strands forwards to its internal OpenAI client.
Notes
-
A budget refusal is sent once. A Strands
Agentretries a throttled model call by default (up to 6 attempts), and Strands treats every429as throttling. On the proxy a429is a budget refusal, so the modeldonkey.strands.model()builds raises it as the typedTokenBudgetExceededinstead. The same holds forRequestRateLimitExceeded, the429of the requestrate-limitingpolicy. The agent’s retry strategy doesn’t retry that error, and it reaches your code as it is, after one request:from strands import Agent from donkey_kit import TokenBudgetExceeded agent = Agent(model=donkey.strands.model("gpt-4o")) try: await agent.invoke_async("hello") except TokenBudgetExceeded as err: print(err.retry_after)The model itself has
max_retries=0, so the OpenAI client under it doesn’t retry either, and the SDK’s transport handles the transient5xx. AnOpenAIModelyou build yourself fromconnection_kwargs()doesn’t get this: build its agent withAgent(model=..., retry_strategy=None). -
Approval-gated tools pause the agent. Add
ApprovalHook()fromdonkey_kit.integrations.strandsto the agent’shooks, and a@donkey.tool(approval="required")call stops the agent with Strands’ own interrupt.pending_approvals(result)returns each paused call as anApproval; resume the agent onapprove(...).nativeorreject(...).native, the interrupt response each helper returns on theApproval. Missing in-process requester evidence on native resume raisesAuthErrorwithout running the tool; changed arguments raiseConfigError. Request a fresh approval after a restart, another process or eviction. See Human-in-the-loop. -
Refusals inside tools stop the agent. Strands sends a tool’s exception to the model as an error tool result, a governed refusal included. Add
GovernedToolHook()fromdonkey_kit.integrations.strandsto the agent’shooks, and a governed refusal inside a tool leaves the tool loop before a retry or another model turn. You add the hook yourself: the model and the MCP clients the SDK builds can’t reach theAgent. AnApprovalHookis aGovernedToolHook, so an agent withApprovalHook()needs no other hook, and the refusal stops the agent in an approved tool as in an ungated one.from strands import Agent from donkey_kit.integrations.strands import GovernedToolHook agent = Agent( model=donkey.strands.model("gpt-4o"), tools=[lookup_order], hooks=[GovernedToolHook()], )Use
donkey.run()or@donkey.governedaround the invocation to recover the typed error from Strands’ event-loop wrapper. Ordinary tool errors still go to the model as error tool results. WithGovernedToolHook()alone, a@donkey.tool(approval="required")call raises itsApprovalRequiredto your code instead of pausing: addApprovalHook()for the pause. -
Strands forwards
client_argsverbatim to the underlying OpenAI client, so both header injection (default_headers) and transport injection (http_client) are available. -
The client stays open. Strands opens and closes an OpenAI client for every request (
async with AsyncOpenAI(**client_args)). Closing thehttp_clientit gets is a no-op, so the SDK’s shared client survives every call. Onopenai3.x that client is anhttpx2bridge onto the shared client, and on earlier releases a view of it. Onlydonkey.aclose()ends the connection pool. -
Streaming is off by default. The governed model sets
stream=False. A proxy routing to a Gemini upstream answers a streamed request with one wholechat.completionand no chunk deltas, and Strands fails on it. Passdonkey.strands.model("gpt-4o", stream=True)on routes that stream.
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.