Donkey Development Kit

An SDK for consuming Agent Fabric capabilities — governed model and tool access — from your own agent framework, in your own IDE, without adopting Mule.

Project status — alpha. This is an early release (Development Status :: 3 - Alpha). The LLM data plane is live-verified; most other surfaces are verification-gated (see What's verified below). Install it from PyPI with pip install donkey-kit — see Install. Unofficial: an independent project, not affiliated with or endorsed by Salesforce or MuleSoft.

Support & trademark statement (please read)

"Agent Fabric" is a MuleSoft (Salesforce) product name, not a generic term. MuleSoft, Anypoint, Omni Gateway, and Agent Fabric are Salesforce trademarks.

Maintainer & support. This is an independent, community-maintained project, published under the org-scoped Donkey-Development-Kit name — it is not affiliated with, endorsed by, or supported by Salesforce or MuleSoft. It is provided as-is, without warranty of any kind; the maintainers triage issues and pull requests on a best-effort basis, with no SLA. Because it ships under a distinct, org-scoped name, only the descriptive form ("an SDK for MuleSoft Agent Fabric") appears in prose — the package does not represent itself as a first-party, official-status SDK.

Licensed under Apache-2.0. See the unsupported boundary for exactly which platform APIs this SDK calls and their support classification.

Security. Report vulnerabilities privately, never in a public issue. See SECURITY.md for supported versions and how to report.

Python versions. CPython 3.10–3.14, each tested in CI; a version is dropped in the first minor release after its end of life. See docs/python-support.md.

Contents

• Documentation
• Install
• Framework support
• What's verified (verification discipline)
• Conformance exemptions

Documentation

Two audiences, two doc sets:

• Use the SDK → the documentation site: https://docs.donkey-kit.dev/. Install and configure, per-framework model access, the governed error taxonomy, and what to trust today — everything you need to point your agent at a governed proxy.
• See it run → runnable demos live in the companion repo donkey-development-kit-demos: the framework-free client, native framework objects, the governed error taxonomy, and the screen-recording scripts.
• Understand or contribute to the repo:
  • ARCHITECTURE.md — how the SDK is built: the layered stack, the framework-free core, verification discipline, the error taxonomy, and framework tiering.
  • CONTRIBUTING.md — how to work in the repo: the branch/PR/release workflow, the testing strategy, coding conventions, and the docs-sync rule.
  • docs/verified-apis.md — the verification ledger: the single source of truth for what is confirmed against a real sandbox and what is still blocked.

Install

pip install "donkey-kit[llm,langgraph]"   # base + raw client + one framework

To work on the SDK itself, install from source with the contributor tooling (the dev dependency group needs pip 25.1 or later):

git clone https://github.com/Donkey-Development-Kit/donkey-development-kit.git
cd donkey-development-kit/python
pip install -e ".[llm,cli]" --group dev

Extras are one per framework (langgraph, adk, strands, agent_framework, openai-agents, anthropic, crewai, llamaindex) plus otel, cli, local, test (the conformance pytest plugin — pytest --donkey-conformance --donkey-agent=my_app.agent:build), and all. all is everything a user runs that installs together — llm, langgraph, otel, cli, local — with no test runner, so add test for the conformance plugin: donkey-kit[all,test]. It leaves out the seven other framework extras, because whether they install together depends on their upstream releases. The generated co-installability table shows which combinations resolve, re-checked nightly. Add the one framework you use: donkey-kit[all,crewai]. Configuration and first-agent walkthroughs live on the documentation site.

Framework support

The roster is deliberately two deep, six shallow (BG §1.8): LangGraph and the OpenAI Agents SDK are held to the full conformance bar, the rest supported through the three-line connection_kwargs() escape hatch. Every framework below returns its framework's own native object — never a wrapper.

Each factory's status is its constructor row in the docs/verified-apis.md §8; its depth is the adapter roster's conformance_tested.

Framework	Factory	Depth	Ledger status
LangGraph	donkey.langgraph.chat_model()	Conformance-tested	Live-verified
Google ADK	donkey.adk.model()	connection_kwargs()	Live-verified
Google ADK	donkey.adk.gemini()	connection_kwargs()	Live-verified
Strands	donkey.strands.model()	connection_kwargs()	Live-verified
MS Agent Framework	donkey.agent_framework.chat_client()	connection_kwargs()	Live-verified
OpenAI Agents SDK	donkey.openai_agents.model()	Conformance-tested	Live-verified
Anthropic SDK	donkey.anthropic.client()	connection_kwargs()	Live-verified
CrewAI	donkey.crewai.llm()	connection_kwargs()	Live-verified
LlamaIndex	donkey.llamaindex.llm()	connection_kwargs()	Live-verified

Signature-confirmed means the factory builds its native object against the installed framework (scripts/verify_frameworks.py), with no live round-trip. Live-verified means a real round-trip through a governed proxy. The raw client (donkey.llm.client()) is conformance-tested too.

connection_kwargs() works for all eight; a deep adapter is promoted from demand evidence, one at a time — never guessed up front. The OpenAI Agents SDK was the second, on Phase 1 demand (#223); the next is #244. See the framework pages for each. Which framework versions are supported and tested is on the site's version compatibility page and in docs/framework-support.md.

What's verified (verification discipline)

The LLM data plane — governed model access through the Omni Gateway proxy — is live-verified against a real Anypoint sandbox. The framework-free client and the framework adapters are wired to that contract; the raw client is conformance-tested against the simulator. For the adapters (each factory is listed under Framework support):

LangGraph and OpenAI Agents SDK are conformance-tested against the simulator in CI. Each adapter factory's constructor row in §8 of the ledger reads live-verified.

Everything still gated raises NotImplementedError("blocked on verification: …") rather than guessing at an unverified endpoint, header, or class name — that currently includes Exchange→MCP tool discovery and Exchange publication; their types live in donkey_kit.experimental, outside the stable namespace. The SDK does not ship a provisioning control plane (ADR 0008 in docs/adr/). The adapters build their framework's native object directly; they refuse only when the installed framework version lacks the class or field the adapter depends on.

The discipline behind this is documented in ARCHITECTURE.md → Verification discipline; the row-by-row worklist is docs/verified-apis.md.

Conformance exemptions

The conformance plugin holds the SDK to the same bar it asks of your agent. Where a framework legitimately cannot satisfy a scenario, the reason is asserted in code (KNOWN_LIMITATIONS) and published here as credibility — never a silent skip (the conformance kit):

Framework	Scenario	Why it's exempt
CrewAI	correlation ID propagated	CrewAI's native OpenAI provider builds both its sync OpenAI and its AsyncOpenAI from one client_params dict, and with an interceptor set it replaces http_client with its own httpx client, so the SDK's async client cannot be injected and the correlation ID ends up per-client, not per-run. ADK (model() and gemini()), LlamaIndex and Microsoft Agent Framework send through the SDK's shared client and record no exemption (#691, #740).
CrewAI	gateway identity observed	For the same reason, no response reaches the SDK's _on_response hook. When every resolved adapter is non-observing, donkey.last_call reports UNAVAILABLE and names them in surface.
CrewAI	JWT refreshed per send	CrewAI's native OpenAI provider owns the transport and builds its own clients, so the rotating JWT the SDK adds per send never reaches its requests. donkey.crewai.llm() and connection_kwargs() raise ConfigError in jwt mode; use client-id auth with CrewAI. ADK's model() and gemini(), LlamaIndex and Microsoft Agent Framework send through the SDK's client and carry the rotating JWT on async calls (jwt mode).
CrewAI	budget refusal not retried	CrewAI wraps every LLM call in its own rate-limit retry (3 attempts) and treats any 429 as a rate limit, so a TokenBudgetExceeded or RequestRateLimitExceeded refusal is sent 3 times. CrewAI has no setting to turn it off; the OpenAI client underneath has max_retries=0. Every other adapter sends a budget refusal once (#734).
CrewAI	typed refusal bridged	CrewAI's native OpenAI provider owns the transport, so its errors come from a client the SDK never saw, and donkey.run() and typed_refusals() cannot tell a gateway refusal from any other failure there and pass those errors through (#724). ADK's gemini() and model() send through the SDK's transport and are bridged (conformance-tested in #955 and #969). LiteLLM, under model(), re-raises a refusal as its own exception, and the adapter's llm_client marks that exception with the refusal the SDK's transport received.
CrewAI	refusal handler cannot un-refuse	CrewAI's native OpenAI provider owns the transport, so its refusals never reach the SDK's _on_refusal hook and handlers registered with donkey.on(...) do not run for its calls. Every other adapter runs them, and none can turn a refusal into a success (#208, #209).
CrewAI	custom policy typed	For the same reason, a refusal shape registered with classify.register() is neither typed by donkey.run() nor seen by donkey.on(...) handlers for CrewAI's calls. Every other adapter raises the registered type, runs its handlers and records its slug as donkey.policy.type (#210).
CrewAI	agent kill stops cleanly	CrewAI's native OpenAI provider owns the transport, so a kill-switch refusal never reaches the SDK's transport: it does not stop donkey.budget.pace() loops or flush spans, and CrewAI's own rate-limit retry decides whether the call is re-sent. Every other adapter sends the kill once, stops every pace loop on the same Donkey, and flushes spans before the AgentKilled reaches your code (#220).
CrewAI	approval round trip	CrewAI's native OpenAI provider owns the transport, so when an approved @donkey.tool(approval="required") resumes, its model call carries neither the approval's correlation ID nor a typed refusal. The pause and the approver's span event work as for any Python code. Every other adapter but the OpenAI Agents SDK resumes the call under the decision's correlation ID, and the gateway still judges it: a refusal comes back typed (#211, #212).
OpenAI Agents SDK	approval round trip	Under Runner.run, the Agents SDK turns an exception raised inside a function_tool into a tool-result string for the model (its default failure_error_function), so the ApprovalRequired an approval-gated tool raises never reaches your code, the tool does not run, and there is no pause to resume. Mapping DDK approvals onto the SDK's own needs_approval interruptions is #213. Every other scenario passes against a Runner.run (#223).

Each exemption matches what the adapter reports in donkey.<framework>.capabilities() (a frozen AdapterCapabilities per factory), and a unit test keeps the two in step (#726).