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, usedonkey.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 gatewayGlobal 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:
| Command | Format key | What it prints |
|---|---|---|
donkey scan | scan_format: 1 | The scan model. |
donkey publish --dry-run | plan_format: 1 | The plan: the assets a publish would register, and the issues. |
donkey publish | publish_format: 1 | The plan’s assets, each with a status and a detail, and the issues. |
donkey verify | verify_format: 1 | The plan’s assets, each with a status, a detail and its differences, and the issues. |
donkey preflight, donkey expose | expose_format: 1 | ok, 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):
| Option | Default | Meaning |
|---|---|---|
--version | off | Print the donkey-kit version and exit. |
--config | none | Where init writes .donkey-kit.toml, or the project config file doctor reads. |
--env | none | Anypoint environment init writes (e.g. Sandbox). init only. |
--json | off | Emit machine-readable JSON where the command supports it. |
donkey dev: Serve an agent over A2A behind a simulated gateway ingress.
| Option | Default | Meaning |
|---|---|---|
target | none | The @donkey.agent handler, as module:attribute. |
--port | 8000 | TCP port to bind. |
--host | 127.0.0.1 | Host/interface to bind. |
--agent-version | 0.0.0 | The agent version the card advertises. |
--protocol-version | 1.0 | A2A protocol to serve: 0.3.0 or 1.0 (default). |
--scenario | none | Inbound 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.
| Option | Default | Meaning |
|---|---|---|
--model | gpt-4o | Model id to test against the proxy allow-list. |
--json | off | Emit machine-readable JSON. |
donkey expose: Expose one MCP server or A2A agent through an existing gateway.
| Option | Default | Meaning |
|---|---|---|
path | . | The repository (or one .py file) to scan. |
--service | none | The service ID to expose; optional when the project has exactly one. |
--env | none | The Anypoint environment (ANYPOINT_ENV). |
--target | none | The gateway’s name; overrides the declared target. |
--dry-run | off | Only read: print what would be created, and change nothing. |
--json | off | Emit the report as JSON. |
donkey init: Bootstrap a commented .donkey-kit.toml from the resolved config.
| Option | Default | Meaning |
|---|---|---|
--force | off | Regenerate even if the file already exists. |
donkey mock: Run the local gateway simulator.
| Option | Default | Meaning |
|---|---|---|
--port | 8080 | TCP port to bind. |
--host | 127.0.0.1 | Host/interface to bind. |
--scenario | none | Fault-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.
| Option | Default | Meaning |
|---|---|---|
path | . | The repository (or one .py file) to scan. |
--service | none | The service ID to expose; optional when the project has exactly one. |
--env | none | The Anypoint environment (ANYPOINT_ENV). |
--target | none | The gateway’s name; overrides the declared target. |
--json | off | Emit the report as JSON. |
donkey publish: Publish code-first assets to Exchange.
| Option | Default | Meaning |
|---|---|---|
path | . | The repository (or one .py file) to publish. |
--dry-run | off | Print the assets and digests it would publish; no network call. |
--if-changed / --always | on | Skip an asset whose latest published version has the same digest. |
--json | off | Emit the plan, or what was published, as JSON. |
donkey scan: Find @donkey.agent and @donkey.tool markers statically and report them.
| Option | Default | Meaning |
|---|---|---|
path | . | The repository (or one .py file) to scan. |
--json | off | Emit the canonical scan model as JSON. |
donkey test: Run the conformance suite against your agent.
| Option | Default | Meaning |
|---|---|---|
--agent | none | Import 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.
| Option | Default | Meaning |
|---|---|---|
path | . | The repository (or one .py file) to verify. |
--json | off | Emit 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
initand a real request never disagree about what is required. - Never writes a secret.
client_secret,llm_proxy_client_secret, andllm_proxy_keyare emitted as commented pointers, not values. Put them in a gitignored.donkey-kit.local.tomlnext 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 usehttps://, thatlocalhostis accepted over plainhttp://, and thatDONKEY_ALLOW_HTTP=1in the environment (not in the file) allows plainhttp://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_secretpair is rejected. - Wrong URL — the gateway answers, but no proxy is deployed on that base
path: an empty
404with nox-llm-proxy-*headers. Thegatewayline fails andcredentialsandmodelshow as not checked. A typo in the path, a trailing/v1(the governed proxy has no/v1segment), 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.
/responsesnot served on this route — the proxy accepted the credentials and routed the model, but the upstream answered the Responses API with404. An Azure OpenAI route does this.doctorthen tries/chat/completionsonce and reports the route as working if that answers. Call it withclient.chat.completions.create(...)ondonkey.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[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 agoOn an Azure OpenAI route, the responses line explains the 404 and the run
still exits 0:
[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 routedonkey doctor --model gpt-4o # model to test against the allow-list (default gpt-4o)
donkey doctor --json # machine-readable checksdonkey 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=60sThe 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=5TARGET 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=5v1 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 fromdonkey_kit, an instance built withDonkey(...)orDonkey.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_IDis reported as anon-literal-argumentissue 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 astransport 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 scanexits1when it finds any of them, so it works as a CI gate,0when there are none, and2when 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 changedRegisters 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:
status | Meaning |
|---|---|
published | A new version was published, or a rerun finished an incomplete one. |
unchanged | The latest version already has this digest, and its publish is complete. |
incomplete | The version is published, but its endpoint, page, or name and description were refused. A rerun finishes it. |
failed | Exchange refused the asset, and nothing was published for it. The detail ends with the fix. |
not_attempted | An 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 JSONRuns 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, deployThe 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 publishdoes. - 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’sendpointunless it sets anupstream. - 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
differsand left alone, and the command exits1. - 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 areskipped. 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.