Add agent handoffs

These are different than sub agents because they are not "smart tools"
but rather a list of agents that the current agent can hand the
conversation to, the new agent can continue with hte conversation and
has access to the whole history.

Signed-off-by: Djordje Lukic <djordje.lukic@docker.com>

Author: rumpl

cagent-schema.json

@@ -92,6 +92,13 @@
             "type": "string"
           }
         },
+        "handoffs": {
+          "type": "array",
+          "description": "List of agents this agent can hand off the conversation to",
+          "items": {
+            "type": "string"
+          }
+        },
         "add_date": {
           "type": "boolean",
           "description": "Whether to add date information"
@@ -662,17 +669,26 @@
           "items": {
             "type": "object",
             "description": "Retrieval strategy configuration with type-specific parameters. Structured fields are limited; additional parameters are passed through as-is for strategy-specific use.",
-            "required": ["type"],
+            "required": [
+              "type"
+            ],
             "properties": {
               "type": {
                 "type": "string",
                 "description": "Retrieval strategy type",
-                "enum": ["chunked-embeddings", "bm25"]
+                "enum": [
+                  "chunked-embeddings",
+                  "bm25"
+                ]
               },
               "model": {
                 "type": "string",
                 "description": "Embedding model reference for chunked-embeddings strategies (looked up in models map, or 'auto' for automatic selection)",
-                "examples": ["openai/text-embedding-3-small", "dmr/embeddinggemma", "auto"]
+                "examples": [
+                  "openai/text-embedding-3-small",
+                  "dmr/embeddinggemma",
+                  "auto"
+                ]
               },
               "docs": {
                 "type": "array",
@@ -688,13 +704,20 @@
               "similarity_metric": {
                 "type": "string",
                 "description": "Similarity metric (chunked-embeddings only). Currently only 'cosine_similarity' is implemented.",
-                "enum": ["cosine_similarity"]
+                "enum": [
+                  "cosine_similarity"
+                ]
               },
               "vector_dimensions": {
                 "type": "integer",
                 "description": "Vector dimensions for embeddings (chunked-embeddings only). Must match your embedding model's output dimensions and is required for chunked-embeddings strategies.",
                 "minimum": 1,
-                "examples": [1536, 3072, 1024, 768]
+                "examples": [
+                  1536,
+                  3072,
+                  1024,
+                  768
+                ]
               },
               "k1": {
                 "type": "number",

examples/handoff.yaml

@@ -0,0 +1,17 @@
+agents:
+  root:
+    model: anthropic/claude-sonnet-4-5
+    description: The best agent
+    instruction: |
+      You are a helpful assistant that can hand off tasks to other agents.
+      Look at the descriptions ofthe avaiable agents, if any of them is better suited to answer the user question, you must call the handoff tool to transfer the task to that agent.
+    handoffs:
+      - web_search
+
+  web_search:
+    model: openai/gpt-4o
+    description: An agent specialized in web searching and information retrieval.
+    instruction: You are an agent specialized in web searching and information retrieval.
+    toolsets:
+      - type: mcp
+        ref: docker:duckduckgo

pkg/agent/agent.go

@@ -19,6 +19,7 @@ type Agent struct {
 	toolsets           []*StartableToolSet
 	models             []provider.Provider
 	subAgents          []*Agent
+	handoffs           []*Agent
 	parents            []*Agent
 	addDate            bool
 	addEnvironmentInfo bool
@@ -83,11 +84,16 @@ func (a *Agent) WelcomeMessage() string {
 	return a.welcomeMessage
 }
 
-// SubAgents returns the list of sub-agent names
+// SubAgents returns the list of sub-agents
 func (a *Agent) SubAgents() []*Agent {
 	return a.subAgents
 }
 
+// Handoffs returns the list of handoff agents
+func (a *Agent) Handoffs() []*Agent {
+	return a.handoffs
+}
+
 // Parents returns the list of parent agent names
 func (a *Agent) Parents() []*Agent {
 	return a.parents

pkg/agent/opts.go

@@ -67,6 +67,12 @@ func WithSubAgents(subAgents ...*Agent) Opt {
 	}
 }
 
+func WithHandoffs(handoffs ...*Agent) Opt {
+	return func(a *Agent) {
+		a.handoffs = handoffs
+	}
+}
+
 func WithAddDate(addDate bool) Opt {
 	return func(a *Agent) {
 		a.addDate = addDate

pkg/config/v2/types.go

@@ -25,6 +25,7 @@ type AgentConfig struct {
 	Toolsets           []Toolset         `json:"toolsets,omitempty"`
 	Instruction        string            `json:"instruction,omitempty"`
 	SubAgents          []string          `json:"sub_agents,omitempty"`
+	Handoffs           []string          `json:"handoffs,omitempty"`
 	RAG                []string          `json:"rag,omitempty"`
 	AddDate            bool              `json:"add_date,omitempty"`
 	AddEnvironmentInfo bool              `json:"add_environment_info,omitempty"`

pkg/runtime/runtime.go

@@ -370,6 +370,7 @@ func (r *LocalRuntime) EmitStartupInfo(ctx context.Context, events chan Event) {
 func (r *LocalRuntime) registerDefaultTools() {
 	slog.Debug("Registering default tools")
 	r.toolMap[builtin.ToolNameTransferTask] = r.handleTaskTransfer
+	r.toolMap[builtin.ToolNameHandoff] = r.handleHandoff
 	slog.Debug("Registered default tools", "count", len(r.toolMap))
 }
 
@@ -455,6 +456,24 @@ func (r *LocalRuntime) RunStream(ctx context.Context, sess *session.Session) <-c
 		runtimeMaxIterations := sess.MaxIterations
 
 		for {
+			// Set elicitation handler on all MCP toolsets before getting tools
+			a := r.CurrentAgent()
+
+			r.emitAgentWarnings(a, events)
+
+			for _, toolset := range a.ToolSets() {
+				toolset.SetElicitationHandler(r.elicitationHandler)
+				toolset.SetOAuthSuccessHandler(func() {
+					events <- Authorization("confirmed", r.currentAgent)
+				})
+			}
+
+			agentTools, err := r.getTools(ctx, a, sessionSpan, events)
+			if err != nil {
+				events <- Error(fmt.Sprintf("failed to get tools: %v", err))
+				return
+			}
+
 			// Check iteration limit
 			if runtimeMaxIterations > 0 && iteration >= runtimeMaxIterations {
 				slog.Debug("Maximum iterations reached", "agent", a.Name(), "iterations", iteration, "max", runtimeMaxIterations)
@@ -890,7 +909,8 @@ func (r *LocalRuntime) processToolCalls(ctx context.Context, sess *session.Sessi
 				},
 			}
 			slog.Debug("Using runtime tool handler", "tool", toolCall.Function.Name, "session_id", sess.ID)
-			if sess.ToolsApproved || toolCall.Function.Name == builtin.ToolNameTransferTask {
+			// TODO: make this better, these tols define themselves as read-only
+			if sess.ToolsApproved || toolCall.Function.Name == builtin.ToolNameTransferTask || toolCall.Function.Name == builtin.ToolNameHandoff {
 				r.runAgentTool(callCtx, handler, sess, toolCall, tool, events, a)
 			} else {
 				slog.Debug("Tools not approved, waiting for resume", "tool", toolCall.Function.Name, "session_id", sess.ID)
@@ -1234,6 +1254,24 @@ func (r *LocalRuntime) handleTaskTransfer(ctx context.Context, sess *session.Ses
 	}, nil
 }
 
+func (r *LocalRuntime) handleHandoff(ctx context.Context, sess *session.Session, toolCall tools.ToolCall, evts chan Event) (*tools.ToolCallResult, error) {
+	var params builtin.HandoffArgs
+	if err := json.Unmarshal([]byte(toolCall.Function.Arguments), &params); err != nil {
+		return nil, fmt.Errorf("invalid arguments: %w", err)
+	}
+
+	ca := r.currentAgent
+	next, err := r.team.Agent(params.Agent)
+	if err != nil {
+		return nil, err
+	}
+
+	r.currentAgent = next.Name()
+	return &tools.ToolCallResult{
+		Output: fmt.Sprintf("The agent %s handed off the conversation to you, look at the history of the conversation and continue where it left off. Once you are done with your task or if the user asks you, handoff the conversation back to %s.", ca, ca),
+	}, nil
+}
+
 // generateSessionTitle generates a title for the session based on the conversation history
 func (r *LocalRuntime) generateSessionTitle(ctx context.Context, sess *session.Session, events chan Event) {
 	slog.Debug("Generating title for session", "session_id", sess.ID)

pkg/session/session.go

@@ -286,6 +286,21 @@ func (s *Session) GetMessages(a *agent.Agent) []chat.Message {
 		})
 	}
 
+	handoffs := a.Handoffs()
+	if len(handoffs) > 0 {
+		agentsInfo := ""
+		var validAgentIDs []string
+		for _, agent := range handoffs {
+			agentsInfo += "ID: " + agent.Name() + " | Name: " + agent.Name() + " | Description: " + agent.Description() + "\n"
+			validAgentIDs = append(validAgentIDs, agent.Name())
+		}
+
+		messages = append(messages, chat.Message{
+			Role:    chat.MessageRoleSystem,
+			Content: "You are part of a multi-agent team. Your goal is to answer the user query in the most helpful way possible.\n\nAvailable agents in your team:\n" + agentsInfo + "\nYou can hand off the conversation to any of these agents at any time by using the `handoff` function with their ID. The valid agent IDs are: " + strings.Join(validAgentIDs, ", ") + ".\n\nWhen to hand off:\n- If another agent's description indicates they are better suited for the current task or question\n\n- If any of the tools of the agent indicate that this agent is able to respond correctly- If the user explicitly asks for a specific agent\n- If you need specialized capabilities that another agent provides\n\nIf you are the best agent to handle the current request based on your capabilities, respond directly. When handing off to another agent, only handoff without talking about the handoff.",
+		})
+	}
+
 	content := a.Instruction()
 
 	if a.AddDate() {

pkg/teamloader/teamloader.go

@@ -208,11 +208,9 @@ func LoadFrom(ctx context.Context, source AgentSource, runtimeConfig *config.Run
 		agentsByName[name] = ag
 	}
 
+	// Connect sub-agents and handoff agents
 	for name := range cfg.Agents {
 		agentConfig := cfg.Agents[name]
-		if len(agentConfig.SubAgents) == 0 {
-			continue
-		}
 
 		subAgents := make([]*agent.Agent, 0, len(agentConfig.SubAgents))
 		for _, subName := range agentConfig.SubAgents {
@@ -224,6 +222,17 @@ func LoadFrom(ctx context.Context, source AgentSource, runtimeConfig *config.Run
 		if a, exists := agentsByName[name]; exists && len(subAgents) > 0 {
 			agent.WithSubAgents(subAgents...)(a)
 		}
+
+		handoffs := make([]*agent.Agent, 0, len(agentConfig.Handoffs))
+		for _, handoffName := range agentConfig.Handoffs {
+			if handoffAgent, exists := agentsByName[handoffName]; exists {
+				handoffs = append(handoffs, handoffAgent)
+			}
+		}
+
+		if a, exists := agentsByName[name]; exists && len(handoffs) > 0 {
+			agent.WithHandoffs(handoffs...)(a)
+		}
 	}
 
 	id := loadOpts.id
@@ -295,6 +304,9 @@ func getToolsForAgent(ctx context.Context, a *latest.AgentConfig, parentDir stri
 	if len(a.SubAgents) > 0 {
 		toolSets = append(toolSets, builtin.NewTransferTaskTool())
 	}
+	if len(a.Handoffs) > 0 {
+		toolSets = append(toolSets, builtin.NewHandoffTool())
+	}
 
 	// Wrap all tools in a single Code Mode toolset.
 	// This allows the agent to call multiple tools in a single response.

pkg/tools/builtin/handoff.go

@@ -0,0 +1,51 @@
+package builtin
+
+import (
+	"context"
+
+	"github.com/docker/cagent/pkg/tools"
+)
+
+const ToolNameHandoff = "handoff"
+
+type HandoffTool struct {
+	tools.ElicitationTool
+}
+
+// Make sure Handoff Tool implements the ToolSet Interface
+var _ tools.ToolSet = (*HandoffTool)(nil)
+
+type HandoffArgs struct {
+	Agent string `json:"agent" jsonschema:"The name of the agent to hand off the conversation to."`
+}
+
+func NewHandoffTool() *HandoffTool {
+	return &HandoffTool{}
+}
+
+func (t *HandoffTool) Instructions() string {
+	return ""
+}
+
+func (t *HandoffTool) Tools(context.Context) ([]tools.Tool, error) {
+	return []tools.Tool{
+		{
+			Name:        ToolNameHandoff,
+			Category:    "handoff",
+			Description: "Use this function to hand off the conversation to the selected agent.",
+			Parameters:  tools.MustSchemaFor[HandoffArgs](),
+			Annotations: tools.ToolAnnotations{
+				ReadOnlyHint: true,
+				Title:        "Handoff Conversation",
+			},
+		},
+	}, nil
+}
+
+func (t *HandoffTool) Start(context.Context) error {
+	return nil
+}
+
+func (t *HandoffTool) Stop(context.Context) error {
+	return nil
+}