Agent Protocols
English | 简体中文
Agent Protocols is an open specification repository for interoperable autonomous agents. The repository currently defines six draft protocols:
- Agent Identity Protocol: Ed25519-based agent identity, signed event envelopes, canonical encoding, and verification rules.
- Agent Profile Protocol: portable agent profiles that describe names, capabilities, service endpoints, and provider metadata without replacing cryptographic identity.
- Agent Delegation Protocol: portable, verifiable delegation credentials that state on whose behalf an agent may act — grants signed by principal controller keys, with scopes, constraints, validity windows, and revocation status.
- Agent Discourse Protocol: lifecycle-bounded rooms for multi-agent discussion, built as a small kernel — membership, signed messages, ordered records, verifiable archives — plus a type system through which each room declares schema-validated custom event types, inline or from reusable type packs.
- Agent Knowledge Protocol: an open network for discovering, sharing, and collaboratively evolving knowledge across disciplines. Signed research capsules connect through provenance, assessments, and reuse reports. Public structured queries, batch reads, relationship exploration, and optional ranked search with portable lexical matching help agents find and examine contributions; disciplinary application profiles define more precise interpretation and validation.
- Agent Mail Protocol: decentralized, asynchronous, end-to-end encrypted private correspondence. Recipient-signed Mailbox Cards bind independent encryption keys to replaceable delivery routes; immutable Messages are encrypted locally, then their Packets are signed for offline delivery, replies, and attachments.
English and Simplified Chinese versions are maintained side by side. The English version is the default working language for cross-implementation review. The Chinese version should preserve the same normative requirements.
Specifications
Each specification links its machine-readable files — JSON Schemas, the ADP type packs, and normative test vectors — from docs/protocols. The Rust, TypeScript, and Python SDKs run shared protocol vectors, including Agent Knowledge's object, acceptance, retrieval, and discovery cases.
Protocol Relationship
The protocols are designed to compose without forcing one service to own everything:
- Agent Identity defines
did:agent: identifiers and the signed event envelope shared by the other protocols.
- Agent Profile uses Agent Identity signatures to publish mutable descriptive metadata for an agent.
- Agent Delegation states on whose behalf an agent may act. Grants and revocations are ordinary Agent Identity signed events whose
actor must be a controller key published by the principal's HTTPS URL; Agent Profile can carry delegation discovery hints.
- Agent Discourse uses Agent Identity for all write operations and may resolve profiles from a local profile store or any compatible third-party Agent Profile service.
- Agent Knowledge uses Agent Identity for portable public research contributions and their continuing evaluation, reuse, and evolution. Profile can advertise knowledge services, and Discourse can discuss or supply public evidence for capsules; neither is required for the knowledge graph. Disciplinary application profiles add structured interpretation and validation without changing core identity or authority.
- Agent Mail uses Agent Identity to sign mailbox configuration and HPKE-encrypted packets. Profile may advertise Mailbox Cards; independent relays store ciphertext while recipients decrypt and verify locally. Receiving a letter does not authorize action.
Agent Identity
|
+--> Agent Profile -- delegation hints --> Agent Delegation
|
+--> Agent Delegation (principal-signed credentials)
|
+--> Agent Discourse -- may resolve --> third-party Agent Profile service
|
+--> Agent Knowledge -- derivation, assessments, corrections --> knowledge graph
|
+--> Agent Mail -- encrypted letters, replaceable routes --> private mailbox
MCP Interfaces
General MCP-capable agents should integrate through a local Agent Protocols MCP connector, which owns signing, nonce management, request JWTs, room state, mail encryption, and live SSE synchronization. The connector is a local adapter over the existing protocols, not a new Agent Protocol. See docs/mcp/local-connector/1.0.md.
Besides identity, delegation, profile, and room tools, the connector covers Agent Mail — mailboxes, sending, and syncing new letters into its inbox — and Agent Knowledge — signed submissions, verified queries, search, and lifecycle status checks.
Maturity
All specifications in this repository are currently drafts. Implementers should expect clarifications, test vectors, JSON Schemas, and conformance tests to be added before a stable 1.0 release.
Draft requirements use the RFC 2119 terms MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY.
Repository Layout
crates/
agent-protocols/ Rust SDK for client and server implementations
packages/
agent-protocols/ TypeScript SDK for client and server implementations
python/
agent-protocols/ Python SDK for client and server implementations
docs/
protocols/
agent-identity/
agent-profile/
agent-delegation/
agent-discourse/
agent-knowledge/
agent-mail/
mcp/
local-connector/
SDKs
This repository includes SDKs for common client and server building blocks across the Identity, Profile, Delegation, Discourse, Knowledge, and Mail protocols:
The SDKs cover Agent ID encoding, strict Ed25519 verification, signed event envelopes, Profile materialization, Delegation controller authority, history, and credential verification, the Discourse kernel and type system, permission helpers, and HTTP clients. The Rust and TypeScript SDKs also include the local MCP connector core.
Knowledge support includes event builders and validators, dependency and lifecycle checks, evidence integrity, an in-memory reference store, structured queries, lexical text matching, batch reads, checkpoint-bound pagination with after_seq polling, discovery, and HTTP clients with response validation. Ranked-search helpers validate caller-supplied candidates and the single-page response contract; they do not supply an embedding model or ranking engine. Durable storage, hosted services, and disciplinary validators remain application or future integration work; the Rust and TypeScript local connectors expose the Knowledge MCP tools. See each SDK's README for its public API and examples.
Mail support includes signed card and packet validation, sender-bound HPKE encryption and decryption, card rollback protection, retained decryption keys, logical message deduplication, pre-decryption sender blocking, in-memory relay state, and HTTP clients. Applications must persist security state and keys and commit inbox state before acknowledging delivery; in-memory helpers are not a durable mailbox service. Mail tests use the shared normative vectors and a three-language encryption/decryption matrix. Run make test-mail-interop after installing all three SDKs' development dependencies to exercise fresh packets across languages.
Future additions may include OpenAPI descriptions, SDK guidance for other languages, and broader conformance suites.
Contributing
Issues and pull requests are welcome. Before proposing behavior changes, please read CONTRIBUTING.md and include interoperability and security considerations in the discussion.
License
This repository is licensed under the MIT License.
