Skip to Content
These docs describe donkey-kit v0.2.1. Release notes
CLI & decorators

Live

CLI & decorators

Two on-ramps to the SDK: decorators that govern a function in one line, and a CLI for setup, diagnosis, local simulation, conformance testing, and scanning, publishing, verifying and exposing your agents and tools.

Decorators

@donkey.governed

Runs a function inside a donkey.run() scope:

@donkey.governed(team="support") async def handle_ticket(ticket): ...

One decorator gives the function a run/correlation ID, cost tags, an OTel span, and typed refusals — the four things you would otherwise set up per call site.

  • Wraps both sync and async callables.
  • Works bare (@donkey.governed) or parametrised (@donkey.governed(team=…, project=…, env=…, enduser_id=…)).
  • Takes no id=: each call opens its own run, so unrelated calls are never collapsed into one correlation. When you need a specific id, use donkey.run(id=…) directly.

@donkey.tool

@donkey.tool async def lookup_crm(customer_id: str) -> dict: """Look up a customer record by id.""" ...

Marks a function as a governed tool without changing how it’s called. It returns the same function with a __donkey_tool__ marker and records a ToolSpec (name, qualname, signature, docstring, is_async) in a process-global registry you read with registered_tools(). Both ToolSpec and registered_tools are exported from donkey_kit.

A tool with no docstring is rejected at decoration time (ValueError) — an undescribed tool is useless to a model and to a registry.

@donkey.tool(approval="required", risk="financial") gates the tool behind a human decision: a call raises ApprovalRequired instead of running, and donkey.approvals.resolve(...) runs it once someone approves. The approval is client-side and advisory. See Human-in-the-loop.

@donkey.tool(server="sku-manager") attributes the tool to the MCP server it belongs to, by that server’s service ID: lowercase kebab-case, recorded as ToolSpec.server. The ID is permanent once a service is registered, so it is always set by you and never inferred from a module path or function name. A tool without server= is reported as unattributed, not guessed. Anything else raises ValueError at decoration time.

@donkey.agent

@donkey.agent(name="support-triage", skills=["triage", "draft-reply"]) async def handle(task): """Triage a support ticket and draft a reply for a human to send.""" ...

Marks an agent entry point, again without changing how it’s called. It returns the same function with a __donkey_agent__ marker and records an AgentSpec (name, qualname, docstring, skills, is_async) that you read with registered_agents(); both are exported from donkey_kit. name is the agent’s service ID, with the same kebab-case rule as server=. The docstring is required, because it is the agent’s description. A blank or repeated skill raises ValueError.

donkey scan reads the @donkey.tool and @donkey.agent markers, and donkey.serve() generates its A2A agent card from the same @donkey.agent record, so the scan and the card can’t drift.

The CLI

pip install "donkey-kit[cli]"
donkey init # writes a commented .donkey-kit.toml, names every missing env var at once donkey doctor # checks creds, reaches the gateway, reports budget state donkey mock # the local simulator — --scenario scripts failures donkey dev my:agent # serves an @donkey.agent behind a simulated A2A ingress donkey test # a thin front end to pytest --donkey-conformance donkey scan # finds your agents, tools and MCP servers, without running your code donkey publish # registers them in Exchange; --dry-run prints the plan and sends nothing donkey verify # checks published MCP servers and agents against their live side; reads only donkey preflight # checks, read-only, that a service can be put behind its gateway donkey expose # puts one MCP server or A2A agent behind an existing gateway

Global flags

Four global flags precede the subcommand:

donkey --version # print the donkey-kit version and exit donkey --config ./cfg.toml init # write the generated config file to a non-default path donkey --config ./cfg.toml doctor # diagnose against this project config file donkey --env Sandbox init # write this Anypoint environment into the generated file donkey --json init # machine-readable output where a command supports it

--config selects the file init writes or the project file doctor reads; doctor still applies the normal per-field precedence: explicit kwargs (when calling the config loader in code), environment variables, the named file’s local overlay, the named file, user config, then defaults. --env applies to init only; set ANYPOINT_ENV for doctor. Other commands reject these flags with exit 2 rather than silently ignore them.

--version prints the version alone, such as 0.2.0, and exits 0 without running a command. It prints the same plain line with --json, since it is not one of the JSON documents. The card version of donkey dev is its own flag, --agent-version.

Exit codes

Every command exits non-zero on failure, so any of them drops into CI as a preflight. A command that needs an optional extra (donkey mock → [local], donkey test → [test], donkey doctor → [llm]) prints the exact pip install line and exits 1 — never a stack trace. The one command still blocked, the hidden donkey status, exits 3 with blocked on verification, so a script can tell “blocked” from “failed”.

The CLI lives in the donkey_kit.cli package. Earlier releases also shipped hidden provisioning commands (validate, plan, apply, drift, lint, generate); they were removed with the refused provisioning control plane, and typer now rejects them as unknown commands (exit 2).

JSON output

Each document that scan, publish, verify, preflight and expose print with --json carries its own format key. A script reads the key before it reads the rest. The number goes up only when the shape changes in a way that breaks an existing reader:

CommandFormat keyWhat it prints
donkey scanscan_format: 1The scan model.
donkey publish --dry-runplan_format: 1The plan: the assets a publish would register, and the issues.
donkey publishpublish_format: 1The plan’s assets, each with a status and a detail, and the issues.
donkey verifyverify_format: 1The plan’s assets, each with a status, a detail and its differences, and the issues.
donkey preflight, donkey exposeexpose_format: 1ok, dry_run, the url, one entry per step, and the issues.

A declaration issue still prints the document, so stdout is JSON whenever the command got as far as reading the declaration. Nothing is sent then. A publish or verify reports every asset not_attempted, an expose report has ok: false and no steps, and every document lists the issues. The issues also go to stderr, and the command exits 1. A missing path or invalid config exits 2 with no document.

Command reference

Generated from the CLI itself; donkey <command> --help prints the same.

Global options go before the command (donkey --json init):

OptionDefaultMeaning
--versionoffPrint the donkey-kit version and exit.
--confignoneWhere init writes .donkey-kit.toml, or the project config file doctor reads.
--envnoneAnypoint environment init writes (e.g. Sandbox). init only.
--jsonoffEmit machine-readable JSON where the command supports it.

donkey dev: Serve an agent over A2A behind a simulated gateway ingress.

OptionDefaultMeaning
targetnoneThe @donkey.agent handler, as module:attribute.
--port8000TCP port to bind.
--host127.0.0.1Host/interface to bind.
--agent-version0.0.0The agent version the card advertises.
--protocol-version1.0A2A protocol to serve: 0.3.0 or 1.0 (default).
--scenariononeInbound rejection rule, repeatable. e.g. ‘pii_block:every=5’, ‘request_limit:limit=3,window=60s’, ‘injection:on-pattern=ignore previous’.

donkey doctor: Diagnose governed access: config, credentials, gateway, model, budget.

OptionDefaultMeaning
--modelgpt-4oModel id to test against the proxy allow-list.
--jsonoffEmit machine-readable JSON.

donkey expose: Expose one MCP server or A2A agent through an existing gateway.

OptionDefaultMeaning
path.The repository (or one .py file) to scan.
--servicenoneThe service ID to expose; optional when the project has exactly one.
--envnoneThe Anypoint environment (ANYPOINT_ENV).
--targetnoneThe gateway’s name; overrides the declared target.
--dry-runoffOnly read: print what would be created, and change nothing.
--jsonoffEmit the report as JSON.

donkey init: Bootstrap a commented .donkey-kit.toml from the resolved config.

OptionDefaultMeaning
--forceoffRegenerate even if the file already exists.

donkey mock: Run the local gateway simulator.

OptionDefaultMeaning
--port8080TCP port to bind.
--host127.0.0.1Host/interface to bind.
--scenariononeFault-injection rule, repeatable. e.g. ‘pii_block:every=5’, ‘budget:limit=20000,window=60s’, ‘request_limit:limit=3,window=60s’, ‘injection:on-pattern=ignore previous’, ‘ciba:pending=2,then=approve’.

donkey preflight: Check, read-only, that a service can be exposed.

OptionDefaultMeaning
path.The repository (or one .py file) to scan.
--servicenoneThe service ID to expose; optional when the project has exactly one.
--envnoneThe Anypoint environment (ANYPOINT_ENV).
--targetnoneThe gateway’s name; overrides the declared target.
--jsonoffEmit the report as JSON.

donkey publish: Publish code-first assets to Exchange.

OptionDefaultMeaning
path.The repository (or one .py file) to publish.
--dry-runoffPrint the assets and digests it would publish; no network call.
--if-changed / --alwaysonSkip an asset whose latest published version has the same digest.
--jsonoffEmit the plan, or what was published, as JSON.

donkey scan: Find @donkey.agent and @donkey.tool markers statically and report them.

OptionDefaultMeaning
path.The repository (or one .py file) to scan.
--jsonoffEmit the canonical scan model as JSON.

donkey test: Run the conformance suite against your agent.

OptionDefaultMeaning
--agentnoneImport path to your agent factory, e.g. my.pkg:make_agent.

donkey verify: Check published MCP servers and A2A agents against their live side, read-only.

OptionDefaultMeaning
path.The repository (or one .py file) to verify.
--jsonoffEmit the plan with each asset’s outcome as JSON.

donkey init

Resolves your current configuration (env vars → config files → defaults; see Precedence) and writes a commented .donkey-kit.toml with the values it found.

  • Names every missing required field at once — control plane and LLM proxy — using the same validation the SDK runs at call time, so init and a real request never disagree about what is required.
  • Never writes a secret. client_secret, llm_proxy_client_secret, and llm_proxy_key are emitted as commented pointers, not values. Put them in a gitignored .donkey-kit.local.toml next to the file, or in environment variables. A URL in .donkey-kit.toml, including a loopback one, only receives credentials from those two files unless you opt in; see Which credentials a URL receives. The file’s comments also say that URLs must use https://, that localhost is accepted over plain http://, and that DONKEY_ALLOW_HTTP=1 in the environment (not in the file) allows plain http:// to other hosts.
  • Idempotent. An existing file is left untouched unless you pass --force.
donkey init --force donkey --json init # {"path": "...", "written": true, "missing": [...]}

donkey doctor

A governed call can fail for several reasons that look identical from the outside. doctor makes one real governed call and tells them apart:

  • Wrong credentials — the client_id/client_secret pair is rejected.
  • Wrong URL — the gateway answers, but no proxy is deployed on that base path: an empty 404 with no x-llm-proxy-* headers. The gateway line fails and credentials and model show as not checked. A typo in the path, a trailing /v1 (the governed proxy has no /v1 segment), or a proxy that is not Active in API Manager all land here.
  • Credentials fine, model not in the allow-list — nothing is misconfigured; your platform team has not granted that model.
  • /responses not served on this route — the proxy accepted the credentials and routed the model, but the upstream answered the Responses API with 404. An Azure OpenAI route does this. doctor then tries /chat/completions once and reports the route as working if that answers. Call it with client.chat.completions.create(...) on donkey.llm.client(), or with your framework’s chat-completions client.

Each verdict prints the same remediation string the matching typed exception carries, so the fix is in the output rather than in a runbook. The budget line states how old the reading is, since the proxy has no budget endpoint.

Before the call, doctor prints each endpoint’s host and where it came from: env, project file, local overlay, user file or default. If the LLM proxy URL comes from the working directory’s config files but its credentials don’t (a loopback URL such as the simulator’s included), the config line fails with the remediation and no request is sent. A control-plane endpoint with the same problem shows its remediation on the control plane line without failing the report, since doctor only calls the LLM proxy. In jwt mode, an LLM proxy URL from those files always fails the config line, because the JWT never comes from a file: set the URL in the environment or opt in.

With DONKEY_ALLOW_HTTP on in the environment, a plain http line says so and quotes the value as set, for example DONKEY_ALLOW_HTTP=true (in --json output, the entry with "name": "plain http"):

[i] plain http allowed to non-loopback hosts (DONKEY_ALLOW_HTTP=1 in env)
donkey doctor donkey --config ./cfg.toml doctor # read cfg.toml and its adjacent local overlay
Expected output
[ok] config env (3 fields) [i] llm endpoint <ingress-gw> (env) [i] control plane anypoint.mulesoft.com (default) [ok] gateway reachable, responded [ok] credentials client_id accepted [ok] model accepted by the proxy [i] budget 99,000 / 100,000 remaining, resets in 59s, observed 0s ago

On an Azure OpenAI route, the responses line explains the 404 and the run still exits 0:

Expected output
[ok] gateway reachable, responded [ok] credentials client_id accepted [ok] model accepted by the proxy [i] responses /responses not served on this route (404 from the azureopenai upstream) remediation: This route's upstream does not serve the OpenAI Responses API. Call it with the Chat Completions API: client.chat.completions.create(...) on donkey.llm.client(), or a framework's chat-completions client. [ok] chat completions served on this route
donkey doctor --model gpt-4o # model to test against the allow-list (default gpt-4o) donkey doctor --json # machine-readable checks

donkey mock

Runs the local simulator, which replays captured gateway rejections. Needs the [local] extra.

donkey mock --port 8080 --host 127.0.0.1 \ --scenario pii_block:every=5 \ --scenario budget:limit=20000,window=60s \ --scenario request_limit:limit=3,window=60s

The flags are listed in the command reference. The --scenario rule syntax is in Scenario scripting.

The port isn’t read from an environment variable or .donkey-kit.toml; these flags (or the serve() keyword arguments) are the only way to change it. See Choosing a port or host for the programmatic entry point and the 0.0.0.0 caveat.

An invalid --scenario exits with code 2.

donkey dev

Serves a @donkey.agent handler over A2A behind a simulated gateway ingress, which rejects inbound calls with the simulator’s fixtures. Needs the [a2a] and [local] extras.

donkey dev my_agent:handle --port 8000 --scenario pii_block:every=5

TARGET is module:attribute, imported from the current directory. The ingress, the rules it takes and where its rejection shapes come from are in Simulated ingress. A target that can’t be loaded or isn’t marked with @donkey.agent, and an invalid --scenario (including budget), exit with code 2.

--protocol-version accepts 1.0 (default) or 0.3.0; an unsupported value also exits 2 before loading the target. --agent-version sets the card’s application release version (default 0.0.0), not the protocol:

donkey dev my_agent:handle --protocol-version 0.3.0 --agent-version 2.4.0 \ --scenario pii_block:every=5

v1 supports injection, pii_block and request_limit on SendMessage and SendStreamingMessage. v0.3 supports only PII/rate replay on message/send; injection exits 2 at startup. With scenarios configured, message/stream gets local plain-text HTTP 400 before a rule advances, even if none would reject. With no scenarios it passes through. Known wrong-version call methods and explicit mismatched version headers on calls get the same local 400, not an invented gateway refusal. Every response carries x-donkey-simulator: true. See the scenario/version/method matrix.

--host defaults to 127.0.0.1. A host that isn’t loopback, such as 0.0.0.0, still binds, but donkey dev prints a warning on stderr. Nothing authenticates the caller, so anyone who can reach the port can call the agent. The ingress answers a request body over 4 MiB with a 413.

donkey test

A thin front end to pytest --donkey-conformance — it does not re-implement the runner. Point it at your agent factory and pass any trailing pytest arguments straight through; pytest’s exit code becomes donkey test’s own. Needs the [test] extra.

donkey test --agent my.pkg:make_agent -k governance -x donkey test --agent my.pkg:make_agent --donkey-mode server # over a real port; needs [local]

See Testing & conformance for what the suite checks.

donkey scan

Reads your repository’s source and reports every @donkey.agent, every @donkey.tool, and the MCP servers those tools name with server=. The scan is static: it parses each .py file and never imports or runs it, so a module with side effects at import time is safe to scan. It needs no extra and no credentials, and it writes no file.

$ donkey scan . agent support-triage (app/main.py:13) mcp sku-manager (1 tool: lookup_sku) streamable-http https://sku-manager.acme.com/mcp unattributed issue_refund (set @donkey.tool(server=...)) found 1 agent, 2 tools, 1 MCP server 1 issue app/main.py:9 tautological tool issue_refund: description equals identifier 'issue_refund'
  • A marker counts only when its receiver is a Donkey: the class imported from donkey_kit, an instance built with Donkey(...) or Donkey.from_env(), or such an instance imported from another module in the repository. Other frameworks’ @mcp.tool() decorators are ignored.
  • Decorator arguments are read only when they are literals. server=SERVER_ID is reported as a non-literal-argument issue rather than guessed.
  • A tool without server= is listed as unattributed. Scan never infers a server from a module or function name.
  • How each MCP server is reached, its transport and endpoint, comes from a [donkey.mcp_servers.<id>] table in .donkey-kit.toml, never from code. A server without one is shown as transport undeclared, which is not an issue. See Declaring how an MCP server is reached.
  • An agent’s protocol and endpoint come the same way from a [donkey.agents.<name>] table. See Declaring how an agent is reached.
  • Issues cover a missing, tautological or too-short description, an invalid service ID or skill list, a service ID used twice, two tools with the same name on one server, a file that fails to parse, and an invalid [donkey.mcp_servers] or [donkey.agents] declaration. donkey scan exits 1 when it finds any of them, so it works as a CI gate, 0 when there are none, and 2 when the path does not exist.

donkey scan --json (or the global donkey --json scan) prints the model as canonical JSON: keys and entries are sorted and paths are relative, so the same code always gives the same bytes and a CI diff shows only real changes. The digest field hashes what would be published and leaves out file paths and line numbers, so moving code around does not change it.

Scan is the first half of Scan & publish: the model it builds is the input donkey publish reads.

donkey publish

donkey publish --dry-run . # the assets a publish would register; no network call donkey publish . # publish the MCP servers and agents that changed

Registers each MCP server and agent that donkey scan finds as an Exchange asset, in the group and at the version declared in [donkey.publication]. An asset whose latest published version has the same digest is left unchanged; one changed without a version bump is refused before anything is published. It reads the ANYPOINT_* control-plane credentials.

With --json it prints the publish document (publish_format: 1; with --dry-run, the plan, plan_format: 1). Each asset carries a status and a detail, also when the publish fails:

statusMeaning
publishedA new version was published, or a rerun finished an incomplete one.
unchangedThe latest version already has this digest, and its publish is complete.
incompleteThe version is published, but its endpoint, page, or name and description were refused. A rerun finishes it.
failedExchange refused the asset, and nothing was published for it. The detail ends with the fix.
not_attemptedAn earlier asset failed, or an issue stopped the publish, so this one was not tried.

It exits 0 when every asset is published or unchanged, 1 on an issue or when an asset is failed or incomplete (what was published before stays published), and 2 on a missing path, invalid config or missing credentials. See Scan & publish.

donkey verify

donkey verify . # each published MCP server and A2A agent against its live side donkey --json verify . # the same, with each asset's outcome as JSON

Runs Publication.verify() on each MCP server and a2a_v1 agent donkey publish would register, at the version declared in [donkey.publication]: the tools an MCP server’s version was published with against the tools it lists through its gateway, and the card an agent’s version was published with against the card it serves there. It writes nothing. Each asset is reported as match, drift (with each difference) or error; an agent with protocol other or none declared is skipped, since it has no card to compare. With --json it prints the verify document (verify_format: 1), where a declaration issue makes every asset not_attempted.

It reads the ANYPOINT_* control-plane credentials for Exchange and the gateway credential (DONKEY_LLM_PROXY_CLIENT_ID and DONKEY_LLM_PROXY_CLIENT_SECRET) for the live side, and exits 0 when every verified asset matches, 1 on drift, a failed read or a declaration issue (nothing is read then), and 2 on a missing path, invalid config, or missing control-plane credentials or gateway credential. The CLI has no token provider, so in jwt or bearer mode it has no gateway credential: verify with DONKEY_LLM_PROXY_AUTH=client-id, or call Publication.verify() from code. Run it in CI after a deploy to catch a server that changed without a new published version.

donkey expose

donkey preflight --service sku-manager # what expose would do; reads only donkey expose --service sku-manager --dry-run # the same donkey expose --service sku-manager # publish, create, add policies, deploy

The argument is the path to scan (. by default), and --service names the service, which you can leave out when the project has exactly one. The 0.2.0 form, with the service ID as the argument (donkey preflight sku-manager), still works until 0.3.0: when nothing is at that path and the project has a service with that ID, the command reads it as --service and prints a deprecation warning.

Puts one MCP server or A2A agent behind a gateway that already exists, in the environment ANYPOINT_ENV (or --env) names. It runs one step at a time and prints one line per step:

✓ environment present Sandbox (…) ✓ gateway present shared-omni-gateway, ingress port 8081 ✓ registry created sku-manager: published 1.0.0 ✓ instance created sku-manager (21262612), upstream https://sku.example.com/mcp ✓ policy mcp-support created inbound mcp-support 1.1.1 ✓ deployment created applied on shared-omni-gateway MCP server sku-manager is exposed at https://<gateway>/sku-manager/
  • registry publishes the service’s Exchange asset, as donkey publish does.
  • instance creates the API Manager instance for that version, labelled with the service ID unless the declaration sets a label, and proxying to the service’s endpoint unless it sets an upstream.
  • policy adds each declared policy the instance lacks. Policies come only from the declaration: there are no defaults.
  • deployment deploys the instance to the gateway and waits until the gateway has applied it.

What the run needs comes from the [donkey.expose] table in .donkey-kit.toml; see A2A agents for the keys.

The command adds what is missing and nothing else:

  • A re-run changes nothing that is there; each step reports present.
  • It never deletes, never edits a policy’s configuration, and never moves an instance to another gateway. Something that is there but differs from the declaration, such as another upstream or a policy at another version, is reported as differs and left alone, and the command exits 1.
  • It never creates the environment or the gateway. A missing one is reported as missing, with where to create it, and nothing else is tried.
  • A failed step is reported as failed, with what to do, and the steps after it are skipped. A step that did not happen is never reported as done.

donkey preflight, like --dry-run, makes only the reads and reports what would be created as planned. Run it in CI before a deploy: it exits 1 when the gateway, the environment or a connected-app scope is missing.

Both exit 0 when every step is present, created or planned; 1 when a step is missing, differs or failed, or the declaration has an issue (nothing is sent then); and 2 on a missing path, invalid config or missing control-plane credentials. With --json both print the report (expose_format: 1), with the declaration’s issues when it has any. The connected-app scopes they need are in Connected-app scopes.

Planned commands Roadmap

These commands are part of the Roadmap and are not available in the CLI yet:

  • donkey serve — serve your agent over A2A from the command line. In code, donkey.serve() does it today. See A2A agents.

Run donkey --help to see the commands available in your installed version.

Last updated on