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

Live

Google ADK

Google’s Agent Development Kit (ADK) reaches the Agent Fabric LLM proxy in one of two ways, depending on the proxy’s ingress Format:

  • model() — ADK’s LiteLlm model wrapper, for a Format=OpenAI proxy (the default). The adapter translates the governed connection into LiteLLM’s own model-string and kwarg conventions for you.
  • gemini() — ADK’s native Gemini model, for a Format=Gemini proxy. The SDK’s shared HTTP client is injected, so every governed feature works: per-run correlation, spans, usage and donkey.last_call. See Native Gemini.

What you get

  • A native google.adk.models.lite_llm.LiteLlm or google.adk.models.Gemini, with the proxy auth and attribution headers set.
  • For model(): the openai/ model prefix and LiteLLM kwarg names handled automatically. Supported at connection_kwargs(). LiteLLM gets a pre-built OpenAI client that sends through the SDK’s shared HTTP client, so per-run correlation, retries, spans, donkey.last_call and the jwt-mode JWT apply (see Notes). Inside donkey.run() or @donkey.governed, a refusal reaches your code as its typed Donkey error, such as PIIDetected.
  • For gemini(): the shared client injected through HttpOptions.httpx_async_client, round-trip verified live against a Format=Gemini proxy.

Install

pip install "donkey-kit[adk]"

Quickstart

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

llm is a real google.adk.models.lite_llm.LiteLlm instance (a subclass that carries donkey.last_call to your callbacks; see Native Gemini). The model string is prefixed with openai/ before it reaches LiteLLM (openai/gpt-4o), which is the prefix LiteLLM’s OpenAI-compatible route expects — you don’t add it yourself.

Three ways to construct

1. Off a shared Donkey instance:

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

2. Module-level factory (shortest):

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

3. Governed kwargs, native constructor:

from donkey_kit import Donkey from google.adk.models.lite_llm import LiteLlm async with Donkey.from_env() as donkey: llm = LiteLlm(model="openai/gpt-4o", **donkey.adk.connection_kwargs())

To read donkey.last_call in an after_model_callback on google-adk 2.13 and later, build it from last_call_bridged(LiteLlm) instead (see Native Gemini):

from donkey_kit.integrations.adk import last_call_bridged llm = last_call_bridged(LiteLlm)(model="openai/gpt-4o", **donkey.adk.connection_kwargs())

Manual equivalent

from google.adk.models.lite_llm import LiteLlm llm = LiteLlm( model="openai/gpt-4o", api_base=..., # from DONKEY_LLM_PROXY_URL, no /v1 suffix api_key=..., extra_headers=..., # client_id / client_secret header pair client=..., # an AsyncOpenAI on the SDK's shared client max_retries=0, # the SDK retries in its own transport layer )

LiteLLM uses api_base and extra_headers, not base_url / default_headers — connection_kwargs() already translates for you. client is present when the openai package is installed; LiteLLM’s OpenAI route uses it in place of the client it would build. max_retries=0 has to be passed to LiteLLM itself: LiteLLM sets the client’s retry count on every call, and its default is 2. An api_base / base_url passed to model() must pass the https:// rule, and the adapter builds client on that URL.

model() also sets ADK’s llm_client to a LiteLLMClient subclass, which is what lets a refusal arrive typed (see Notes). connection_kwargs() leaves it out, so a LiteLlm you build yourself raises LiteLLM’s own errors for a refusal. An llm_client you pass to model() replaces the SDK’s.

Native Gemini

A proxy provisioned with Format = Gemini exposes the native Gemini API at POST /<base-path>/models/<model>:generateContent (and :streamGenerateContent). ADK’s own Gemini model speaks that API, so gemini() returns a native google.adk.models.Gemini bound to the proxy, with the SDK’s shared HTTP client injected.

The three forms mirror model(). Pass the bare Gemini model id — there is no prefix, because the URL path carries the model:

from donkey_kit import Donkey from google.adk.models import Gemini async with Donkey.from_env() as donkey: # 1. Off a shared Donkey instance llm = donkey.adk.gemini("gemini-3.8-flash") # 3. Governed kwargs, native constructor llm = Gemini(model="gemini-3.8-flash", **donkey.adk.gemini_connection_kwargs())
# 2. Module-level factory from donkey_kit.integrations.adk import gemini llm = gemini("gemini-3.8-flash")

Pointing at the Gemini proxy. DONKEY_LLM_PROXY_URL usually names a Format=OpenAI proxy. If your Gemini proxy is a different one, pass its URL as base_url; the client_id/client_secret pair must be contracted on that proxy, and the URL must pass the https:// rule:

llm = donkey.adk.gemini("gemini-3.8-flash", base_url="https://…/ddk-gemini-inbound/")

Any other keyword is passed to ADK’s Gemini and overrides the governed default — for example retry_options, or your own client_kwargs.

Manual equivalent. This is what gemini_connection_kwargs() returns:

from google.adk.models import Gemini llm = Gemini( model="gemini-3.8-flash", base_url=..., # the Format=Gemini proxy URL client_kwargs={ "api_key": ..., # a placeholder; google-genai requires one "http_options": { "base_url": ..., # same URL "api_version": "", # the proxy path has no /v1beta segment "headers": ..., # client_id / client_secret header pair "timeout": ..., # milliseconds "httpx_async_client": ..., # the SDK's shared client }, }, )

All five http_options keys are passed together, because ADK builds its client from client_kwargs. The base_url, api_version and headers you set are kept, and ADK adds its own x-goog-api-client and user-agent tracking values to the headers. google-genai requires an API key and always sends it as x-goog-api-key; the gateway authenticates on the client_id/client_secret pair and ignores it.

donkey.last_call. Usage (input_tokens, output_tokens, total_tokens, cached_tokens, reasoning_tokens) is read from Gemini’s usageMetadata, and requested_model from the URL path. Gemini’s total_tokens includes the thinking tokens it also reports as reasoning_tokens. On model-based-routing 1.0.5 a Format=Gemini proxy sends the routing headers, so served_provider (gemini), served_model and routing_type are filled. Every model in the path is served by gemini, so a path model the proxy resolves to another model sets substituted to True. Older versions pass the request through with no routing headers: served_provider, served_model and routing_type stay None, and substituted is False. request_id and api_instance_id are populated on both.

last_call is contextvar-scoped, and ADK’s Runner makes the model call in a task of its own, so the caller of runner.run_async(...) reads UNOBSERVED. Read it in an after_model_callback. Both gemini() and model() return a subclass of the ADK class that carries the record from the model call to the callback, including on google-adk 2.13 and later, which runs the model call in a copy of the agent’s context. For a model you build yourself, last_call_bridged(...) returns that subclass of any ADK model class, your own subclass included:

from google.adk.agents import LlmAgent def record_usage(callback_context, llm_response): r = donkey.last_call print(r.requested_model, r.input_tokens, r.output_tokens) return None # keep the model's response agent = LlmAgent( name="assistant", model=donkey.adk.gemini("gemini-3.8-flash"), after_model_callback=record_usage, )

When streaming, the callback runs once per partial response and once more for the complete response. The token counts land when the stream ends, so only the complete response’s callback reads them. In the partial callbacks they are None.

Errors. google-genai raises its own google.genai.errors.APIError (ClientError for a 4xx) and the SDK does not wrap it. The error’s .response is the proxy’s HTTP response, so classify() gives you the typed Donkey error:

from donkey_kit.core.errors import classify from google.genai import errors as genai_errors try: async for event in runner.run_async(...): ... except genai_errors.APIError as exc: err = classify(exc.response) # e.g. AuthError on 401, UpstreamRequestError on 404

Reusing a model across asyncio.run(...) calls works. The shared HTTP client keeps one connection pool per event loop, so a sync app that wraps each run in asyncio.run(...) can build the Donkey (or call the module-level gemini()) once and reuse it.

Notes

  • Both factories send through the SDK’s shared HTTP client, so the correlation ID bound by donkey.run() reaches every request.
  • donkey.last_call is set in the context that made the call. ADK’s Runner calls the model in a task of its own, so read it in an after_model_callback (see Native Gemini). The factories’ models carry the record to that callback. A LiteLlm or Gemini you build from connection_kwargs() or gemini_connection_kwargs() carries it only when its class is last_call_bridged(LiteLlm) or last_call_bridged(Gemini). Built from the plain class, its callback reads UNOBSERVED on google-adk 2.13 and later. A cold read on a Donkey that resolved only ADK reports UNOBSERVED, and OBSERVED after a call, for model() as well as gemini().
  • Refusals on the model() path are typed inside donkey.run() and @donkey.governed. LiteLLM re-raises a gateway refusal as its own error, such as litellm.exceptions.APIError, without the gateway’s response headers. The llm_client that model() sets marks that error with the refusal the SDK’s transport received for the same call, and the typed-refusal bridge raises PIIDetected, ModelSubstituted or GatewayUnavailable in its place, with LiteLLM’s error on framework_error. Outside those scopes, and without typed_refusals(), you get LiteLLM’s error unchanged; see the ADK examples.
  • Approval-gated tools pause the run. Add approval_plugin() from donkey_kit.integrations.adk to the App’s plugins, and a @donkey.tool(approval="required") call pauses with ADK’s own tool confirmation. pending_approvals(events) returns each paused call as an Approval; resume the run on a user message whose parts are approve(...).native or reject(...).native, the types.Part each helper returns on the Approval. DDK’s requester evidence remains in process memory, not the session events: missing evidence on native resume raises AuthError without running the tool, and changed arguments raise ConfigError. Request a fresh approval after losing that state. See Human-in-the-loop.
  • The plugin’s injected ToolContext is execution-only. It is excluded from approval review and snapshots, and execution must receive that exact framework-supplied object. Reviewed arguments and defaults still require acyclic exact built-in data; this is not an exemption for custom user values.
  • gemini() needs the adk extra’s minimum google-adk (see Version compatibility), the first release whose Gemini accepts client_kwargs. On an older ADK, Gemini drops the governed client without an error and talks to Google directly, so gemini() raises NotImplementedError instead of returning a model that bypasses the gateway.
  • The adk extra’s litellm requirement is a floor, not a ceiling (see Version compatibility) — pin your own upper bound if you need one.
  • The adk extra installs litellm[mcp], not plain litellm. From litellm 1.106, any request that carries tools imports the mcp package, which plain litellm does not install, so an agent with tools fails with “No module named ‘mcp’”. If you install litellm yourself rather than through the extra, install litellm[mcp].

See the error taxonomy for how proxy rejections surface through ADK’s LiteLlm model, and Native Gemini for gemini().

Last updated on