Skip to content

Agent Mesh

bridge: document parts support and the card tool in the agent skill

Tomas Tormoa22cd56a8175
diff --git a/agents/skills/sam-a2a-bridge/SKILL.md b/agents/skills/sam-a2a-bridge/SKILL.md
index 5ba36a6c..daac1db1 100644
--- a/agents/skills/sam-a2a-bridge/SKILL.md
+++ b/agents/skills/sam-a2a-bridge/SKILL.md
@@ -1,18 +1,19 @@
---
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."
+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 (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-sovereignty labels on every call. Also use to set up the sam-a2a-bridge MCP server when those 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
+bridge exposes three 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 tools are not callable yet: [Set Up The Bridge](#set-up-the-bridge).
+- Before sending data or files, check what the agent accepts:
+ [Check Agent Capabilities](#check-agent-capabilities).
- The task needs a remote agent to do something:
[Send A Task](#send-a-task).
- A previous send returned a non-terminal state:
@@ -31,19 +32,45 @@ Propose each shell command and let the user approve it before running anything.
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.
+3. Register it with the harness, passing the sidecar URL, its API token, and
+ the download directory for agent-returned files:
+ `claude mcp add sam-a2a-bridge -- ~/bin/sam-a2a-bridge -url http://localhost:8080 -token <sidecar-token> -download-dir ~/.sam/a2a-downloads`
+ (Files are saved under the download directory; the default is `~/.sam/a2a-downloads` and the user prunes manually.)
+4. 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, required_labels?, context_id?, task_id?)`
+`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.
-- `message` is plain text. The call returns immediately with
- `{"task_id","context_id","state","text"}` — it never blocks on the agent.
+- 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` and `file_name` attach a local file (up to 5 MB). Both must be
+ provided together. The agent receives the file as an attachment.
+- 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.
- **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
@@ -56,7 +83,8 @@ Propose each shell command and let the user approve it before running anything.
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.
+message while running and its answer or artifacts when completed. `data` and
+`files` appear only when present.
## Multi-Turn