Merge pull request #891 from rumpl/feat-handoff

Add agent handoffs

Author: dgageot

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

@@ -53,8 +53,13 @@ const (
 	ResumeTypeReject         ResumeType = "reject"
 )
 
-// ToolHandler is a function type for handling tool calls
-type ToolHandler func(ctx context.Context, sess *session.Session, toolCall tools.ToolCall, events chan Event) (*tools.ToolCallResult, error)
+// ToolHandlerFunc is a function type for handling tool calls
+type ToolHandlerFunc func(ctx context.Context, sess *session.Session, toolCall tools.ToolCall, events chan Event) (*tools.ToolCallResult, error)
+
+type ToolHandler struct {
+	handler ToolHandlerFunc
+	tool    tools.Tool
+}
 
 // ElicitationRequestHandler is a function type for handling elicitation requests
 type ElicitationRequestHandler func(ctx context.Context, message string, schema map[string]any) (map[string]any, error)
@@ -369,7 +374,26 @@ func (r *LocalRuntime) EmitStartupInfo(ctx context.Context, events chan Event) {
 // registerDefaultTools registers the default tool handlers
 func (r *LocalRuntime) registerDefaultTools() {
 	slog.Debug("Registering default tools")
-	r.toolMap[builtin.ToolNameTransferTask] = r.handleTaskTransfer
+
+	tt := builtin.NewTransferTaskTool()
+	ht := builtin.NewHandoffTool()
+	ttTools, _ := tt.Tools(context.TODO())
+	htTools, _ := ht.Tools(context.TODO())
+	allTools := append(ttTools, htTools...)
+
+	handlers := map[string]ToolHandlerFunc{
+		builtin.ToolNameTransferTask: r.handleTaskTransfer,
+		builtin.ToolNameHandoff:      r.handleHandoff,
+	}
+
+	for _, t := range allTools {
+		if h, exists := handlers[t.Name]; exists {
+			r.toolMap[t.Name] = ToolHandler{handler: h, tool: t}
+		} else {
+			slog.Warn("No handler found for default tool", "tool", t.Name)
+		}
+	}
+
 	slog.Debug("Registered default tools", "count", len(r.toolMap))
 }
 
@@ -455,6 +479,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)
@@ -881,42 +923,37 @@ func (r *LocalRuntime) processToolCalls(ctx context.Context, sess *session.Sessi
 		))
 
 		slog.Debug("Processing tool call", "agent", a.Name(), "tool", toolCall.Function.Name, "session_id", sess.ID)
-		handler, exists := r.toolMap[toolCall.Function.Name]
+		def, exists := r.toolMap[toolCall.Function.Name]
 		if exists {
-			tool := tools.Tool{
-				Annotations: tools.ToolAnnotations{
-					// TODO: We need to handle the transfer task tool better
-					Title: "Transfer Task",
-				},
-			}
 			slog.Debug("Using runtime tool handler", "tool", toolCall.Function.Name, "session_id", sess.ID)
-			if sess.ToolsApproved || toolCall.Function.Name == builtin.ToolNameTransferTask {
-				r.runAgentTool(callCtx, handler, sess, toolCall, tool, events, a)
+			// TODO: make this better, these tools define themselves as read-only
+			if sess.ToolsApproved || def.tool.Annotations.ReadOnlyHint {
+				r.runAgentTool(callCtx, def.handler, sess, toolCall, def.tool, events, a)
 			} else {
 				slog.Debug("Tools not approved, waiting for resume", "tool", toolCall.Function.Name, "session_id", sess.ID)
 
-				events <- ToolCallConfirmation(toolCall, tool, a.Name())
+				events <- ToolCallConfirmation(toolCall, def.tool, a.Name())
 
 				select {
 				case cType := <-r.resumeChan:
 					switch cType {
 					case ResumeTypeApprove:
 						slog.Debug("Resume signal received, approving tool handler", "tool", toolCall.Function.Name, "session_id", sess.ID)
-						r.runAgentTool(callCtx, handler, sess, toolCall, tool, events, a)
+						r.runAgentTool(callCtx, def.handler, sess, toolCall, def.tool, events, a)
 					case ResumeTypeApproveSession:
 						slog.Debug("Resume signal received, approving session", "tool", toolCall.Function.Name, "session_id", sess.ID)
 						sess.ToolsApproved = true
-						r.runAgentTool(callCtx, handler, sess, toolCall, tool, events, a)
+						r.runAgentTool(callCtx, def.handler, sess, toolCall, def.tool, events, a)
 					case ResumeTypeReject:
 						slog.Debug("Resume signal received, rejecting tool handler", "tool", toolCall.Function.Name, "session_id", sess.ID)
-						r.addToolRejectedResponse(sess, toolCall, tool, events)
+						r.addToolRejectedResponse(sess, toolCall, def.tool, events)
 					}
 				case <-callCtx.Done():
 					slog.Debug("Context cancelled while waiting for resume", "tool", toolCall.Function.Name, "session_id", sess.ID)
 					// Synthesize cancellation responses for the current and any remaining tool calls
-					r.addToolCancelledResponse(sess, toolCall, tool, events)
+					r.addToolCancelledResponse(sess, toolCall, def.tool, events)
 					for j := i + 1; j < len(calls); j++ {
-						r.addToolCancelledResponse(sess, calls[j], tool, events)
+						r.addToolCancelledResponse(sess, calls[j], def.tool, events)
 					}
 					callSpan.SetStatus(codes.Ok, "tool call canceled by user")
 					return
@@ -1043,7 +1080,7 @@ func (r *LocalRuntime) runTool(ctx context.Context, tool tools.Tool, toolCall to
 	sess.AddMessage(session.NewAgentMessage(a, &toolResponseMsg))
 }
 
-func (r *LocalRuntime) runAgentTool(ctx context.Context, handler ToolHandler, sess *session.Session, toolCall tools.ToolCall, tool tools.Tool, events chan Event, a *agent.Agent) {
+func (r *LocalRuntime) runAgentTool(ctx context.Context, handler ToolHandlerFunc, sess *session.Session, toolCall tools.ToolCall, tool tools.Tool, events chan Event, a *agent.Agent) {
 	// Start a child span for runtime-provided tool handler execution
 	ctx, span := r.startSpan(ctx, "runtime.tool.handler.runtime", trace.WithAttributes(
 		attribute.String("tool.name", toolCall.Function.Name),
@@ -1234,6 +1271,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

@@ -276,13 +276,28 @@ func (s *Session) GetMessages(a *agent.Agent) []chat.Message {
 		subAgentsStr := ""
 		var validAgentIDs []string
 		for _, subAgent := range subAgents {
-			subAgentsStr += "ID: " + subAgent.Name() + " | Name: " + subAgent.Name() + " | Description: " + subAgent.Description() + "\n"
+			subAgentsStr += "Name: " + subAgent.Name() + " | Description: " + subAgent.Description() + "\n"
 			validAgentIDs = append(validAgentIDs, subAgent.Name())
 		}
 
 		messages = append(messages, chat.Message{
 			Role:    chat.MessageRoleSystem,
-			Content: "You are a multi-agent system, make sure to answer the user query in the most helpful way possible. You have access to these sub-agents:\n" + subAgentsStr + "\nIMPORTANT: You can ONLY transfer tasks to the agents listed above using their ID. The valid agent IDs are: " + strings.Join(validAgentIDs, ", ") + ". You MUST NOT attempt to transfer to any other agent IDs - doing so will cause system errors.\n\nIf you are the best to answer the question according to your description, you can answer it.\n\nIf another agent is better for answering the question according to its description, call `transfer_task` function to transfer the question to that agent using the agent's ID. When transferring, do not generate any text other than the function call.\n\n",
+			Content: "You are a multi-agent system, make sure to answer the user query in the most helpful way possible. You have access to these sub-agents:\n" + subAgentsStr + "\nIMPORTANT: You can ONLY transfer tasks to the agents listed above using their ID. The valid agent names are: " + strings.Join(validAgentIDs, ", ") + ". You MUST NOT attempt to transfer to any other agent IDs - doing so will cause system errors.\n\nIf you are the best to answer the question according to your description, you can answer it.\n\nIf another agent is better for answering the question according to its description, call `transfer_task` function to transfer the question to that agent using the agent's ID. When transferring, do not generate any text other than the function call.\n\n",
+		})
+	}
+
+	handoffs := a.Handoffs()
+	if len(handoffs) > 0 {
+		agentsInfo := ""
+		var validAgentIDs []string
+		for _, agent := range handoffs {
+			agentsInfo += "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 names 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.",
 		})
 	}
 

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.