Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
docs: add the chat-a2a use case page and wire GEMINI_MODEL through the example
Tomas Tormo69cbe36a4d66
diff --git a/development/examples/chat-a2a/Dockerfile b/development/examples/chat-a2a/Dockerfileindex 2e474c2b..57f1fdb2 100644--- a/development/examples/chat-a2a/Dockerfile+++ b/development/examples/chat-a2a/Dockerfile@@ -6,5 +6,6 @@ RUN pip install --no-cache-dir -r requirements.txtCOPY agent.py /srv/ENV GEMINI_API_KEY=<API_KEY>+ENV GEMINI_MODEL=models/gemini-3.5-flash-liteCMD ["python3", "/srv/agent.py"]diff --git a/development/examples/chat-a2a/README.md b/development/examples/chat-a2a/README.mdindex f98cdc77..5d989f61 100644--- a/development/examples/chat-a2a/README.md+++ b/development/examples/chat-a2a/README.md@@ -8,7 +8,7 @@ routing over libp2p, and `contextId` continuity across turns.Edit `Dockerfile` and replace `<API_KEY>` in `ENV GEMINI_API_KEY=<API_KEY>`(same pattern as `gemini-buddy-mcp`). Optionally override the model with-`GEMINI_MODEL` (default `models/gemini-3.6-flash`).+`GEMINI_MODEL` (default `models/gemini-3.5-flash-lite`).## 2. Host the agent on a mesh node@@ -60,6 +60,7 @@ a stock A2A client work against the mesh unmodified.Requires [`uv`](https://docs.astral.sh/uv/).```sh+cd development/examples/chat-a2auv run --with-requirements requirements.txt chat.py "http://127.0.0.1:9099/sam/$PEER/a2a/chat"```diff --git a/site/content/docs/use-cases/chat-a2a.md b/site/content/docs/use-cases/chat-a2a.mdnew file mode 100644index 00000000..accb519e--- /dev/null+++ b/site/content/docs/use-cases/chat-a2a.md@@ -0,0 +1,147 @@+---+title: "A2A Chat"+linkTitle: "A2A Chat"+weight: 30+---++Hold a multi-turn conversation with an [A2A](https://a2a-protocol.org/)+(Agent2Agent) agent hosted on a remote mesh node — using a **stock,+unmodified `a2a-sdk` client**. No SAM-specific client code: the mesh's+agent-card rewrite makes the standard SDK work as-is.++Source: [`development/examples/chat-a2a/`](https://github.com/google/sam/tree/main/development/examples/chat-a2a).++## The idea++A2A is the mesh's southbound agent-to-agent wire: an agent process speaking+A2A over HTTP registers on its node as a `type: a2a` service, and remote+peers reach it through the raw egress path+`/sam/{peer}/a2a/{service}/...` (see+[A2A Service Routing](../../user/node-configuration/#a2a-service-routing)).++The problem with proxying A2A naively is the **agent card**. A2A clients+bootstrap from `/.well-known/agent-card.json`, and the card contains the+agent's own interface URLs — addresses that are only reachable on the+provider's machine. A stock client would fetch the card through the mesh,+then try to talk to `http://127.0.0.1:7777/` and fail.++So the caller's node rewrites the card **in transit**: interface URLs are+pointed back at the mesh path the client fetched from, transports the mesh+cannot carry (gRPC needs its own end-to-end connection) are dropped, and+streaming is advertised off. The client follows the rewritten URLs like it+would for any A2A server — discovery, JSON-RPC `message/send`, and+`contextId` round-tripping all work unmodified, while the traffic actually+flows over libp2p between the nodes.++This example proves both halves:++- **Card rewrite** — the bundled REPL is a plain `a2a-sdk` client; it works+ only because the rewritten card sends it back through the mesh.+- **Conversation continuity** — the agent keeps one Gemini chat session per+ A2A `contextId`. Tell it your name, ask for it back two turns later: the+ answer shows the context survived the mesh hop. Each turn is still its own+ short-lived A2A **task** (`taskId` changes every turn, created and+ completed by each `message/send`); `contextId` is what persists and groups+ them into one conversation.++## The pieces++- **`chat` service** (`agent.py`) — a Gemini-backed A2A agent built on the+ Python `a2a-sdk`: serves its agent card, answers `message/send`, and holds+ history server-side, one Gemini chat session per `contextId`. The node+ proxies to it via `target_url`; the agent itself knows nothing about SAM.+- **REPL client** (`chat.py`) — a ~40-line stock `a2a-sdk` client: resolves+ the card through the mesh, then loops `input()` → `message/send`, echoing+ the `contextId` the server minted on the first reply.++## What you can do with it++- **Bring any A2A agent onto the mesh unchanged** — the example agent is+ deliberately vanilla `a2a-sdk`; anything speaking A2A over HTTP (ADK,+ LangGraph, a hosted agent) plugs in the same way, one `target_url` line in+ the node config.+- **Use any stock A2A client** — `chat.py` is just the smallest one. The+ rewritten card means SDKs, CLIs, and other agents resolve and call the+ service without knowing SAM exists.+- **Let the agent own the conversation** — the same pattern as+ [Gemini Buddy](../gemini-buddy/), but on the standard A2A wire instead of a+ custom MCP tool: state lives with the agent, keyed by `contextId`, and+ callers only ever send the next message.++## Try it on kind++The repository ships a [kind](https://kind.sigs.k8s.io/)-based local mesh+that brings the agent up with one command.++### 1. Set a Gemini key for the agent image++`agent.py` calls Gemini, so set your API key on the `ENV GEMINI_API_KEY`+line in `development/examples/chat-a2a/Dockerfile` before building (a free+Google AI Studio key is fine for the demo).++### 2. Mesh layout++Host the agent on one node in `development/kind/mesh-config.yaml`:++```yaml+node-a: # bare node+node-b: chat-a2a # the A2A agent+```++### 3. Bring the mesh up and enroll a local caller node++```bash+make build # builds ./bin/sam-node (once)+make kind-up # control plane + router + agent (node-b)+make kind-local-node # local sam-node enrolled in the mesh — LEAVE RUNNING+```++The local node is your entry point: its sidecar API listens on+**`http://127.0.0.1:9099`** (bearer token `devtoken`), MCP tools at `/mcp`.++### 4. Find the provider peer++```bash+./bin/mcp-client -url http://127.0.0.1:9099/mcp -token devtoken \+ -tool discover_remote_services -args '{"type":"a2a","name":"chat"}'+```++Note the peer ID and export it as `PEER`. Discovery is gossip-fed; retry for+a few seconds after startup if the list comes back empty.++### 5. Watch the card rewrite happen++Fetch the agent card through the mesh with nothing but `curl`:++```bash+curl -s -H 'X-Sam-Authentication: Bearer devtoken' \+ "http://127.0.0.1:9099/sam/$PEER/a2a/chat/.well-known/agent-card.json" | jq+```++The interface URLs in the response point back at this+`/sam/{peer}/a2a/chat` path — not at the agent's own `127.0.0.1:7777` — and+`capabilities.streaming` is `false`. That rewrite is the whole trick.++### 6. Chat++Requires [`uv`](https://docs.astral.sh/uv/).++```bash+cd development/examples/chat-a2a+uv run --with-requirements requirements.txt chat.py \+ "http://127.0.0.1:9099/sam/$PEER/a2a/chat"+```++Prove the continuity: introduce yourself in one turn, chat about something+else, then ask the agent what your name is. It answers from its own+server-side session — the client never re-sent the history, only the+`contextId`.++## Configuration++| var | default | used by |+|-----|---------|---------|+| `GEMINI_API_KEY` | *(placeholder — set in the Dockerfile)* | agent |+| `GEMINI_MODEL` | `models/gemini-3.5-flash-lite` *(set in the Dockerfile)* | agent |++The listen port (`7777`) is a constant at the top of `agent.py`.diff --git a/site/content/docs/user/node-configuration.md b/site/content/docs/user/node-configuration.mdindex fb74fd8b..413a6ddb 100644--- a/site/content/docs/user/node-configuration.md+++ b/site/content/docs/user/node-configuration.md@@ -75,6 +75,7 @@ When configuring `type: a2a` services (Agent2Agent protocol agents):* **URL backends only**: register the agent's local HTTP endpoint as `target_url`. `command` backends are rejected.* **Raw Proxy Access**: remote peers reach the agent at `http://localhost:8080/sam/{peer}/a2a/{service}/...`. The agent card served at `.../.well-known/agent-card.json` is rewritten in transit so its interface URLs point back at this mesh path; transports the mesh cannot carry (gRPC) are dropped and streaming is advertised off.* **Label-gated egress**: setting `X-Sam-Required-Labels: key=value[,key=value]` on a raw a2a request makes the caller's node verify the provider's control-plane-attested labels and refuse fail-closed (HTTP 403) before any data leaves the node. The header is stripped before forwarding.+* **Runnable example**: the [A2A Chat use case](../../use-cases/chat-a2a/) walks through hosting an a2a agent on a kind mesh and talking to it with a stock `a2a-sdk` client.---