Merge pull request #71 from dexhorthy/dexter/eng-1116-delegation-to-sub-agents

sub-agent delegation

Author: dexhorthy

README.md

@@ -33,6 +33,7 @@ ACP (Agent Control Plane) is a cloud-native orchestrator for AI Agents built on
   - [Creating an Agent and Running your first task](#creating-an-agent-and-running-your-first-task)
   - [Adding Tools with MCP](#adding-tools-with-mcp)
   - [Using other language models](#using-other-language-models)
+  - [Delegating to a Sub-Agent](#delegating-to-a-sub-agent)
   - [Incorporating Human Approval](#incorporating-human-approval)
   - [Incorporating Humans as Tools](#humans-as-tools)
   - [Cleaning Up](#cleaning-up)
@@ -908,6 +909,107 @@ NAME          READY   STATUS   PHASE         PREVIEW   OUTPUT
 claude-task   true    Ready    FinalAnswer             I am Claude, an AI assistant created by Anthropic. My primary directive is to be helpful while being direct and honest in my interactions. I aim to help users with their tasks while adhering to ethical principles.
 ```
 
+### Delegating to a Sub-Agent
+
+We can compose agents together to create more complex behaviors and make longer workflows more reliable.
+
+Let's create a web search agent that can use the fetch tool we created in the previous example.
+
+```bash
+cat <<EOF | kubectl apply -f -
+apiVersion: acp.humanlayer.dev/v1alpha1
+kind: Agent
+metadata:
+  name: web-search
+spec:
+  llmRef:
+    name: gpt-4o
+  system: |
+    You are a helpful assistant. Your job is to help the user with their tasks.
+  mcpServers:
+    - name: fetch
+EOF
+```
+
+next, we can create a router agent that can delegate to the web search agent.
+
+```bash
+cat <<EOF | kubectl apply -f -
+apiVersion: acp.humanlayer.dev/v1alpha1
+kind: Agent
+metadata:
+  name: manager
+spec:
+  llmRef:
+    name: gpt-4o
+  system: |
+    You are a helpful assistant. Your job is to help the user with their tasks.
+  subAgents:
+    - name: web-search
+EOF
+```
+
+From here, let's create a task that uses the manager agent.
+
+```bash
+cat <<EOF | kubectl apply -f -
+apiVersion: acp.humanlayer.dev/v1alpha1
+kind: Task
+metadata:
+  name: manager-task
+spec:
+  agentRef:
+    name: manager
+  userMessage: "what is the data at https://lotrapi.co/api/v1/characters/2?"
+EOF
+```
+
+While this is running, you can run the following a few times to see how the parent agent calls a `delegate` tool which then spawns a new task that uses the `web-fetch` agent
+
+```
+kubectl get agent,task,toolcall
+```
+
+
+
+
+The following diagram shows the relationship between Agents, subagents, and created tasks:
+
+```mermaid
+graph RL
+    
+
+    subgraph ManagerAgent
+      subAgents
+    end
+
+    subgraph WebFetchAgent
+      MCPServers
+    end
+
+
+
+    subgraph ManagerTask
+       agentRef
+    end
+
+    subgraph DelegationTask
+      userMessage
+      agentRef2
+    end
+
+    DelegationTask --> parentTask --> ManagerTask
+    agentRef2 --> WebFetchAgent
+
+    agentRef --> ManagerAgent
+
+    subgraph MCPServer
+      fetch[fetch server]
+    end
+
+    MCPServers --> MCPServer
+```
+
 ### Incorporating Human Approval
 
 For certain classes of MCP tools, you may want to incorporate human approval into an agent's workflow.
@@ -1198,7 +1300,7 @@ kind delete cluster
 | MCP stdio Support | Alpha ✅ |
 | Task Execution History via Kubernetes Events | Alpha ✅ |
 | Better MCP Scheduling | Planned 🗺️ |
-| Delegation to Sub Agents | Planned 🗺️ |
+| Delegation to Sub Agents | In Progress 🚧 |
 | Human approval for MCP Tools | Alpha ✅ |
 | Contact human as a tool | In Progress 🚧 |
 | Tiered approval (once, just for this task, or always) | Planned 🗺️ |

acp/api/v1alpha1/agent_types.go

@@ -22,6 +22,16 @@ type AgentSpec struct {
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
 	System string `json:"system"`
+
+	// SubAgents is a list of local object references to other Agents
+	// that can be delegated to as sub-agents.
+	// +optional
+	SubAgents []LocalObjectReference `json:"subAgents,omitempty"`
+
+	// Description is an optional description for an agent.
+	// If present, it's included in any "delegateToAgent" tool descriptions
+	// +optional
+	Description string `json:"description,omitempty"`
 }
 
 // LocalObjectReference contains enough information to locate the referenced resource in the same namespace
@@ -32,14 +42,22 @@ type LocalObjectReference struct {
 	Name string `json:"name"`
 }
 
+type AgentStatusType string
+
+const (
+	AgentStatusReady   AgentStatusType = "Ready"
+	AgentStatusError   AgentStatusType = "Error"
+	AgentStatusPending AgentStatusType = "Pending"
+)
+
 // AgentStatus defines the observed state of Agent
 type AgentStatus struct {
 	// Ready indicates if the agent's dependencies (LLM and Tools) are valid and ready
 	Ready bool `json:"ready,omitempty"`
 
 	// Status indicates the current status of the agent
 	// +kubebuilder:validation:Enum=Ready;Error;Pending
-	Status string `json:"status,omitempty"`
+	Status AgentStatusType `json:"status,omitempty"`
 
 	// StatusDetail provides additional details about the current status
 	StatusDetail string `json:"statusDetail,omitempty"`
@@ -51,6 +69,10 @@ type AgentStatus struct {
 	// ValidHumanContactChannels is the list of human contact channels that were successfully validated
 	// +optional
 	ValidHumanContactChannels []ResolvedContactChannel `json:"validHumanContactChannels,omitempty"`
+
+	// ValidSubAgents is the list of sub-agents that were successfully validated
+	// +optional
+	ValidSubAgents []ResolvedSubAgent `json:"validSubAgents,omitempty"`
 }
 
 type ResolvedMCPServer struct {
@@ -73,6 +95,12 @@ type ResolvedContactChannel struct {
 	Type string `json:"type"`
 }
 
+type ResolvedSubAgent struct {
+	// Name of the sub-agent
+	// +kubebuilder:validation:Required
+	Name string `json:"name"`
+}
+
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Ready",type="boolean",JSONPath=".status.ready"

acp/api/v1alpha1/task_types.go

@@ -157,6 +157,7 @@ const (
 
 // +kubebuilder:object:root=true
 // +kubebuilder:subresource:status
+// +kubebuilder:printcolumn:name="Agent",type="string",JSONPath=".spec.agentRef.name"
 // +kubebuilder:printcolumn:name="Ready",type="boolean",JSONPath=".status.ready"
 // +kubebuilder:printcolumn:name="Status",type="string",JSONPath=".status.status"
 // +kubebuilder:printcolumn:name="Detail",type="string",JSONPath=".status.statusDetail",priority=1

acp/api/v1alpha1/toolcall_types.go

@@ -13,12 +13,13 @@ const (
 	ToolCallStatusTypeSucceeded ToolCallStatusType = "Succeeded"
 )
 
-// ToolType identifies the type of the tool (Standard, MCP, HumanContact)
+// ToolType identifies the type of the tool (Standard, MCP, HumanContact, DelegateToAgent)
 type ToolType string
 
 const (
-	ToolTypeMCP          ToolType = "MCP"
-	ToolTypeHumanContact ToolType = "HumanContact"
+	ToolTypeMCP             ToolType = "MCP"
+	ToolTypeHumanContact    ToolType = "HumanContact"
+	ToolTypeDelegateToAgent ToolType = "DelegateToAgent"
 )
 
 // ToolCallSpec defines the desired state of ToolCall

acp/api/v1alpha1/zz_generated.deepcopy.go

@@ -50,6 +50,11 @@ spec:
           spec:
             description: AgentSpec defines the desired state of Agent
             properties:
+              description:
+                description: |-
+                  Description is an optional description for an agent.
+                  If present, it's included in any "delegateToAgent" tool descriptions
+                type: string
               humanContactChannels:
                 description: HumanContactChannels is a list of ContactChannel resources
                   that can be used for human interactions
@@ -89,6 +94,22 @@ spec:
                   - name
                   type: object
                 type: array
+              subAgents:
+                description: |-
+                  SubAgents is a list of local object references to other Agents
+                  that can be delegated to as sub-agents.
+                items:
+                  description: LocalObjectReference contains enough information to
+                    locate the referenced resource in the same namespace
+                  properties:
+                    name:
+                      description: Name of the referent
+                      minLength: 1
+                      type: string
+                  required:
+                  - name
+                  type: object
+                type: array
               system:
                 description: System is the system prompt for the agent
                 minLength: 1
@@ -148,6 +169,18 @@ spec:
                   - name
                   type: object
                 type: array
+              validSubAgents:
+                description: ValidSubAgents is the list of sub-agents that were successfully
+                  validated
+                items:
+                  properties:
+                    name:
+                      description: Name of the sub-agent
+                      type: string
+                  required:
+                  - name
+                  type: object
+                type: array
             type: object
         type: object
     served: true

acp/config/crd/bases/acp.humanlayer.dev_agents.yaml

@@ -15,6 +15,9 @@ spec:
   scope: Namespaced
   versions:
   - additionalPrinterColumns:
+    - jsonPath: .spec.agentRef.name
+      name: Agent
+      type: string
     - jsonPath: .status.ready
       name: Ready
       type: boolean

acp/config/crd/bases/acp.humanlayer.dev_tasks.yaml

@@ -7,3 +7,4 @@ images:
 - name: controller
   newName: ghcr.io/humanlayer/agentcontrolplane
   newTag: v0.5.1
+