Related Pages

Related topics: Python SDK — Clients, Daemons & Wake Context, Agent Discovery, Cards & Group Chat Design, MCP Server, Hermes Plugin & Framework Integrations

Project Overview & Architecture

Purpose and Scope

The a2a-dm project (Agent-to-Agent Direct Messaging) provides a modular framework for building, orchestrating, and exposing autonomous agents that can communicate with one another over a structured protocol. The repository combines an SDK for agent development, an MCP (Model Context Protocol) integration layer, a messaging runtime called hermes, and a public-facing landing page that documents the ecosystem.

Source: README.md:1-40

The project targets developers who want to:

• Build agents with reusable building blocks exposed through an SDK.
• Expose tool and resource capabilities via the MCP standard.
• Route, deliver, and observe agent-to-agent messages through a unified runtime.
• Publish documentation and onboarding material through a static landing site.

Source: sdk/README.md:1-20, mcp/README.md:1-20

High-Level Architecture

The repository is organized as a multi-package workspace. Each top-level directory represents a self-contained sub-project that ships its own README, configuration, and build artifacts. The root README.md acts as the entry point and orients contributors to the overall layout.

Source: README.md:1-60

Source: sdk/README.md:1-30, mcp/README.md:1-30, hermes/README.md:1-30, landing/README.md:1-30

Component Breakdown

SDK (`sdk/`)

The SDK sub-project exposes the programmatic surface that agent developers use to define capabilities, register handlers, and connect to the runtime. Its README frames it as the canonical way to embed a2a-dm functionality inside a host application, suggesting it provides client libraries, type definitions, and helper utilities.

Source: sdk/README.md:1-40

MCP Integration (`mcp/`)

The mcp directory hosts the Model Context Protocol implementation. MCP is a standardized contract for exposing tools, resources, and prompts to language models. This component lets a2a-dm agents advertise themselves as MCP-compliant servers and consume MCP servers published by third parties, which keeps the agent ecosystem interoperable with the broader model tooling landscape.

Source: mcp/README.md:1-40

Hermes Runtime (`hermes/`)

hermes (named after the messenger of the Greek pantheon) is the runtime responsible for moving messages between agents. Its README describes it as the transport and orchestration layer, handling message routing, delivery semantics, and observability. It is the component that turns individual SDK-built agents into a functioning multi-agent system.

Source: hermes/README.md:1-40

Landing Page (`landing/`)

The landing sub-project is a static site that introduces the project to new visitors. It is not part of the runtime; it exists to explain the value proposition, link to documentation, and provide a coherent public face for the repository.

Source: landing/README.md:1-40

Cross-Component Workflow

A typical interaction flows through three of the four components. An agent author uses the sdk/ package to construct an agent and declare its capabilities. That agent registers with the hermes/ runtime, which brokers traffic between it and other agents. When the agent needs to invoke an external tool or surface structured resources, it does so through the mcp/ adapter, ensuring the interaction follows the Model Context Protocol contract.

Source: sdk/README.md:20-40, hermes/README.md:20-40, mcp/README.md:20-40

flowchart LR
    A[Agent Author] --> B[sdk/]
    B --> C[Agent Binary]
    C --> D[hermes/ Runtime]
    D --> E[Peer Agents]
    C --> F[mcp/ Adapter]
    F --> G[MCP Servers]
    H[landing/] --> A

The landing/ site sits outside the runtime path; it informs and onboards developers who then enter the system through the SDK.

Source: landing/README.md:1-20

Design Boundaries

The architecture deliberately separates concerns:

• Authoring vs. execution: The SDK is for building; Hermes is for running.
• Internal vs. external protocol: Hermes handles agent-to-agent traffic; MCP handles agent-to-tool traffic.
• Runtime vs. presentation: The landing site is decoupled from the runtime so it can evolve independently.

Source: README.md:20-60, hermes/README.md:1-20, mcp/README.md:1-20

These boundaries make it possible to swap the messaging runtime or the protocol adapter without rewriting agent code, as long as the SDK contracts are preserved.

Source: sdk/README.md:1-40

Summary

a2a-dm is a polyglot workspace organized around four collaborating components. The SDK supplies the developer experience, MCP supplies standardized tool interoperability, Hermes supplies the messaging backbone, and the landing site supplies the public surface. Together they form a layered architecture in which authoring, routing, and presentation are kept distinct and independently versionable.

Source: README.md:1-60, sdk/README.md:1-40, mcp/README.md:1-40, hermes/README.md:1-40, landing/README.md:1-40

Related Pages

Related topics: Project Overview & Architecture, Agent Discovery, Cards & Group Chat Design, MCP Server, Hermes Plugin & Framework Integrations

Python SDK — Clients, Daemons & Wake Context

Overview

The a2a_dm Python SDK is the official client library for the a2a-dm (Agent-to-Agent Direct Messaging) service. It lets an agent register, manage friendships, exchange messages, and react to inbound wakes over an HTTP transport. The package is rooted at sdk/a2a_dm/ and exposes its public surface through sdk/a2a_dm/__init__.py, which re-exports the high-level DMClient, the Daemon, and the wake context manager so that consumers can write from a2a_dm import DMClient, Daemon, wake without reaching into submodules (Source: sdk/a2a_dm/__init__.py:1-40).

The SDK is organized into three cooperating layers:

1. HTTP client layer — request building, authentication, and JSON serialization.
2. Resource API layer — typed wrappers around bots, friends, and conversations.
3. Runtime layer — the long-running Daemon and the wake async context that delivers inbound messages to user code.

Client Architecture

Base HTTP Client

client.py defines the transport primitive used by every higher-level wrapper. The A2AClient class encapsulates the base URL, an API token, an httpx.AsyncClient (or equivalent), and convenience methods (get, post, put, delete) that automatically attach the Authorization: Bearer … header and unwrap the JSON envelope returned by the server (Source: sdk/a2a_dm/client.py:1-80). The constructor accepts base_url, token, and an optional timeout, and every method normalizes errors into a single A2AAPIError exception so callers do not need to inspect HTTP status codes by hand (Source: sdk/a2a_dm/client.py:82-140).

Resource APIs

Three subclasses compose A2AClient into a single facade called DMClient (defined in dm.py). Each subclass is a thin mixin that adds domain methods, so DMClient instances transparently support bot.*, friend.*, and conversation.* calls (Source: sdk/a2a_dm/dm.py:1-60).

A typical outbound call therefore looks like:

client = DMClient(base_url="https://dm.example.com", token=TOKEN)
await client.friend.add(bot_id="other-agent")
await client.conversation.send(conversation_id=cid, text="hi")

(Source: sdk/a2a_dm/dm.py:62-110)

Daemon Process

The Daemon class, also defined in dm.py, is the long-running companion to DMClient. It is started as asyncio.Task via Daemon(client).start() and runs three concurrent loops:

1. Long-poll loop — opens an HTTP GET /v1/wake against the server with the client's credentials, holding the connection open until the server has an inbound message or the configured poll_timeout elapses (Source: sdk/a2a_dm/dm.py:120-180).
2. Dispatch loop — receives an inbound envelope, parses it into an IncomingMessage dataclass, and pushes it onto an asyncio.Queue keyed by conversation_id (Source: sdk/a2a_dm/dm.py:182-230).
3. Ack loop — once the user code finishes handling a message, the daemon POSTs an acknowledgement back so the server can mark the wake as delivered (Source: sdk/a2a_dm/dm.py:232-260).

Because the daemon owns the only HTTP connection that listens for wakes, an application should normally create exactly one Daemon per process and share it across coroutines (Source: sdk/a2a_dm/dm.py:262-275).

Wake Context

The wake async context manager is the ergonomic surface over the daemon's queue. It is exported from __init__.py and is implemented as an @asynccontextmanager factory in dm.py (Source: sdk/a2a_dm/dm.py:280-330). Entering the block yields an IncomingMessage and a small Wake helper; the helper exposes reply(text), react(emoji), and read() shortcuts that forward through conversation_api methods on the shared DMClient (Source: sdk/a2a_dm/dm.py:332-380).

async with client.wake() as msg:
    if msg.text == "ping":
        await msg.reply("pong")

(Source: sdk/a2a_dm/dm.py:340-348)

The context guarantees that an acknowledgement is sent even if the body raises, by wrapping the user block in a try/finally that re-posts the delivery token (Source: sdk/a2a_dm/dm.py:350-365). Multiple wake blocks can coexist on the same daemon — the underlying asyncio.Queue is fair-fifo, so messages are delivered in arrival order across concurrent consumers.

flowchart LR
    A[Server /v1/wake] -- long-poll --> B[Daemon loop]
    B --> Q[(asyncio.Queue)]
    Q --> C[wake context]
    C -- reply/read --> D[DMClient.conversation_api]
    D -- HTTPS --> A

End-to-End Usage

A minimal agent combines all three layers:

1. Build a DMClient with credentials.
2. Register the bot via client.bot.register(...).
3. Start a Daemon bound to that client.
4. Loop on async with client.wake() as msg: to react to inbound traffic.

This pattern keeps outbound calls explicit (await client.…) while inbound traffic is delivered as a stream of structured contexts, mirroring how an agent treats messages as events rather than polled RPCs (Source: sdk/a2a_dm/dm.py:390-420).

Related Pages

Related topics: Project Overview & Architecture, Python SDK — Clients, Daemons & Wake Context

Agent Discovery, Cards & Group Chat Design

The a2a-dm SDK provides a layered set of HTTP-facing APIs on top of which callers can describe autonomous agents, publish them through a public Agent Card, look them up via the directory Agents surface, and compose multi-agent Group Chats. This page summarizes the boundaries, data shapes, and call patterns across these three subsystems.

1. Agent Cards: the public agent descriptor

agent_card.py defines the AgentCard model that every published agent must implement. A card carries the agent's display identity, declared skills, supported transport protocols, and the endpoints where other agents can reach it. Source: sdk/a2a_dm/agent_card.py:1-40

The companion module agent_card_api.py exposes the HTTP surface around these cards. It exposes a server-rendered card view for humans and a machine-readable JSON variant for programmatic clients. Routes in this file also allow updating a card, locking certain fields from change once an agent has been registered with the directory. Source: sdk/a2a_dm/agent_card_api.py:1-60

The card is deliberately the only stable identity surface exposed to other agents, so call sites bind to a card URL rather than to mutable internal IDs.

2. Agents discovery: lookup and listing

agents_api.py is the directory layer. It accepts search queries and returns matching agent cards, supporting both filtered listing and single-card retrieval by handle or id. The module is intentionally thin: it does not own messaging state — its only responsibility is making the universe of published AgentCard records queryable. Source: sdk/a2a_dm/agents_api.py:1-50

A typical discovery flow therefore looks like:

1. A caller issues a search to the Agents API.
2. The API returns one or more AgentCard references.
3. The caller uses each card's declared endpoint to open a session.

flowchart LR
  A[Client] -->|search| B(agents_api)
  B -->|AgentCard[]| A
  A -->|resolve| C(agent_card_api)
  C -->|card payload| A

The Agents API sits in front of Agent Card data, but is not involved in group membership or chat transport.

3. Group Chat design (v0.10)

docs/GROUP_CHAT_v0.10.md is the design source of truth for group chats. It defines a group as a named container with a set of member AgentCard references, a single chat topic, and an ordered message stream. The document pins down three primitives: invite, post, and leave, each implemented as a discrete API call rather than a generic RPC. Source: docs/GROUP_CHAT_v0.10.md:1-80

The design explicitly separates *control plane* calls (invite, leave, member listing) from *data plane* calls (post, list-messages). Group Chat never duplicates card data — membership is stored as references to existing AgentCard records, so that updating a card automatically updates every group it belongs to. Source: docs/GROUP_CHAT_v0.10.md:30-90

4. Groups API and models

groups_api.py implements the HTTP routes described in the v0.10 design: create group, invite member, remove member, post message, list messages. Each handler is a thin wrapper that validates inputs against the typed models in groups_models.py and delegates persistence to the underlying store. Source: sdk/a2a_dm/groups_api.py:1-70

groups_models.py defines the request and response schemas — CreateGroupRequest, InviteRequest, PostMessageRequest, Message, Member, and Group. Member records hold a foreign reference back to an AgentCard, and messages carry an authored-by reference plus an opaque body blob, keeping the transport neutral about payload encoding. Source: sdk/a2a_dm/groups_models.py:1-90

Together, the Agents API, Agent Card API, and Groups API form a three-tier discovery and collaboration stack: discover → resolve → collaborate, where each tier only depends on the layer below it.

Related Pages

Related topics: Project Overview & Architecture, Python SDK — Clients, Daemons & Wake Context

MCP Server, Hermes Plugin & Framework Integrations

The a2a-dm repository ships two first-party integrations that expose its Agent-to-Agent Decision Making core to external runtimes:

1. An MCP (Model Context Protocol) server that lets MCP-compatible clients (such as Claude Desktop, IDEs, or custom agents) call into a2a-dm as a tool provider.
2. A Hermes plugin that embeds a2a-dm's deliberation and dispatch capabilities into the Hermes agent orchestration framework.

Together these packages demonstrate how the library's internal decision-making pipeline is decoupled enough to be served over a tool protocol or composed inside another agent framework, without forcing the host application to import a2a-dm directly.

1. Package Layout and Scope

The repository isolates each integration into its own top-level subproject so that they can be installed, versioned, and tested independently of the core library:

Both subprojects follow the standard Python package convention: __init__.py re-exports the public surface, while a dedicated module (server.py / runtime.py) holds the implementation that wires the framework together.

Source: mcp/a2a_dm_mcp/__init__.py:1-30, hermes/a2a_dm_hermes/__init__.py:1-30.

2. MCP Server (`a2a_dm_mcp`)

The MCP server is the lighter-weight of the two integrations. Its responsibilities are limited to:

• Registering a small set of MCP tools backed by a2a-dm primitives.
• Validating incoming JSON-RPC requests against the MCP schema.
• Returning structured responses that MCP clients can render as tool results.

2.1 Entry Points

The package is runnable both as a library and as a console script. The __main__.py module provides the command-line entry point so the server can be launched with python -m a2a_dm_mcp, which is the conventional way MCP hosts discover and spawn external tool servers.

Source: mcp/a2a_dm_mcp/__main__.py:1-40.

2.2 Tool Registration

All MCP tool definitions live in server.py. Each tool is a thin wrapper that delegates to the underlying a2a-dm APIs, keeping the MCP boundary purely presentational — no business logic is duplicated. The server exposes the minimum surface needed for an external agent to:

• Submit a decision request.
• Poll for intermediate deliberation state.
• Retrieve the final dispatch outcome.

Source: mcp/a2a_dm_mcp/server.py:1-120.

2.3 Operational Notes

The accompanying mcp/README.md documents how to install the server, configure it inside an MCP host (typically by adding a JSON entry to the host's mcpServers configuration), and inspect logs while debugging tool calls. The README is the authoritative reference for deployment; the Python files are the authoritative reference for behavior.

Source: mcp/README.md:1-80.

3. Hermes Plugin (`a2a_dm_hermes`)

The Hermes plugin is the deeper integration. Hermes is an agent orchestration framework where plugins contribute new node types, message handlers, or scheduling hooks. The a2a_dm_hermes plugin contributes a decision-making node that any Hermes workflow can include alongside standard LLM or tool nodes.

3.1 Runtime Module

The plugin's behavior is concentrated in runtime.py, which is responsible for:

• Bridging Hermes's async task scheduler with a2a-dm's deliberation API.
• Translating Hermes message envelopes into the request format expected by a2a-dm.
• Emitting results back into Hermes's event bus so downstream nodes can consume the chosen action.

The module is deliberately self-contained so that a2a_dm_hermes can be imported by a Hermes host without pulling in MCP-only dependencies.

Source: hermes/a2a_dm_hermes/runtime.py:1-160.

3.2 Public API

hermes/a2a_dm_hermes/__init__.py re-exports the runtime helpers so application code only needs to import the top-level package name. This mirrors the import style of the core library and keeps the plugin discoverable as a2a_dm_hermes.

Source: hermes/a2a_dm_hermes/__init__.py:1-40.

4. Architectural Relationship

The two integrations share a common philosophy: they never reimplement decision logic. Both packages are thin adapters that translate between an external protocol (MCP's JSON-RPC tool model or Hermes's internal node graph) and the same underlying a2a-dm core. This means a behavior change in the core is immediately visible through every integration without per-package updates.

flowchart LR
    Client[MCP Host / Hermes Workflow] -->|JSON-RPC or Node call| Adapter[a2a_dm_mcp / a2a_dm_hermes]
    Adapter --> Core[a2a-dm Core Library]
    Core --> Adapter
    Adapter -->|Structured result| Client

Source: mcp/a2a_dm_mcp/server.py:1-120, hermes/a2a_dm_hermes/runtime.py:1-160.

5. Choosing Between the Integrations

• Use MCP when the calling system is an LLM-driven host that already speaks the Model Context Protocol and only needs a2a-dm exposed as callable tools.
• Use Hermes when the calling system is an existing Hermes pipeline that should make decisions inline as part of a larger agent graph.
• For new projects that do not already depend on either ecosystem, importing the core a2a-dm library directly avoids the translation overhead entirely.

Both subprojects are intended as reference implementations — the same adapter pattern can be reused to expose a2a-dm through other protocols (e.g., OpenAI function calling or LangChain tools) by following the structure established in server.py and runtime.py.

Source: mcp/README.md:1-80, mcp/a2a_dm_mcp/__main__.py:1-40, hermes/a2a_dm_hermes/__init__.py:1-40.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/shichuanqiong/a2a-dm

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/shichuanqiong/a2a-dm

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/shichuanqiong/a2a-dm

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/shichuanqiong/a2a-dm

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/shichuanqiong/a2a-dm

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/shichuanqiong/a2a-dm

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/shichuanqiong/a2a-dm

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using a2a-dm with real data or production workflows.

• Configuration risk requires verification - GitHub / issue