ATD — Agent Tool Dispatch

The reference implementation of the Agent Tool Dispatch (ATD) protocol.

ATD is a neutral, cross-vendor wire protocol that lets any LLM agent, on any framework, call any tool, on any platform — through a single typed RPC surface. This repository is the Rust source of truth: a wire-type crate, a server runtime, a client SDK, two transports, middleware, built-in tools, an MCP bridge, a CLI, and a conformance suite — plus a Python package mirror.

New here? Read docs/index.md for the documentation map, or docs/atd-architecture.md for the full picture. AI coding agents: start at AGENTS.md.

Every message, in every direction, over every transport, serialises to one machine-readable schema: atd-protocol-schema.json.

git clone https://github.com/downsea/atd
cd atd
cargo run --example hello_atd -p atd-examples

The example auto-spawns the reference server and exercises three tools:

[atd] auto-spawning atd-ref-server → /tmp/.../demo.sock
[atd] connected — 10 tools registered

[1/3] ref:echo.say {"text":"hello from ATD"}
      → {"echoed":{"text":"hello from ATD"}}
[2/3] ref:fs.glob {"pattern":"**/*.toml","path":"."}
      → 9 paths: Cargo.toml, crates/atd-cli/Cargo.toml, ...
[3/3] ref:shell.exec {"command":"uname -s"}
      → exit 0, stdout="Linux"

No external daemon — everything runs from this repo, with zero ANOS dependency.

Every crate publishes to crates.io under the atd-* prefix at one shared version — pin atd-sdk = "1" and the whole stack stays mutually consistent. Pick by what you're doing:

cargo add atd-sdk          # Rust   ·   Python:  pip install atd-client

use atd_sdk::{AtdClient, CallOptions, DiscoverFilter, Endpoint};

let atd = AtdClient::connect(Endpoint::unix("/tmp/atd.sock")).await?;
let tools = atd.discover(None, DiscoverFilter::default()).await?;        // discovery
let out = atd.call("ref:echo.say",
    serde_json::json!({ "text": "hello" }), CallOptions::default()).await?;

Full walkthrough — discover / describe / call, the OpenAI · Anthropic · LangChain adapters, error handling: Rust quickstart · Python quickstart.

cargo add atd-runtime atd-server        # Unix-socket transport
cargo add atd-runtime atd-server-http   # …or HTTP + MCP JSON-RPC

Implement the Tool trait, register it, hand the registry to a listener:

let mut registry = Registry::new();
registry.register(Arc::new(MyTool::new()));
atd_server::Server::new(registry, ServerConfig::default()).run().await?;

How-to: docs/extending/tool.md. Working skeleton (~80 lines): crates/atd-mock-weather-server. Opt-in egress middleware: atd-middleware-fhir, atd-middleware-pii-redact-medical.

cargo install atd-mcp-bridge

Point Claude Desktop / Cursor / Hermes / any MCP client at the bridge binary — config examples in docs/integrations/.

cargo install atd-cli
atd --sock /tmp/atd.sock list           # subcommands: list · schema · call · doctor · skills

See docs/cli.md.

Dev-dep on atd-conformance and run the cross-implementation fixture corpus against your server — pass it and you interoperate. See crates/atd-conformance.

Not sure which path fits? docs/integrations/overview.md maps every framework to one of five integration paths; the full 16-crate map is docs/atd-architecture.md §9.

ATD is agent-native — paste the prompt below into Claude Code · Cursor · Codex, fill in the My task: line at the bottom, and the agent will clone the repo, read the relevant docs, and pick the matching integration path.

ATD (Agent Tool Dispatch) is a neutral cross-vendor wire protocol — any LLM
agent on any framework can call any tool on any platform via one typed RPC
surface. Reference implementation: https://github.com/downsea/atd. Clone it
locally if it isn't already.

Get oriented in this order:
  1. AGENTS.md             — architectural map for AI coding agents
  2. docs/index.md         — documentation map
  3. docs/atd-architecture.md  — dispatch pipeline + 16-crate layout

Then pick the path matching my task:

- Expose <my CLI / REST API / library> as an ATD server
  → docs/extending/tool.md + the ~80-line skeleton at
    crates/atd-mock-weather-server/. Implement Tool, register on a Registry,
    serve via atd-server (Unix socket) or atd-server-http (HTTP + MCP).

- Call ATD tools from <my agent>
  → docs/quickstart/rust.md (or docs/quickstart/python.md). Use atd-sdk:
    discover at startup, render through the OpenAI / Anthropic / LangChain
    adapter, dispatch with AtdClient::call.

- Bridge an ATD server into an MCP-only client
  (Claude Desktop / Cursor / Hermes / …)
  → install atd-mcp-bridge and follow docs/integrations/.

- Verify a third-party ATD server
  → dev-dep atd-conformance and run its fixture corpus per
    crates/atd-conformance. Fix every failing fixture — the suite is the
    interop contract.

Confirm which path my task maps to before writing code; flag ambiguity.

My task: <describe what you want built / changed / verified>

• Protocol — length-prefixed JSON over a duplex byte stream; one unified schema; a full AtdError taxonomy.
• Two transports — atd-server (Unix socket) and atd-server-http (HTTP + MCP JSON-RPC), both routing into one transport-agnostic dispatcher.
• Dispatch — capability gate, tier-aware deadlines, pluggable bindings, HMAC-signed cursor pagination, an egress middleware pipeline.
• Security — capability allow-listing, UCAN-lite bearer tokens, multi-tenant secret routing (TokenBroker), structured audit.
• Reference server — atd-ref-server with 10 built-in tools (ref:echo.say, ref:fs.{read,write,edit,glob,grep}, ref:shell.{exec,pwsh}, ref:web.fetch, ref:external.uname).
• Medical middleware — FHIR R4 egress validation and HIPAA PHI redaction as opt-in crates.
• Conformance suite — atd-conformance; pass it and you interoperate.
• MCP bridge — atd-mcp-bridge connects Claude Desktop, Cursor, Hermes, and any MCP client to any ATD server.

Full inventory: CHANGELOG.md.

┌──────────────┐  length-prefixed JSON   ┌─────────────────────────────────────┐
│   atd-sdk    │ ←────────────────────→  │ atd-ref-server                       │
│  (client)    │   Unix socket / HTTP    │  Hello → capability gate             │
└──────────────┘                         │  registry → tier → binding → mw      │
                                          └─────────────────────────────────────┘
┌──────────────┐   MCP JSON-RPC    ┌────────────────┐      ┌──────────────┐
│  MCP client  │ ← stdio ────────→ │ atd-mcp-bridge │ ←──→ │  ATD server  │
└──────────────┘                   └────────────────┘      └──────────────┘

The full layer model, dispatch pipeline, security model, and crate map are in docs/atd-architecture.md.

ATD attaches third-party code without forking — every extension point is a pub trait with a how-to guide in docs/extending/: add a tool, binding, middleware, transport, auth scheme, or audit sink.

• docs/index.md — the documentation map (start here)
• docs/atd-architecture.md — normative architecture
• docs/protocol/ — wire format + error taxonomy
• docs/extending/ — how to extend each layer
• docs/integrations/ — per-framework wiring
• docs/roadmap.md — evolution scope and deferred work
• docs/issues/ — tracked gaps and adopter validation

The wire schema is regenerated from the Rust types and gated in CI:

cargo run -p atd-protocol --features schema --bin gen-schema -- --check

1.0 — the wire format and the public extension traits are frozen for the 1.x line. See docs/release-plan-v1.0.md for the stability contract and CHANGELOG.md for release history.

See CONTRIBUTING.md. Issues, PRs, and design feedback welcome.

Apache-2.0. See LICENSE.