Merge pull request #1049 from dgageot/a2a-tools

Support remote a2a tool

Author: dgageot

cagent-schema.json

@@ -351,7 +351,8 @@
             "shell",
             "todo",
             "fetch",
-            "api"
+            "api",
+            "a2a"
           ]
         },
         "instruction": {
@@ -457,6 +458,15 @@
           "type": "integer",
           "description": "Timeout in seconds for the fetch tool",
           "minimum": 1
+        },
+        "url": {
+          "type": "string",
+          "description": "URL for the a2a tool",
+          "format": "uri"
+        },
+        "name": {
+          "type": "string",
+          "description": "Name for the a2a tool"
         }
       },
       "additionalProperties": false,
@@ -521,6 +531,22 @@
               ]
             }
           ]
+        },
+        {
+          "allOf": [
+            {
+              "properties": {
+                "type": {
+                  "const": "a2a"
+                }
+              }
+            },
+            {
+              "required": [
+                "url"
+              ]
+            }
+          ]
         }
       ]
     },

cmd/root/a2a.go

@@ -6,6 +6,7 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/docker/cagent/pkg/a2a"
+	"github.com/docker/cagent/pkg/cli"
 	"github.com/docker/cagent/pkg/config"
 	"github.com/docker/cagent/pkg/server"
 	"github.com/docker/cagent/pkg/telemetry"
@@ -43,6 +44,7 @@ func (f *a2aFlags) runA2ACommand(cmd *cobra.Command, args []string) error {
 	telemetry.TrackCommand("a2a", args)
 
 	ctx := cmd.Context()
+	out := cli.NewPrinter(cmd.OutOrStdout())
 	agentFilename := args[0]
 
 	// Listen as early as possible
@@ -55,5 +57,6 @@ func (f *a2aFlags) runA2ACommand(cmd *cobra.Command, args []string) error {
 		_ = ln.Close()
 	}()
 
+	out.Println("Listening on", ln.Addr().String())
 	return a2a.Run(ctx, agentFilename, f.agentName, &f.runConfig, ln)
 }

cmd/root/debug.go

@@ -99,7 +99,7 @@ func (f *debugFlags) runDebugToolsetsCommand(cmd *cobra.Command, args []string)
 
 		out.Printf("%d tool(s) for %s:\n", len(tools), agent.Name())
 		for _, tool := range tools {
-			out.Println(" +", tool.Name)
+			out.Println(" +", tool.Name, "-", tool.Description)
 		}
 	}
 

e2e/cagent_a2a_test.go

@@ -44,7 +44,7 @@ func TestA2AServer_AgentCard(t *testing.T) {
 	_, runConfig := startRecordingAIProxy(t)
 	agentCard := startA2AServer(t, "testdata/basic.yaml", runConfig)
 
-	assert.Equal(t, "root", agentCard.Name)
+	assert.Equal(t, "basic", agentCard.Name)
 	assert.NotEmpty(t, agentCard.Description)
 	assert.Equal(t, a2a.TransportProtocolJSONRPC, agentCard.PreferredTransport)
 	assert.Contains(t, agentCard.URL, "/invoke")

e2e/cagent_debug_test.go

@@ -25,7 +25,7 @@ func TestDebug_Toolsets_Todo(t *testing.T) {
 
 	output := cagentDebug(t, "toolsets", "testdata/todo_tools.yaml")
 
-	require.Equal(t, "2 tool(s) for root:\n + create_todo\n + list_todos\n", output)
+	require.Equal(t, "2 tool(s) for root:\n + create_todo - Create a new todo item with a description\n + list_todos - List all current todos with their status\n", output)
 }
 
 func cagentDebug(t *testing.T, moreArgs ...string) string {

examples/tic-tac-toe.yaml

@@ -0,0 +1,68 @@
+#!/usr/bin/env cagent run
+
+metadata:
+  readme: |
+    This example demonstrates a Tic-Tac-Toe game between two agents, "player_blue" and "player_red", 
+    organized by a root agent. The root agent manages the game state, enforces the rules, and declares the winner or a draw.
+    Each player agent makes moves based on the current state of the board.
+
+    To run the demo:
+    cagent a2a --port 8080 ./examples/tic-tac-toe.yaml --agent player_blue
+    cagent a2a --port 8081 ./examples/tic-tac-toe.yaml --agent player_red
+    cagent run --yolo ./examples/tic-tac-toe.yaml 'Go!'
+
+agents:
+  # Game Organizer
+  root:
+    model: anthropic/claude-opus-4-5
+    description: A Tic-Tac-Toe game organizer
+    instruction: |
+      <identity>
+      You are a Tic-Tac-Toe game organizer. Your goal is to make your two subagents play Tic-Tac-Toe against each other.
+      You keep track of the game state, enforce the rules, and declare the winner or a draw at the end of the game.
+      You communicate with your two subagents, "player_blue" and "player_red", to get their moves and update the game board accordingly.
+      </identity>
+
+      <game>
+      On each player's first turn, you inform them of their assigned mark: "X" for player_blue and "O" for player_red.
+      </game>
+
+      <preparation>
+      Before the game, you must prepare an html page that visually represents the Tic-Tac-Toe board.
+      - Make it retro and super flashy!
+      - Serve this page on a local web server that you runs as a background job. (Stop it at the end of the game.)
+      - Always work in /tmp
+      - IMPORTANT: Make sure you can ping the page before starting the game. We don't want users to miss the game!
+      - The page shows the user the current state of the board and is updated live with javascript and live-reload.
+      - On each turn, you update the page to reflect the current state of the board. It MUST auto-refresh with you update the state/
+      - IMPORTANT: You must open a browser on this URL before the players start to play, for the user to follow the game.
+      - (The url can't be on port 8080 or 8081, as those are used by the players' agents.)
+      </preparation>
+    add_environment_info: true
+    toolsets:
+      - type: shell
+      - type: filesystem
+      - type: a2a
+        name: player_blue
+        url: http://localhost:8080/
+      - type: a2a
+        name: player_red
+        url: http://localhost:8081/
+
+  # BLUE Player
+  player_blue:
+    model: openai/gpt-4.1-nano
+    description: A Tic-Tac-Toe player
+    instruction: |
+      You know how to play Tic-Tac-Toe. You will be playing against another agent in a game organized by a third agent.
+      When it's your turn, you will receive the current state of the board and you need to choose your move by specifying
+      the row and column (0-indexed) where you want to place your mark (X or O).
+
+  # RED Player
+  player_red:
+    model: anthropic/claude-haiku-4-5
+    description: A Tic-Tac-Toe player
+    instruction: |
+      You know how to play Tic-Tac-Toe. You will be playing against another agent in a game organized by a third agent.
+      When it's your turn, you will receive the current state of the board and you need to choose your move by specifying
+      the row and column (0-indexed) where you want to place your mark (X or O).

pkg/a2a/server.go

@@ -7,6 +7,8 @@ import (
 	"net"
 	"net/http"
 	"net/url"
+	"path/filepath"
+	"strings"
 
 	"github.com/a2aproject/a2a-go/a2a"
 	"github.com/a2aproject/a2a-go/a2asrv"
@@ -48,11 +50,18 @@ func Run(ctx context.Context, agentFilename, agentName string, runConfig *config
 
 	slog.Debug("A2A server listening", "url", baseURL.String())
 
+	name := strings.TrimSuffix(filepath.Base(agentFilename), filepath.Ext(agentFilename))
+
 	agentPath := "/invoke"
 	agentCard := &a2a.AgentCard{
-		Name:               adkAgent.Name(),
-		Description:        adkAgent.Description(),
-		Skills:             adka2a.BuildAgentSkills(adkAgent),
+		Name:        name,
+		Description: adkAgent.Description(),
+		Skills: []a2a.AgentSkill{{
+			ID:          name,
+			Name:        "main",
+			Description: adkAgent.Description(),
+			Tags:        []string{"llm", "cagent"},
+		}},
 		PreferredTransport: a2a.TransportProtocolJSONRPC,
 		URL:                baseURL.JoinPath(agentPath).String(),
 		Capabilities:       a2a.AgentCapabilities{Streaming: true},
@@ -63,7 +72,7 @@ func Run(ctx context.Context, agentFilename, agentName string, runConfig *config
 
 	executor := newExecutorWrapper(adka2a.ExecutorConfig{
 		RunnerConfig: runner.Config{
-			AppName:        adkAgent.Name(),
+			AppName:        name,
 			Agent:          adkAgent,
 			SessionService: session.InMemoryService(),
 		},

pkg/config/latest/types.go

@@ -133,6 +133,10 @@ type Toolset struct {
 	Remote  Remote   `json:"remote,omitempty"`
 	Config  any      `json:"config,omitempty"`
 
+	// For the `a2a` tool
+	Name string `json:"name,omitempty"`
+	URL  string `json:"url,omitempty"`
+
 	// For `shell`, `script` or `mcp` tools
 	Env map[string]string `json:"env,omitempty"`
 

pkg/config/latest/validate.go

@@ -57,12 +57,21 @@ func (t *Toolset) validate() error {
 	if t.Ref != "" && t.Type != "mcp" {
 		return errors.New("ref can only be used with type 'mcp'")
 	}
-	if (t.Remote.URL != "" || t.Remote.TransportType != "" || len(t.Remote.Headers) > 0) && t.Type != "mcp" {
+	if (t.Remote.URL != "" || t.Remote.TransportType != "") && t.Type != "mcp" {
 		return errors.New("remote can only be used with type 'mcp'")
 	}
+	if (len(t.Remote.Headers) > 0) && (t.Type != "mcp" && t.Type != "a2a") {
+		return errors.New("headers can only be used with type 'mcp' or 'a2a'")
+	}
 	if t.Config != nil && t.Type != "mcp" {
 		return errors.New("config can only be used with type 'mcp'")
 	}
+	if t.URL != "" && t.Type != "a2a" {
+		return errors.New("url can only be used with type 'a2a'")
+	}
+	if t.Name != "" && t.Type != "a2a" {
+		return errors.New("name can only be used with type 'a2a'")
+	}
 
 	switch t.Type {
 	case "memory":
@@ -90,6 +99,10 @@ func (t *Toolset) validate() error {
 		if t.Ref != "" && !strings.Contains(t.Ref, "docker:") {
 			return errors.New("only docker refs are supported for MCP tools, e.g., 'docker:context7'")
 		}
+	case "a2a":
+		if t.URL == "" {
+			return errors.New("a2a toolset requires a url to be set")
+		}
 	}
 
 	return nil

pkg/httpclient/client.go

@@ -43,6 +43,14 @@ func WithHeader(key, value string) Opt {
 	}
 }
 
+func WithHeaders(headers map[string]string) Opt {
+	return func(o *HTTPOptions) {
+		for k, v := range headers {
+			o.Header.Add(k, v)
+		}
+	}
+}
+
 func WithProxiedBaseURL(value string) Opt {
 	return func(o *HTTPOptions) {
 		o.Header.Set("X-Cagent-Forward", value)