Skip to Content
These docs describe donkey-kit v0.2.1. Release notes
FrameworksStrands

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 and donkey.last_call work, as with LangGraph.
  • Supported at connection_kwargs().

Install

pip install "donkey-kit[strands]"

Quickstart

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 Agent retries a throttled model call by default (up to 6 attempts), and Strands treats every 429 as throttling. On the proxy a 429 is a budget refusal, so the model donkey.strands.model() builds raises it as the typed TokenBudgetExceeded instead. The same holds for RequestRateLimitExceeded, the 429 of the request rate-limiting policy. 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 transient 5xx. An OpenAIModel you build yourself from connection_kwargs() doesn’t get this: build its agent with Agent(model=..., retry_strategy=None).

  • Approval-gated tools pause the agent. Add ApprovalHook() from donkey_kit.integrations.strands to the agent’s hooks, and a @donkey.tool(approval="required") call stops the agent with Strands’ own interrupt. pending_approvals(result) returns each paused call as an Approval; resume the agent on approve(...).native or reject(...).native, the interrupt response each helper returns on the Approval. Missing in-process requester evidence on native resume raises AuthError without running the tool; changed arguments raise ConfigError. 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() from donkey_kit.integrations.strands to the agent’s hooks, 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 the Agent. An ApprovalHook is a GovernedToolHook, so an agent with ApprovalHook() 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.governed around the invocation to recover the typed error from Strands’ event-loop wrapper. Ordinary tool errors still go to the model as error tool results. With GovernedToolHook() alone, a @donkey.tool(approval="required") call raises its ApprovalRequired to your code instead of pausing: add ApprovalHook() for the pause.

  • Strands forwards client_args verbatim 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 the http_client it gets is a no-op, so the SDK’s shared client survives every call. On openai 3.x that client is an httpx2 bridge onto the shared client, and on earlier releases a view of it. Only donkey.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 whole chat.completion and no chunk deltas, and Strands fails on it. Pass donkey.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.

Last updated on