1# Delegate to Agent Tool
2 
3## Purpose
4 
5Route a task to a specialized agent for execution. Handles context passing, result collection, and error management.
6 
7## Tool Definition
8 
9```typescript
10import { tool } from "ai";
11import { z } from "zod";
12 
13export const delegateToAgent = tool({
14  description: `Delegate a task to a specialized agent.
15Use when a subtask requires specific capabilities.
16Pass complete context needed for the agent to succeed.`,
17 
18  parameters: z.object({
19    agentName: z.enum(["evaluator", "researcher", "writer", "analyst"])
20      .describe("Name of the agent to delegate to"),
21    
22    task: z.string()
23      .describe("Clear description of what the agent should do"),
24    
25    context: z.object({
26      previousOutputs: z.array(z.string()).optional()
27        .describe("Outputs from prior steps this agent needs"),
28      
29      documents: z.array(z.string()).optional()
30        .describe("Relevant documents or data"),
31      
32      constraints: z.array(z.string()).optional()
33        .describe("Requirements or limitations to observe")
34    }).optional(),
35    
36    expectedOutput: z.object({
37      format: z.enum(["text", "json", "markdown", "structured"])
38        .describe("Expected output format"),
39      
40      schema: z.string().optional()
41        .describe("JSON schema if format is structured"),
42      
43      maxLength: z.number().optional()
44        .describe("Maximum length constraint")
45    }).optional(),
46    
47    timeout: z.number().default(60000)
48      .describe("Timeout in milliseconds")
49  }),
50 
51  execute: async (input) => {
52    return executeAgentDelegation(input);
53  }
54});
55```
56 
57## Input Schema
58 
59| Field | Type | Required | Description |
60|-------|------|----------|-------------|
61| agentName | enum | Yes | Target agent |
62| task | string | Yes | Task description |
63| context | object | No | Context and dependencies |
64| expectedOutput | object | No | Output requirements |
65| timeout | number | No | Timeout ms (default: 60000) |
66 
67## Output Schema
68 
69```typescript
70interface DelegationResult {
71  success: boolean;
72  
73  agentName: string;
74  task: string;
75  
76  output: {
77    content: string | object;
78    format: string;
79  };
80  
81  execution: {
82    startTime: string;
83    endTime: string;
84    durationMs: number;
85    tokenUsage: {
86      prompt: number;
87      completion: number;
88    };
89  };
90  
91  error?: {
92    code: string;
93    message: string;
94    retryable: boolean;
95  };
96}
97```
98 
99## Available Agents
100 
101### Evaluator Agent
102```typescript
103await delegateToAgent.execute({
104  agentName: "evaluator",
105  task: "Evaluate the quality of this response against accuracy and clarity criteria",
106  context: {
107    documents: [responseToEvaluate],
108    constraints: ["Use 1-5 scale", "Include justification"]
109  },
110  expectedOutput: { format: "structured" }
111});
112```
113 
114### Researcher Agent
115```typescript
116await delegateToAgent.execute({
117  agentName: "researcher",
118  task: "Research current best practices for LLM evaluation",
119  context: {
120    constraints: ["Focus on 2024 publications", "Include citations"]
121  },
122  expectedOutput: { format: "markdown" }
123});
124```
125 
126### Writer Agent
127```typescript
128await delegateToAgent.execute({
129  agentName: "writer",
130  task: "Write an executive summary of these research findings",
131  context: {
132    previousOutputs: [researchFindings],
133    constraints: ["Maximum 500 words", "Non-technical audience"]
134  },
135  expectedOutput: { format: "text", maxLength: 2500 }
136});
137```
138 
139### Analyst Agent
140```typescript
141await delegateToAgent.execute({
142  agentName: "analyst",
143  task: "Analyze the trade-offs between direct scoring and pairwise comparison",
144  context: {
145    documents: [evaluationData],
146    constraints: ["Quantitative where possible"]
147  },
148  expectedOutput: { format: "structured" }
149});
150```
151 
152## Error Handling
153 
154```typescript
155const errorCodes = {
156  "AGENT_NOT_FOUND": "Specified agent does not exist",
157  "TIMEOUT": "Agent did not complete within timeout",
158  "CONTEXT_TOO_LARGE": "Context exceeds agent's capacity",
159  "INVALID_OUTPUT": "Agent output did not match expected format",
160  "AGENT_ERROR": "Agent encountered an error during execution"
161};
162```
163 
164## Implementation Notes
165 
1661. **Context Optimization**: Compress context if needed before passing
1672. **Timeout Handling**: Set realistic timeouts per agent type
1683. **Retry Logic**: Implement retries for transient failures
1694. **Audit Trail**: Log all delegations for traceability
1705. **Resource Management**: Track token usage across delegations
171 
172