Live
Scan & publish
donkey scan, donkey publish and donkey verify are live: publish plans
(--dry-run sends nothing) and registers each MCP server and agent in Exchange
from CI, and verify checks the live side against what was published. The
collision check and descriptor="auto" derivation are on the
Roadmap; their sections are badged and show the planned design.
donkey scan walks your repository and finds every
@donkey.agent and @donkey.tool, plus
the MCP servers those tools name with server=. It produces one deterministic
model of them. Publishing registers that model with Exchange / Agent
Registry, and the GitHub Action runs both on every merge
to main.
The registry becomes a consequence of the code, not a chore. A support agent with six tools registered by hand has a stale tool list within a week; with the Action, every merge updates it.
This complements MuleSoft’s Agent Scanners. Agent Scanners discover agents from Agentforce, Bedrock, Vertex AI, and Copilot Studio at runtime. Scan is the design-time / CI source for the agents you build in plain Python, which no cloud scanner can see. Its model feeds direct Exchange publishing today, and is planned to feed the platform’s self-managed scanner too, so the platform stays the system of record.
donkey scan — the model of your code Live
donkey scan . # a summary, and any issues
donkey scan . --json # the canonical model, for a CI diffScan is static: it parses your source and never imports or runs it. It needs no credentials and writes no file. The model lists:
- agents: each
@donkey.agent, with its name (a service ID), skills and description, and the protocol and endpoint you declare for it (see Declaring how an agent is reached), - tools: each
@donkey.tool, with its parameters, description,server,approvalandrisk, - MCP servers: each distinct
server=ID and the tools that name it, - unattributed tools that have no
server=. Scan reports them and never guesses a server. - for each MCP server, the transport and endpoint you declare for it
(see below), or
nullwhen you declare none.
The model is deterministic: the same code always gives the same JSON, and its
digest leaves out file paths and line numbers, so moving code does not look
like a change. Scan also reports issues and exits 1 when it finds one:
a missing or tautological description, an invalid service ID, a non-literal
decorator argument it cannot read, or a service ID used twice. That way CI
fails before anything is published. See donkey scan for
the full rules.
Declaring how an MCP server is reached
Publishing an MCP server needs to say how a client reaches it, and that is not
something scan can read from code: nothing ties a server= ID to the object
that serves it, and the URL a client uses depends on where the server is
deployed. So you declare it, one table per server ID, in .donkey-kit.toml
beside your code:
# .donkey-kit.toml (committed)
[donkey.mcp_servers.hr-tools]
transport = "streamable-http"
endpoint = "https://hr-tools.acme.com/mcp"
[donkey.mcp_servers.sku-manager]
transport = "stdio"-
transportis one of the MCP transports:stdio,streamable-http, orsse(deprecated by the MCP specification, still accepted). -
endpointis thehttporhttpsURL a client connects to, normally the gateway-fronted one. Astdioserver is started as a process and has no endpoint. Don’t put credentials in the URL. The endpoint is published as written, so scan refuses a URL with a user name or password, or a query parameter named like a credential (token,secret,password,api_key,client_id,key,sigand similar). The issue names the parameter, never its value. -
A
.donkey-kit.local.tomlbeside it (gitignored) overrides the project file key by key, so each environment can point at its own endpoint without editing the committed file:# .donkey-kit.local.toml [donkey.mcp_servers.hr-tools] endpoint = "http://localhost:8080/mcp"
Scan reads only these two files in the scanned directory, not your user-wide
config file, and parses them without running anything. A server with no table
is reported with no transport and no endpoint. Scan never guesses one, and this
is not an issue, so donkey scan still exits 0. An unknown transport, an
endpoint that is not an http(s) URL, an unknown key, or a table for an ID that
no @donkey.tool names is an issue and fails the scan.
The declaration is part of the scan digest, because it is part of what would
be published. Settings outside [donkey.mcp_servers] are unaffected:
Donkey.from_env() ignores the table.
Declaring how an agent is reached
An agent’s Exchange asset says which protocol it speaks and, for an A2A agent, the URL its agent card names. Neither is in the decorator, so you declare them the same way, one table per agent name:
# .donkey-kit.toml (committed)
[donkey.agents.support-triage]
protocol = "a2a_v1"
endpoint = "https://agents.acme.com/support-triage/"protocolisa2a_v1, for an agent served over A2A 1.0 such asdonkey.serve(), orother.a2a(A2A 0.3) is refused with a hint, becausedonkey.serve()speaks 1.0.endpointis thehttporhttpsURL the agent is served at, with the same rules as an MCP server’s. Ana2a_v1agent needs one.- An agent with no table is published with protocol
otherand no endpoint. This is not an issue. .donkey-kit.local.tomloverrides the file key by key, and the declaration is part of the digest, as for[donkey.mcp_servers]. A table for a name that no@donkey.agentuses is an issue.
A service ID (@donkey.agent(name=...), @donkey.tool(server=...)) names a
service in the registry permanently, so choose it deliberately. Renaming
it later would register a second service rather than rename the first.
Planning a publish
donkey publish --dry-run . # the assets a publish would register
donkey publish --dry-run . --json # the same plan as canonical JSON (plan_format: 1)The dry run scans your code the way donkey scan does, then prints one
Exchange asset per MCP server (type mcp) and per agent (type agent), with
its group ID, asset ID and version, and the digest a publish would compare
with the latest published version’s. It makes no network call and needs no
credentials.
Exchange coordinates aren’t in your code, so you declare them in a
[donkey.publication] table in .donkey-kit.toml beside your code:
# .donkey-kit.toml (committed)
[donkey.publication]
version = "1.3.0" # required, a semantic version
group_id = "acme" # optional: defaults to your org_id (ANYPOINT_ORG_ID)
protocol_version = "2025-06-18" # optional
provider = { organization = "Acme HR", url = "https://hr.acme.example" } # optional
[donkey.publication.assets.hr-tools] # a service ID; every key is optional
asset_id = "hr-tools-mcp" # default: the service ID
name = "HR Tools" # default: the service ID
description = "Look up employees and their managers."
version = "1.4.0" # default: the table's version
documentation = "docs/hr-tools.md" # Markdown that opens the asset's page
# protocol_version and provider can be set here too, overriding the table's- An MCP server has no description in code, so give it one here. An agent defaults to its own description. Exchange and Agent Fabric show the name as the asset’s title and the description under it. A name or description you change later is applied with the next new version, to every version.
protocol_versionis the MCP protocol revision your server speaks:2024-11-05,2025-03-26,2025-06-18or2025-11-25.provideris who provides it, with bothorganizationandurl. Agent Fabric shows them as the asset’s protocol version and provider; withoutproviderit shows “Other”. Both describe an MCP server, so an agent’sassetstable can’t set them; the table-wide ones apply to MCP servers only.documentationis a UTF-8.mdor.markdownfile, relative to the scanned directory and inside it. Hidden path components and components whose name before the first dot iscredentialsorsecrets(case-insensitive) are refused, including symlink targets. Configuration guides such asconfig.md,docs/configuration.mdandconfiguration/guide.mdare allowed. These naming checks do not sanitize the file’s content; review it before publishing. The dry-run JSON shows the source path; review it before publishing. Its content opens the asset’s page (see below).- A
.donkey-kit.local.tomlbeside it overrides the project file key by key, as for[donkey.mcp_servers]. - The digest covers what would be published for that asset: its tools, their descriptions and parameters (an agent’s skills), how the server or agent is reached, the asset’s name and description, and the protocol version, provider and documentation content when you set them. Editing the documentation file is a change, so it needs a new version. The digest leaves out file paths, line numbers and the version, so moving code or bumping the version alone does not look like a change.
The dry run exits 1 on any issue, so CI can run it on every pull request:
every issue donkey scan reports, plus a missing group ID or version, a
version that isn’t semantic, an unknown key, a protocol version or provider
the metadata can’t carry (or one set for an agent), a documentation file that is missing or outside the
scanned directory, or an assets table for a service ID your code doesn’t
define.
Publishing MCP servers
donkey publish . # publish what changed (--if-changed is the default)
donkey publish . --always # publish even when the digest matches the latest version
donkey publish . --json # each asset with its status and detail (publish_format: 1)Without --dry-run, donkey publish registers each MCP server in the plan as
an Exchange asset of type mcp, in the group and at the version you declared.
It runs from CI with the control-plane credentials: ANYPOINT_CLIENT_ID,
ANYPOINT_CLIENT_SECRET and ANYPOINT_ORG_ID. The connected app needs
the manage:exchange scope on that business group: with edit:exchange or
create:exchange only, a version can be published but its endpoint cannot be
registered. See Connected-app scopes. Publishing has been checked against a live sandbox
with a connected app’s token.
Each asset is published with:
- its name and description. Exchange keeps the ones an asset’s first version
was published with, so when a later version declares a different name or
description,
donkey publishsets it on the asset after publishing the version. A description you don’t declare leaves the asset’s as it is. - the digest, stored with the asset so the next run can compare it,
- an
mcp-metadatafile: the transport, the tools with their descriptions and an input schema from their parameters, the capabilities (tools, and no resources, prompts or logging, since scan sees only tools), the protocol version and provider you declared, and the asset’s coordinates. A parameter annotatedstr,int,float,bool,listordictgets that JSON Schema type; any other parameter accepts any value. No parameter is marked required, because scan does not record defaults. - the endpoint you declared in
[donkey.mcp_servers], if any, registered as an external instance. Exchange keeps instances per minor version, so a new patch version reuses the existing one. - a Home page, generated in Markdown. Agent Fabric shows it as the asset’s
Documentation section. Every page has the same sections: an Overview with
the description (or “No description is declared.”) followed by your
documentationfile; the tools, each with its description, theapprovalandriskit declares, and a table of its parameters; on a new version of an existing asset, “Changes since” the latest published version (tools added or removed, a description changed, a parameter added, removed or given another type), which a first publish leaves out; how to connect (transport, endpoint, protocol version); and provenance: the asset ID and version, the content digest and, when the publish runs in GitHub Actions, the repository, the commit and a link to the run. It never includes credentials or your org ID. Only a new version gets a page; an unchanged asset keeps the one it has. A rerun that finishes a publish writes the page the first run would have, with “Changes since” the published version before it.
A publish is safe to repeat:
- With
--if-changed, an asset whose latest published version has the same digest is left alone. A merge that changes nothing, or that only bumps the version, publishes nothing. - Exchange never overwrites a version. If you change an MCP server without
bumping its version,
donkey publishstops before sending and tells you to bump it. The same happens if the version is already published with other content. - A rerun finishes a publish that stopped partway. See below.
When a publish fails
Assets are published one at a time, in plan order. When Exchange refuses a
call, donkey publish stops. The assets published before it stay published,
and --json still prints every asset with its status and detail:
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 registering its endpoint, writing its page, or setting the asset’s name and description was refused. |
failed | Exchange refused the asset, and nothing was published for it. |
not_attempted | An earlier asset failed, or an issue stopped the publish, so this one was not tried. |
When the scan or the declaration has an issue, nothing is sent: --json
prints every asset not_attempted, with the issues, and the command exits
1. Each --json document carries a format key; see
JSON output.
The refusal and its fix go to stderr, and a refused asset’s detail ends with
the same fix. A common one: a connected app without manage:exchange can
publish a version but not register its endpoint, so the asset is incomplete.
Fix what was reported and run donkey publish again, with the same version.
A version that has the planned digest counts as unchanged only once its
publish is complete. If it is not, the rerun does whatever is missing:
- registers the endpoint, when the version’s instances don’t list it,
- writes and publishes the Home page, when the version has no published one (for an MCP server, it first reads the tools of the published version before it, for the page’s “Changes since”),
- sets the declared name and description, when the asset’s differ,
and reports the asset published, with a detail such as finished publishing 1.0.0: registered its endpoint. Nothing is published twice, and a complete
version gets no write. Checking the page reads the version’s portal draft, one
more read per unchanged asset.
donkey publish exits 0 when every asset is published or unchanged. It
exits 1 when the plan has an issue (nothing is sent) or an asset is failed
or incomplete, and 2 when the path doesn’t exist, the config is invalid,
or the control-plane credentials are missing.
Publishing agents
The same donkey publish registers each agent as an Exchange asset of type
agent, with the same credentials, the same digest check and the same
version-bump rule. Each agent asset is published with:
- its name and description, as for an MCP server. An agent’s description defaults to its docstring.
- the digest, and the protocol you declared (
otherwhen you declared none), stored with the asset. Exchange stores ana2a_v1agent’s protocol asa2a, with the version carried by its A2A 1.0 card, so the agent is listed as protocola2a, versionv1. That is the form the gateway accepts whendonkey exposefronts the agent. - an
agent-metadatafile: the protocol, the agent’s name and description, and its asset coordinates. - for an
a2a_v1agent, an A2A agent card (a2a-v1-card): the name, description, version, skills, input and output modes and the endpoint, as an A2A 1.0 card. It is built from the same@donkey.agentrecord as the carddonkey.serve()serves, so the two match. - the endpoint, if you declared one, registered as an external instance.
- a Home page with the same Overview and provenance as an MCP server’s, the agent’s skills, and how to connect (protocol and endpoint).
Publishing agents has been checked against a live sandbox, as for MCP servers.
From GitHub Actions
The scan-and-publish action runs donkey publish in a workflow. It lives in
the SDK repository’s action/ folder, so you pin it like any action, to a
release tag or a commit SHA. The action at a ref installs donkey-kit from the
same ref, into its own virtual environment. Your job’s Python is left as it
was.
# .github/workflows/publish.yml
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
persist-credentials: false
- uses: Donkey-Development-Kit/donkey-development-kit/action@<ref>
with:
# On a pull request: plan only, with no credentials.
dry-run: ${{ github.event_name == 'pull_request' }}
client-id: ${{ secrets.ANYPOINT_CLIENT_ID }}
client-secret: ${{ secrets.ANYPOINT_CLIENT_SECRET }}
org-id: ${{ secrets.ANYPOINT_ORG_ID }}A dry run needs no credentials, so it works on pull requests from forks, which
get no secrets. Set group_id in [donkey.publication] so the plan doesn’t
need the org ID either. The action passes the credentials to donkey only
through the environment. A credential input left empty keeps the ANYPOINT_*
variable your job already sets.
Pass client-secret from a secrets.* value only. GitHub masks secrets before
any step runs. The action masks the input in its first step, but the runner
prints that step’s environment before the mask takes effect, so a value from a
variable or another step’s output shows in the log once.
| Input | Default | |
|---|---|---|
path | . | The directory (or one .py file) to scan and publish. |
dry-run | false | true plans and sends nothing (--dry-run). |
if-changed | true | false publishes even when the digest matches (--always). |
client-id, client-secret, org-id | empty | ANYPOINT_CLIENT_ID, ANYPOINT_CLIENT_SECRET, ANYPOINT_ORG_ID. |
python-version | 3.12 | The Python that runs donkey-kit (3.10 or later). |
donkey-kit | empty | A pip requirement to install instead, such as donkey-kit[cli]==X.Y.Z. |
constraints | empty | A pip constraints file in your repository, which pins the versions donkey-kit’s dependencies install at (pip install -c). |
By default the action installs the newest version of each dependency that
donkey-kit allows, so a new release of one of them reaches your pipeline the
day it ships. To keep publishing reproducible, pin donkey-kit to a release
and commit a constraints file for the job’s Python, then pass its path as
constraints. One way to write it is to run
pip freeze --exclude donkey-kit > constraints/publish.txt in a clean virtual
environment where you installed donkey-kit[cli]==X.Y.Z, with the same
Python as python-version. You refresh the file yourself, when you choose to.
The job summary shows a table of the assets: each one’s digest on a dry run,
and each one’s status and detail after a publish, including one that failed
partway. The step’s outputs are the published, unchanged, incomplete,
failed and not-attempted counts, and result, the path of the
JSON that donkey publish --json printed. A failed publish fails the step with
donkey’s exit code, and each line donkey printed to stderr becomes an error
annotation, so the fix shows on the run’s page. Re-running the failed job
finishes the publish (see When a publish fails).
What donkey prints comes from the repository it scans, so the summary shows
every field as plain text, and the stderr echo can’t run a workflow command.
The action reads only the document of its own release: plan_format: 1 on a
dry run, publish_format: 1 otherwise (see JSON output).
If the donkey-kit input installs a release that prints another, the action
writes no summary and no outputs. It fails the step with an annotation that
names the format it found, even when the publish succeeded.
From GitLab CI
There is no GitLab component yet, so run donkey publish in a job of your
own. This one plans on merge requests and publishes from the default branch:
# .gitlab-ci.yml
donkey-publish:
image: python:3.12-slim
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
variables:
DONKEY_ARGS: "--dry-run"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
variables:
DONKEY_ARGS: ""
script:
- pip install "donkey-kit[cli]==X.Y.Z"
- donkey publish . $DONKEY_ARGS --json > donkey-publish.json
artifacts:
when: always
paths:
- donkey-publish.jsonAdd ANYPOINT_CLIENT_ID, ANYPOINT_CLIENT_SECRET and ANYPOINT_ORG_ID as
CI/CD variables under Settings > CI/CD > Variables. Mask the secret and
protect all three: a protected variable reaches only pipelines on protected
branches, so the default branch gets the credentials and a merge request
doesn’t. The dry run needs none; set group_id in [donkey.publication] so
it doesn’t need the org ID either.
donkey publish prints the JSON on stdout, which the job keeps as the
donkey-publish.json artifact, even when the job fails. Any issue or refusal
goes to stderr, so it shows in the job log, and the exit code fails the job.
From Bitbucket Pipelines
There is no Bitbucket Pipe yet, so run donkey publish in a step of your
own. This one plans on pull requests and publishes from main:
# bitbucket-pipelines.yml
image: python:3.12-slim
definitions:
steps:
- step: &donkey-plan
name: donkey publish (plan)
script:
- pip install "donkey-kit[cli]==X.Y.Z"
- donkey publish . --dry-run --json > donkey-publish.json
artifacts:
- donkey-publish.json
pipelines:
pull-requests:
"**":
- step: *donkey-plan
branches:
main:
- step:
name: donkey publish
deployment: production
script:
- pip install "donkey-kit[cli]==X.Y.Z"
- donkey publish . --json > donkey-publish.json
artifacts:
- donkey-publish.jsonAdd ANYPOINT_CLIENT_ID, ANYPOINT_CLIENT_SECRET and ANYPOINT_ORG_ID as
secured variables of the production deployment environment under
Repository settings > Deployments. Deployment variables reach only steps
that name that environment, so the main step gets the credentials and the
pull-request step doesn’t. The dry run needs none; set group_id in
[donkey.publication] so it doesn’t need the org ID either.
As on GitLab, the JSON goes to the artifact, any issue or refusal to the step log, and the exit code fails the step.
On GitLab and Bitbucket, the generated Home page leaves out the commit and
run links: donkey publish reads them only from GitHub Actions.
Scope: code-first assets
Publication is for assets that originate in your code:
- an MCP server written in Python or TypeScript,
- an agent exposed over A2A,
- an agent exposed as a tool without an A2A surface.
It is not for assets the platform already owns. An MCP server created by MCP Bridge from an existing API is already in Exchange; publishing a second, code-derived descriptor would create two catalog entries for one capability.
Collision check Roadmap
donkey publish doesn’t run this check yet. As planned, before publishing the
SDK will search Exchange for an existing asset with the same endpoint, name, or
derived tool signature. On a probable match it will refuse and print the
existing asset’s coordinates, and a planned --allow-duplicate flag will
override it with a WARNING.
The Publication object
The publication types are in donkey_kit.experimental, not donkey_kit, until
descriptor derivation (preview() and export()) is verified. They may change
in any release until then. verify() works
today; preview() and export() raise NotImplementedError.
from donkey_kit.experimental import Contact, Publication, PublicationAssetType
pub = Publication(
asset_type=PublicationAssetType.MCP_SERVER, # MCP_SERVER | A2A_AGENT | AGENT | API
group_id="${ANYPOINT_ORG_ID}",
asset_id="hr-tools-mcp",
version="1.3.0", # semver
name="HR Tools",
description="Employee lookup and leave-balance tools for HR agents.",
# Discovery metadata
tags=["hr", "internal", "agent-tool"],
categories={"Domain": "People", "Lifecycle": "Production"},
contact=Contact(team="People Platform", email="people-plat@acme.com"),
# Type-specific descriptor — exactly one, matching asset_type
descriptor="auto", # introspect the live server
# Documentation pages, published alongside the asset
docs=[
("home", "docs/exchange/overview.md"),
("getting-started", "docs/exchange/quickstart.md"),
],
# Where it actually lives — metadata only
endpoint="https://hr-tools.internal.acme.com/mcp",
)As planned, asset_type will determine which descriptor is required and how it
is generated Roadmap:
asset_type | Descriptor | Generated from |
|---|---|---|
MCP_SERVER | MCP tool manifest — server info, tool names, descriptions, JSON Schema inputs | live tools/list against the running server |
A2A_AGENT | A2A Agent Card | declared skills, endpoint, auth schemes, input/output modes |
AGENT | agent descriptor (no A2A surface) | framework introspection, best-effort |
API | OpenAPI / AsyncAPI | user-supplied file; no generation |
descriptor="auto" — deriving the spec from code Roadmap
This section is the planned design: a Publication doesn’t derive its
descriptor yet. Hand-maintained catalog descriptors go stale within a sprint, so generation is
the core of this feature.
Every supported framework already derives JSON Schema from function signatures,
type hints, and docstrings — @tool in LangChain and Strands, FunctionTool in
ADK and LlamaIndex, @mcp.tool() in the MCP Python SDK, and the equivalent
conventions in CrewAI, the OpenAI Agents SDK, and the Anthropic SDK. The SDK
asks the framework for the schema it already computed rather than
re-deriving it, so the catalog documents exactly the schema the model sees.
Derivation modes
descriptor="auto" # object introspection — the default
descriptor="auto:live" # live protocol introspection — highest fidelity
descriptor="auto:check" # generate, diff against committed file, fail on mismatch-
auto:livestarts the server, performs the MCP initialize handshake, and callstools/list(plusresources/listandprompts/list). It is exactly what a client sees, but the server must actually run, with whatever credentials and network that needs. -
auto(the default) imports your module, locates the tool and agent objects, and reads their already-computed schemas. No server, no network, works in CI. Importing user code executes it, so tool definitions must be import-safe; you will declare explicit entrypoints rather than scanning whole packages, in a planned table such as:[publication.entrypoints] "hr-tools-mcp" = "acme.hr.server:mcp" # module:attribute "hr-agent" = "acme.hr.agent:build_agent" # a zero-arg factory also works -
auto:checkgenerates the descriptor, diffs it against the committed file, and fails on mismatch — useful as a CI gate.
There is no AST-only mode. Parsing source can name a tool but cannot produce
its schema without re-deriving it. Where importing your code is not acceptable,
donkey scan (above) is the static, no-execution view.
A planned donkey publish --cross-check will run auto and auto:live and diff
them. A disagreement will mean either dynamic registration the object graph does
not reflect, or a broken framework adapter.
Type hints give the shape, not the meaning — department: str becomes
{"type": "string"} and says nothing about which departments are valid, or
when to use this tool over a similar one. auto will fail publication on a
description that is tautological or missing, and preview() will report
description quality. Today donkey scan already fails on such a description.
Verifying at runtime: verify()
Publication.verify(donkey) is the read-only runtime check that a live MCP
server or A2A agent still matches what its version was published with. It writes nothing:
there is no runtime publish.
from donkey_kit import Donkey
from donkey_kit.experimental import Publication, PublicationAssetType
pub = Publication(
asset_type=PublicationAssetType.MCP_SERVER,
group_id="${ANYPOINT_ORG_ID}",
asset_id="hr-tools-mcp",
version="1.3.0",
name="HR Tools",
description="Employee lookup and leave-balance tools for HR agents.",
)
async with Donkey.from_env() as donkey:
drift = await pub.verify(donkey) # warns, returns the differences
await pub.verify(donkey, raise_on_drift=True) # raises PublicationDrift insteadIt reads the tools of the version’s mcp-metadata file from Exchange, and
lists the live server’s tools through its gateway instance, with the same
governance check and credential as a donkey.tools binding:
an ungoverned server raises UngovernedMcpServer and is sent nothing. A tool
added or removed, a changed description, or a changed set of parameter names
is drift. Parameter types are not compared, because donkey publish records
only the plain annotations it reads without running your code.
For an AGENT (or A2A_AGENT) publication it reads the card the version was
published with (its a2a-v1-card file, or the a2a-card of a version published
before A2A 1.0) and the card the agent serves at
.well-known/agent-card.json through its gateway instance, with the same
governance check and gateway credential: an ungoverned agent raises
RegistryError and is sent nothing, and so does one whose gateway URL is not
https://. A changed card description, a changed set
of default input or output modes, a skill added or removed, or a skill whose
description changed is drift. The fields that say where and how this deployment
serves the agent are not compared: url, supportedInterfaces,
preferredTransport, protocolVersion, version (your code’s version, not the
asset’s) and the security fields (securitySchemes, security,
securityRequirements), which the upstream declares and the gateway enforces.
You can read the live side yourself, with the same governance check and
credential and no cache: live_tools() returns what the MCP server’s
tools/list returns now, and live_card() the card the A2A agent serves now.
Each takes the asset version as group_id/asset_id/version:
tools = await donkey.tools.live_tools("${ANYPOINT_ORG_ID}/hr-tools-mcp/1.3.0")
card = await donkey.tools.live_card("${ANYPOINT_ORG_ID}/hr-agent/0.1.0")Both methods are provisional: unlike the rest of donkey.tools, they may
change in a minor release, with a migration note in the release notes. See
Stability.
By default each difference is logged at WARNING and returned, so a drifted
catalog is loud without taking down production traffic. With
raise_on_drift=True it raises PublicationDrift, whose message
lists every difference. API publications are not verified and raise
NotImplementedError.
donkey verify runs the same check from CI, for every MCP
server and a2a_v1 agent in the repository.
Both read the live side at a gateway URL that discovery read from the control
plane at base_url, so the gateway credential follows base_url’s rule. If
base_url comes from the working directory’s .donkey-kit.toml or
.donkey-kit.local.toml and isn’t a regional Anypoint host, the credential is
sent only when it comes from those files too, or when DONKEY_TRUST_PROJECT_CONFIG
is set. Otherwise verify() raises ConfigError before anything is sent, and
donkey verify reports each such asset as an error with that message and
exits 1. See
Which credentials a URL receives.
Related
- CLI & decorators — mark tools with
@donkey.tooltoday. - A2A agents — serve and expose the agent whose card you publish.
- Tool access — discover and bind published tools from Exchange.