Feat/concurrent transfer

[shentongmartin]

Concurrent Transfer Feature

Summary

This PR introduces concurrent transfer capabilities to the ADK framework, enabling agents to transfer tasks to multiple sub-agents simultaneously using a fork-join execution model.

New APIs

Transfer Tools

• ConcurrentTransferTool: Tool implementation supporting both single and concurrent transfers
  • Accepts agent_name (single) or agent_names (concurrent) parameters
  • Returns appropriate transfer action based on parameter count

Agent Configuration

• ChatModelAgentConfig.TransferTool: Configurable transfer tool field
  • Default: &transferToAgent{} (single-agent transfers)
  • Option: &ConcurrentTransferTool{} (concurrent transfers)

Core Data Structures

• ConcurrentTransferToAgentAction: Action type emitted by ConcurrentTransferTool for multiple destination agents
  • DestAgentNames []string: List of agents to execute concurrently

Usage Examples

Plain Agent Transfer

// Configure agent for concurrent transfers
agent, err := NewChatModelAgent(ctx, &ChatModelAgentConfig{
    Name:        "Orchestrator",
    Model:       chatModel,
    TransferTool: &ConcurrentTransferTool{},
})

// Tool call with multiple agents
{
    "agent_names": ["AnalyticsAgent", "ValidationAgent", "EnrichmentAgent"]
}

Supervisor Pattern

// Supervisor with concurrent sub-agent execution
supervisor, err := New(ctx, &Config{
    Supervisor: &ChatModelAgent{
        Name:        "Supervisor",
        TransferTool: &ConcurrentTransferTool{},
    },
    SubAgents: []adk.Agent{analyticsAgent, validationAgent, enrichmentAgent},
})

// Supervisor can transfer to selected sub-agents concurrently
// Results are automatically aggregated when all selected sub-agents complete

Complex Nested Supervisor

// Multi-level supervisor hierarchy with concurrent transfers
nestedSupervisor, err := New(ctx, &Config{
    Supervisor: subSupervisor,
    SubAgents:  []adk.Agent{grandChild1, grandChild2},
})

topSupervisor, err := New(ctx, &Config{
    Supervisor: superSupervisor,
    SubAgents:  []adk.Agent{subAgent1, nestedSupervisor},
})

// Both levels can execute transfers concurrently
// Interrupts and resumes are properly handled across concurrent lanes

Backward Compatibility

• Existing single-agent transfers continue to work unchanged
• No breaking changes to existing APIs

flowchart TD
    A[flowAgent receives ConcurrentTransferToAgentAction] --> B[runConcurrentLanes called]
    B --> C[Fork execution context for each agent]
    C --> D[Launch concurrent goroutines]
    
    D --> E1[Agent 1: Further Transfers]
    D --> E2[Agent 2: Workflow Agent]
    D --> E3[Agent 3: Custom Agent]
    
    E1 --> F1[Agent 1: May transfer to other agents]
    E2 --> F2[Agent 2: Complex workflow execution]
    E3 --> F3[Agent 3: Custom internal logic]
    
    F1 --> G[Join: Wait for all agents to complete]
    F2 --> G
    F3 --> G
    
    G --> H[Execution complete]

Loading

[github-actions]

📊 Coverage Report:

File coverage threshold (20%) satisfied:	PASS
Package coverage threshold (30%) satisfied:	PASS
Total coverage threshold (83%) satisfied:	PASS
Total test coverage: 83.8% (6899/8230)