# https://github.com/shichuanqiong/a2a-dm Project Manual

Generated at: 2026-07-13 23:46:15 UTC

## Table of Contents

- [Project Overview & Architecture](#page-1)
- [Python SDK — Clients, Daemons & Wake Context](#page-2)
- [Agent Discovery, Cards & Group Chat Design](#page-3)
- [MCP Server, Hermes Plugin & Framework Integrations](#page-4)

<a id='page-1'></a>

## Project Overview & Architecture

### Related Pages

Related topics: [Python SDK — Clients, Daemons & Wake Context](#page-2), [Agent Discovery, Cards & Group Chat Design](#page-3), [MCP Server, Hermes Plugin & Framework Integrations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/shichuanqiong/a2a-dm/blob/main/README.md)
- [sdk/README.md](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/README.md)
- [mcp/README.md](https://github.com/shichuanqiong/a2a-dm/blob/main/mcp/README.md)
- [hermes/README.md](https://github.com/shichuanqiong/a2a-dm/blob/main/hermes/README.md)
- [landing/README.md](https://github.com/shichuanqiong/a2a-dm/blob/main/landing/README.md)
</details>

# 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]()

| Directory | Role | Primary Audience |
|-----------|------|------------------|
| `sdk/` | Developer toolkit for constructing agents and clients | Agent authors, integrators |
| `mcp/` | Model Context Protocol adapter and server tooling | Tooling providers, model runtime hosts |
| `hermes/` | Messaging runtime that brokers agent-to-agent traffic | Platform operators, runtime engineers |
| `landing/` | Static documentation and marketing site | End users, evaluators |

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]()

```mermaid
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]()

---

<a id='page-2'></a>

## Python SDK — Clients, Daemons & Wake Context

### Related Pages

Related topics: [Project Overview & Architecture](#page-1), [Agent Discovery, Cards & Group Chat Design](#page-3), [MCP Server, Hermes Plugin & Framework Integrations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [sdk/a2a_dm/__init__.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/__init__.py)
- [sdk/a2a_dm/client.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/client.py)
- [sdk/a2a_dm/dm.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/dm.py)
- [sdk/a2a_dm/bot_api.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/bot_api.py)
- [sdk/a2a_dm/friends_api.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/friends_api.py)
- [sdk/a2a_dm/conversations_api.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/conversations_api.py)
</details>

# 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]()`).

| Mixin file | Resource | Key methods |
|---|---|---|
| `bot_api.py` | Self / bot profile | `register`, `me`, `update_profile`, `set_webhook` (`Source: [sdk/a2a_dm/bot_api.py:20-95]()`) |
| `friends_api.py` | Social graph | `add`, `remove`, `list`, `accept`, `block` (`Source: [sdk/a2a_dm/friends_api.py:18-110]()`) |
| `conversations_api.py` | Message threads | `create`, `send`, `list_messages`, `mark_read`, `close` (`Source: [sdk/a2a_dm/conversations_api.py:22-140]()`) |

A typical outbound call therefore looks like:

```python
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]()`).

```python
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.

```mermaid
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]()`).

---

<a id='page-3'></a>

## Agent Discovery, Cards & Group Chat Design

### Related Pages

Related topics: [Project Overview & Architecture](#page-1), [Python SDK — Clients, Daemons & Wake Context](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [sdk/a2a_dm/agent_card.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/agent_card.py)
- [sdk/a2a_dm/agent_card_api.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/agent_card_api.py)
- [sdk/a2a_dm/agents_api.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/agents_api.py)
- [sdk/a2a_dm/groups_api.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/groups_api.py)
- [sdk/a2a_dm/groups_models.py](https://github.com/shichuanqiong/a2a-dm/blob/main/sdk/a2a_dm/groups_models.py)
- [docs/GROUP_CHAT_v0.10.md](https://github.com/shichuanqiong/a2a-dm/blob/main/docs/GROUP_CHAT_v0.10.md)
</details>

# 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.

```mermaid
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]()`

| Endpoint | Module | Purpose |
|----------|--------|---------|
| `GET /agents` | `agents_api.py` | List / search cards |
| `GET /agent_cards/{id}` | `agent_card_api.py` | Fetch a card |
| `POST /groups` | `groups_api.py` | Create a group |
| `POST /groups/{id}/messages` | `groups_api.py` | Post a message |

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.

---

<a id='page-4'></a>

## MCP Server, Hermes Plugin & Framework Integrations

### Related Pages

Related topics: [Project Overview & Architecture](#page-1), [Python SDK — Clients, Daemons & Wake Context](#page-2)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [mcp/a2a_dm_mcp/__init__.py](https://github.com/shichuanqiong/a2a-dm/blob/main/mcp/a2a_dm_mcp/__init__.py)
- [mcp/a2a_dm_mcp/__main__.py](https://github.com/shichuanqiong/a2a-dm/blob/main/mcp/a2a_dm_mcp/__main__.py)
- [mcp/a2a_dm_mcp/server.py](https://github.com/shichuanqiong/a2a-dm/blob/main/mcp/a2a_dm_mcp/server.py)
- [mcp/README.md](https://github.com/shichuanqiong/a2a-dm/blob/main/mcp/README.md)
- [hermes/a2a_dm_hermes/__init__.py](https://github.com/shichuanqiong/a2a-dm/blob/main/hermes/a2a_dm_hermes/__init__.py)
- [hermes/a2a_dm_hermes/runtime.py](https://github.com/shichuanqiong/a2a-dm/blob/main/hermes/a2a_dm_hermes/runtime.py)
</details>

# 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:

| Subproject | Path | Role |
| --- | --- | --- |
| MCP server | `mcp/a2a_dm_mcp/` | Standalone MCP server exposing `a2a-dm` tools |
| Hermes plugin | `hermes/a2a_dm_hermes/` | Drop-in plugin for the Hermes runtime |

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.

```mermaid
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]().

---

<!-- evidence_pipeline_checked: true -->

---

## Pitfall Log

Project: shichuanqiong/a2a-dm

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/shichuanqiong/a2a-dm

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/shichuanqiong/a2a-dm

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/shichuanqiong/a2a-dm

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/shichuanqiong/a2a-dm

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/shichuanqiong/a2a-dm

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/shichuanqiong/a2a-dm

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/shichuanqiong/a2a-dm

<!-- canonical_name: shichuanqiong/a2a-dm; human_manual_source: deepwiki_human_wiki -->