Agent Mesh
Go a2aa2a-protocolagent-meshagentic-aiinferencemcpmeshmesh-networknetwork-securitynetworking-aip2p-network
bridge: add the sam-a2a-bridge agent skill
Tomas Tormo26f0687aa3b9
diff --git a/agents/skills/sam-a2a-bridge/SKILL.md b/agents/skills/sam-a2a-bridge/SKILL.mdnew file mode 100644index 00000000..5ba36a6c--- /dev/null+++ b/agents/skills/sam-a2a-bridge/SKILL.md@@ -0,0 +1,81 @@+---+name: sam-a2a-bridge+description: "Use when the task should be delegated to a remote A2A agent on the SAM (Sovereign Agent Mesh) network: send it work with send_agent_task, poll results with get_agent_task, hold multi-turn conversations, and enforce data-sovereignty labels on every call. Also use to set up the sam-a2a-bridge MCP server when those two tools are not callable yet."+---++# SAM A2A Bridge Skill++Use this skill to delegate work to A2A agents hosted by SAM mesh peers. The+bridge exposes exactly two tools; everything else (auth, routing, the labels+gate) happens inside the local `sam-node`.++Pick the path that matches the need:++- `send_agent_task` / `get_agent_task` are not callable yet:+ [Set Up The Bridge](#set-up-the-bridge).+- The task needs a remote agent to do something:+ [Send A Task](#send-a-task).+- A previous send returned a non-terminal state:+ [Poll A Task](#poll-a-task).+- The conversation with the agent continues:+ [Multi-Turn](#multi-turn).+- A call failed: [Interpret Errors](#interpret-errors).++## Set Up The Bridge++The bridge is a stdio MCP server that talks to the local `sam-node` sidecar.+Propose each shell command and let the user approve it before running anything.++1. A running, enrolled `sam-node` is required first. If its sidecar does not+ answer on `http://localhost:8080`, use the `sam-mesh` skill's bootstrap+ path before continuing.+2. Build the bridge (own Go module, Go >= 1.25):+ `cd <sam-repo>/cmd/sam-a2a-bridge && go build -o ~/bin/sam-a2a-bridge .`+3. Register it with the harness, passing the sidecar URL and its API token:+ `claude mcp add sam-a2a-bridge -- ~/bin/sam-a2a-bridge -url http://localhost:8080 -token <sidecar-token>`+4. Restart the harness session; the two tools appear.++## Send A Task++`send_agent_task(peer, service, message, required_labels?, context_id?, task_id?)`++- `peer` is the provider node's peer ID; `service` is the a2a service name it+ registered. If unknown, discover them with the `sam-node` MCP tool+ `discover_remote_services` with `type: a2a`, or ask the user.+- `message` is plain text. The call returns immediately with+ `{"task_id","context_id","state","text"}` — it never blocks on the agent.+- **Sovereignty**: when the task involves data that must stay in a region or+ jurisdiction, set `required_labels` (comma-separated `key=value`, e.g.+ `region=eu-west-1`). The local node then refuses fail-closed before any data+ leaves it unless the peer's control-plane-attested labels match. Never drop+ or weaken `required_labels` to make a refused call succeed without the+ user's explicit approval — the refusal is the feature.++## Poll A Task++If `state` is not terminal (`completed`, `failed`, `canceled`, `rejected`),+poll with `get_agent_task(peer, service, task_id)` until it is. Space polls a+few seconds apart; agent tasks can be slow. `text` carries the agent's status+message while running and its answer or artifacts when completed.++## Multi-Turn++- Follow-up question in the same conversation: pass the returned `context_id`+ on the next `send_agent_task`. Without it every message is a cold start.+- The task is in state `input-required` (the agent asked something): answer by+ passing BOTH `task_id` and `context_id` — that routes the reply into the+ waiting task so it can finish. Terminal tasks cannot receive messages.++## Interpret Errors++- `403: Required labels not attested by provider` — the sovereignty gate+ refused before egress. Expected for non-matching regions; report it to the+ user, do not retry with weaker labels on your own.+- `400: Invalid X-Sam-Required-Labels header ...` — malformed labels; fix the+ `key=value,key=value` syntax.+- `404` / `Service not found` — the peer has no a2a service by that name;+ re-discover or check the name with the user.+- Connection refused / timeout — the local sidecar URL or token is wrong, or+ the node is down; go to [Set Up The Bridge](#set-up-the-bridge).+- Interop note: the remote agent must run a2a-go v2.x; older A2A stacks speak+ a different JSON-RPC dialect and will not answer.