SAM A2A Bridge Skill
Use this skill to delegate work to A2A agents hosted by SAM mesh peers. The
bridge exposes three tools; everything else (auth, routing, the labels
gate) happens inside the local sam-node.
Pick the path that matches the need:
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.
- 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.
- Build the bridge (own Go module; the Makefile pins the Go toolchain the
module needs, so a stale system Go still works):
make -C <sam-repo>/cmd/sam-a2a-bridge build
- Register it with the harness, passing the sidecar URL and its API token:
claude mcp add sam-a2a-bridge -- <sam-repo>/bin/sam-a2a-bridge -url http://localhost:8080 -token <sidecar-token>
(Agent-returned files land in ~/.sam/a2a-downloads by default, auto-created; pass -download-dir to change it — you must create that directory yourself. No auto-cleanup; prune manually.)
- Restart the harness session; the three tools appear.
Check Agent Capabilities
get_agent_card(peer, service)
Call this before composing structured data or file attachments to verify what
the agent accepts. Returns a trimmed card including:
- Registered skills with examples
default_input_modes — accepted MIME types for structured data (e.g.,
application/json)
default_output_modes — MIME types the agent can return
- Whether the agent supports streaming
Use the capabilities to shape your data (JSON object matching the agent's
input schema) and file_path attachments appropriately.
Send A Task
send_agent_task(peer, service, message?, data?, file_path?, file_name?, 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.
- At least one of
message, data, or file_path is required. All are combinable.
message is plain text.
data is a JSON object; it becomes a DataPart and routes to the agent's
structured-input handler. Check default_input_modes first.
file_path attaches a local file (up to 5 MB); file_name optionally
renames what the agent sees (default: the file's base name).
- The call returns immediately with
{"task_id", "context_id", "state", "text", "data"?, "files"?} — it never blocks on the agent.
data (optional) contains structured JSON returned inline.
files (optional) is a list of paths where agent-returned files are saved
under the download directory.
- Data residency: 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. data and
files appear only when present.
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 label 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.
- Interop note: the remote agent must run a2a-go v2.x; older A2A stacks speak
a different JSON-RPC dialect and will not answer.
1---2name: sam-a2a-bridge3description: "Use when the task should be delegated to a remote A2A agent on the SAM agent mesh: send it work with send_agent_task (with text, structured data, or file attachments), check agent capabilities with get_agent_card, poll results with get_agent_task, hold multi-turn conversations, and enforce data-residency labels on every call. Also use to set up the sam-a2a-bridge MCP server when those tools are not callable yet."4metadata:5 source: https://skillmd.com/skills/google/sam-a2a-bridge6---78# SAM A2A Bridge Skill910Use this skill to delegate work to A2A agents hosted by SAM mesh peers. The11bridge exposes three tools; everything else (auth, routing, the labels12gate) happens inside the local `sam-node`.1314Pick the path that matches the need:1516- The tools are not callable yet: [Set Up The Bridge](#set-up-the-bridge).17- Before sending data or files, check what the agent accepts:18 [Check Agent Capabilities](#check-agent-capabilities).19- The task needs a remote agent to do something:20 [Send A Task](#send-a-task).21- A previous send returned a non-terminal state:22 [Poll A Task](#poll-a-task).23- The conversation with the agent continues:24 [Multi-Turn](#multi-turn).25- A call failed: [Interpret Errors](#interpret-errors).2627## Set Up The Bridge2829The bridge is a stdio MCP server that talks to the local `sam-node` sidecar.30Propose each shell command and let the user approve it before running anything.31321. A running, enrolled `sam-node` is required first. If its sidecar does not33 answer on `http://localhost:8080`, use the `sam-mesh` skill's bootstrap34 path before continuing.352. Build the bridge (own Go module; the Makefile pins the Go toolchain the36 module needs, so a stale system Go still works):37 `make -C <sam-repo>/cmd/sam-a2a-bridge build`383. Register it with the harness, passing the sidecar URL and its API token:39 `claude mcp add sam-a2a-bridge -- <sam-repo>/bin/sam-a2a-bridge -url http://localhost:8080 -token <sidecar-token>`40 (Agent-returned files land in `~/.sam/a2a-downloads` by default, auto-created; pass `-download-dir` to change it — you must create that directory yourself. No auto-cleanup; prune manually.)414. Restart the harness session; the three tools appear.4243## Check Agent Capabilities4445`get_agent_card(peer, service)`4647Call this before composing structured data or file attachments to verify what48the agent accepts. Returns a trimmed card including:49- Registered skills with examples50- `default_input_modes` — accepted MIME types for structured data (e.g.,51 `application/json`)52- `default_output_modes` — MIME types the agent can return53- Whether the agent supports streaming5455Use the capabilities to shape your `data` (JSON object matching the agent's56input schema) and `file_path` attachments appropriately.5758## Send A Task5960`send_agent_task(peer, service, message?, data?, file_path?, file_name?, required_labels?, context_id?, task_id?)`6162- `peer` is the provider node's peer ID; `service` is the a2a service name it63 registered. If unknown, discover them with the `sam-node` MCP tool64 `discover_remote_services` with `type: a2a`, or ask the user.65- At least one of `message`, `data`, or `file_path` is required. All are combinable.66 - `message` is plain text.67 - `data` is a JSON object; it becomes a DataPart and routes to the agent's68 structured-input handler. Check `default_input_modes` first.69 - `file_path` attaches a local file (up to 5 MB); `file_name` optionally70 renames what the agent sees (default: the file's base name).71- The call returns immediately with `{"task_id", "context_id", "state", "text",72 "data"?, "files"?}` — it never blocks on the agent.73 - `data` (optional) contains structured JSON returned inline.74 - `files` (optional) is a list of paths where agent-returned files are saved75 under the download directory.76- **Data residency**: when the task involves data that must stay in a region or77 jurisdiction, set `required_labels` (comma-separated `key=value`, e.g.78 `region=eu-west-1`). The local node then refuses fail-closed before any data79 leaves it unless the peer's control-plane-attested labels match. Never drop80 or weaken `required_labels` to make a refused call succeed without the81 user's explicit approval — the refusal is the feature.8283## Poll A Task8485If `state` is not terminal (`completed`, `failed`, `canceled`, `rejected`),86poll with `get_agent_task(peer, service, task_id)` until it is. Space polls a87few seconds apart; agent tasks can be slow. `text` carries the agent's status88message while running and its answer or artifacts when completed. `data` and89`files` appear only when present.9091## Multi-Turn9293- Follow-up question in the same conversation: pass the returned `context_id`94 on the next `send_agent_task`. Without it every message is a cold start.95- The task is in state `input-required` (the agent asked something): answer by96 passing BOTH `task_id` and `context_id` — that routes the reply into the97 waiting task so it can finish. Terminal tasks cannot receive messages.9899## Interpret Errors100101- `403: Required labels not attested by provider` — the label gate102 refused before egress. Expected for non-matching regions; report it to the103 user, do not retry with weaker labels on your own.104- `400: Invalid X-Sam-Required-Labels header ...` — malformed labels; fix the105 `key=value,key=value` syntax.106- `404` / `Service not found` — the peer has no a2a service by that name;107 re-discover or check the name with the user.108- Connection refused / timeout — the local sidecar URL or token is wrong, or109 the node is down; go to [Set Up The Bridge](#set-up-the-bridge).110- Interop note: the remote agent must run a2a-go v2.x; older A2A stacks speak111 a different JSON-RPC dialect and will not answer.