Skip to content

Agent Mesh

bridge: add a trimmed get_agent_card tool

Tomas Tormo51fd049130b9
diff --git a/cmd/sam-a2a-bridge/a2a.go b/cmd/sam-a2a-bridge/a2a.go
index 1f18aad9..ea57ab89 100644
--- a/cmd/sam-a2a-bridge/a2a.go
+++ b/cmd/sam-a2a-bridge/a2a.go
@@ -16,6 +16,7 @@ package main
import (
"context"
+ "encoding/json"
"errors"
"fmt"
"mime"
@@ -274,3 +275,70 @@ func saveFilePart(dir, taskID, name string, data []byte) (string, error) {
}
return path, nil
}
+
+type getAgentCardParams struct {
+ Peer string `json:"peer" jsonschema:"Peer ID of the node hosting the agent"`
+ Service string `json:"service" jsonschema:"Name of the a2a service registered on that peer"`
+}
+
+// agentCardSummary trims the agent card to what a model can use; full cards
+// carry security schemas and provider blurbs a model never needs.
+type agentCardSummary struct {
+ Name string `json:"name"`
+ Description string `json:"description,omitempty"`
+ Version string `json:"version,omitempty"`
+ DefaultInputModes []string `json:"default_input_modes,omitempty"`
+ DefaultOutputModes []string `json:"default_output_modes,omitempty"`
+ Streaming bool `json:"streaming"`
+ Skills []agentCardSkill `json:"skills,omitempty"`
+}
+
+type agentCardSkill struct {
+ ID string `json:"id"`
+ Name string `json:"name,omitempty"`
+ Description string `json:"description,omitempty"`
+ Tags []string `json:"tags,omitempty"`
+ Examples []string `json:"examples,omitempty"`
+}
+
+func getAgentCard(ctx context.Context, cfg bridgeConfig, p getAgentCardParams) (agentCardSummary, error) {
+ httpClient := &http.Client{
+ Timeout: 30 * time.Second,
+ Transport: &samTransport{base: http.DefaultTransport, token: cfg.token},
+ }
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet,
+ cfg.meshURL(p.Peer, p.Service)+"/.well-known/agent-card.json", nil)
+ if err != nil {
+ return agentCardSummary{}, err
+ }
+ resp, err := httpClient.Do(req)
+ if err != nil {
+ return agentCardSummary{}, err
+ }
+ defer func() { _ = resp.Body.Close() }()
+
+ // Wire keys match a2a-go v2.5.0's a2a.AgentCard/AgentCapabilities/AgentSkill json tags exactly.
+ var wire struct {
+ Name string `json:"name"`
+ Description string `json:"description"`
+ Version string `json:"version"`
+ DefaultInputModes []string `json:"defaultInputModes"`
+ DefaultOutputModes []string `json:"defaultOutputModes"`
+ Capabilities struct {
+ Streaming bool `json:"streaming"`
+ } `json:"capabilities"`
+ Skills []agentCardSkill `json:"skills"`
+ }
+ if err := json.NewDecoder(resp.Body).Decode(&wire); err != nil {
+ return agentCardSummary{}, fmt.Errorf("agent card is not valid JSON: %w", err)
+ }
+ return agentCardSummary{
+ Name: wire.Name,
+ Description: wire.Description,
+ Version: wire.Version,
+ DefaultInputModes: wire.DefaultInputModes,
+ DefaultOutputModes: wire.DefaultOutputModes,
+ Streaming: wire.Capabilities.Streaming,
+ Skills: wire.Skills,
+ }, nil
+}
diff --git a/cmd/sam-a2a-bridge/a2a_test.go b/cmd/sam-a2a-bridge/a2a_test.go
index b0460019..dd702600 100644
--- a/cmd/sam-a2a-bridge/a2a_test.go
+++ b/cmd/sam-a2a-bridge/a2a_test.go
@@ -313,3 +313,43 @@ func TestResultIncludesFileURIs(t *testing.T) {
t.Fatalf("URI file part must pass through as-is: %v", got.Files)
}
}
+
+func TestGetAgentCardTrims(t *testing.T) {
+ card := `{"name":"echo-agent","description":"echoes","version":"1.2.0",` +
+ `"defaultInputModes":["text/plain","application/pdf"],"defaultOutputModes":["text/plain"],` +
+ `"capabilities":{"streaming":false,"pushNotifications":true},` +
+ `"securitySchemes":{"oauth":{"type":"oauth2"}},"provider":{"organization":"acme"},` +
+ `"skills":[{"id":"echo","name":"Echo","description":"repeats input",` +
+ `"tags":["test"],"examples":["say hi"]}]}`
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet || !strings.HasSuffix(r.URL.Path, "/.well-known/agent-card.json") {
+ http.Error(w, "not found", http.StatusNotFound)
+ return
+ }
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(card))
+ }))
+ defer srv.Close()
+
+ got, err := getAgentCard(context.Background(), bridgeConfig{sidecarURL: srv.URL},
+ getAgentCardParams{Peer: "12D3KooWpeer", Service: "echo"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if got.Name != "echo-agent" || got.Version != "1.2.0" {
+ t.Errorf("identity fields: %+v", got)
+ }
+ if len(got.Skills) != 1 || got.Skills[0].ID != "echo" || got.Skills[0].Examples[0] != "say hi" {
+ t.Errorf("skills not carried: %+v", got.Skills)
+ }
+ if len(got.DefaultInputModes) != 2 {
+ t.Errorf("input modes not carried: %+v", got.DefaultInputModes)
+ }
+ if got.Streaming {
+ t.Error("streaming must reflect the card (false)")
+ }
+ raw, _ := json.Marshal(got)
+ if strings.Contains(string(raw), "oauth") || strings.Contains(string(raw), "acme") {
+ t.Fatalf("trim failed, security/provider material leaked: %s", raw)
+ }
+}
diff --git a/cmd/sam-a2a-bridge/main.go b/cmd/sam-a2a-bridge/main.go
index fc54f26f..53254bd4 100644
--- a/cmd/sam-a2a-bridge/main.go
+++ b/cmd/sam-a2a-bridge/main.go
@@ -59,17 +59,26 @@ func newBridgeServer(cfg bridgeConfig) *mcp.Server {
mcp.AddTool(server, &mcp.Tool{
Name: "send_agent_task",
- Description: "Send a text message to an A2A agent on the SAM mesh. Returns immediately with " +
- "{task_id, context_id, state, text}; poll non-terminal states with get_agent_task. " +
- "Pass context_id to continue a conversation, task_id to reply into a task waiting for input. " +
- "required_labels makes the local node refuse fail-closed unless the provider attested them.",
+ Description: "Send a message to an A2A agent on the SAM mesh: plain text (message), structured JSON " +
+ "(data), and/or a local file attachment (file_path, max 5 MB) — at least one required. Returns " +
+ "immediately with {task_id, context_id, state, text, data?, files?}; received files are saved to " +
+ "disk and returned as paths. Poll non-terminal states with get_agent_task. Pass context_id to " +
+ "continue a conversation, task_id to reply into a task waiting for input. required_labels makes " +
+ "the local node refuse fail-closed unless the provider attested them.",
}, handleSendAgentTask(cfg))
mcp.AddTool(server, &mcp.Tool{
- Name: "get_agent_task",
- Description: "Fetch the current state and output of a task previously created with send_agent_task.",
+ Name: "get_agent_task",
+ Description: "Fetch the current state and output of a task previously created with send_agent_task; " +
+ "same result shape, including data and files.",
}, handleGetAgentTask(cfg))
+ mcp.AddTool(server, &mcp.Tool{
+ Name: "get_agent_card",
+ Description: "Fetch a mesh agent's card, trimmed to essentials: skills with examples, accepted " +
+ "input/output MIME types, and streaming support. Use before composing data/file sends.",
+ }, handleGetAgentCard(cfg))
+
return server
}
@@ -87,6 +96,13 @@ func handleGetAgentTask(cfg bridgeConfig) func(context.Context, *mcp.CallToolReq
}
}
+func handleGetAgentCard(cfg bridgeConfig) func(context.Context, *mcp.CallToolRequest, getAgentCardParams) (*mcp.CallToolResult, any, error) {
+ return func(ctx context.Context, _ *mcp.CallToolRequest, p getAgentCardParams) (*mcp.CallToolResult, any, error) {
+ res, err := getAgentCard(ctx, cfg, p)
+ return toolResult(res, err)
+ }
+}
+
// toolResult renders errors as tool errors (not protocol errors) so the
// harness model sees refusal text like the labels-gate 403 verbatim.
func toolResult(res any, err error) (*mcp.CallToolResult, any, error) {
diff --git a/cmd/sam-a2a-bridge/main_test.go b/cmd/sam-a2a-bridge/main_test.go
index d88693e2..b7e38c26 100644
--- a/cmd/sam-a2a-bridge/main_test.go
+++ b/cmd/sam-a2a-bridge/main_test.go
@@ -107,3 +107,23 @@ func TestNewBridgeServerConstructs(t *testing.T) {
t.Fatal("newBridgeServer returned nil")
}
}
+
+func TestHandleGetAgentCard(t *testing.T) {
+ srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+ w.Header().Set("Content-Type", "application/json")
+ _, _ = w.Write([]byte(`{"name":"echo-agent","capabilities":{"streaming":true},"skills":[]}`))
+ }))
+ defer srv.Close()
+
+ res, _, err := handleGetAgentCard(bridgeConfig{sidecarURL: srv.URL})(
+ context.Background(), nil, getAgentCardParams{Peer: "12D3KooWpeer", Service: "echo"})
+ if err != nil {
+ t.Fatal(err)
+ }
+ if res.IsError {
+ t.Fatalf("unexpected tool error: %s", textContent(t, res))
+ }
+ if !strings.Contains(textContent(t, res), `"echo-agent"`) {
+ t.Errorf("card summary missing: %s", textContent(t, res))
+ }
+}