agent tool

AgentTool 实现了子 Agent 调用机制，支持任务委派和多 Agent 协作。

设计理念

为什么需要子 Agent？

单个 AI Agent 面临的挑战：

1. 上下文限制 - 复杂任务需要大量上下文

2. 专业化 - 不同任务需要不同的专业知识

3. 并行化 - 某些任务可以并行执行

子 Agent 解决方案：

• 每个子 Agent 有独立的上下文

• 可以使用专门的 System Prompt

• 支持同步和异步执行

核心实现

输入 Schema

const AgentInputSchema = z.object({
  name: z.string(),  // Agent 名称
  prompt: z.string(), // 任务描述
  explanation: z.string(), // 为什么调用这个 Agent
  contextFiles: z.array(z.object({
    path: z.string(),
    startLine: z.number().optional(),
    endLine: z.number().optional(),
  })).optional(),
  preset: z.string().optional(), // Agent 预设
});

执行流程

async execute(input: AgentInput, context: ToolContext) {
  // 1. 解析 Agent 类型
  const agentType = parseAgentType(input.name);
  
  // 2. 准备上下文
  const agentContext = await prepareAgentContext(
    input.contextFiles,
    context
  );
  
  // 3. 构建 Agent System Prompt
  const systemPrompt = await buildAgentPrompt(
    agentType,
    input.preset
  );
  
  // 4. 执行 Agent
  if (agentType.mode === 'sync') {
    return await executeSyncAgent(input, agentContext, systemPrompt);
  } else {
    return await executeAsyncAgent(input, agentContext, systemPrompt);
  }
}

Agent 类型

内置 Agent

const BUILTIN_AGENTS = {
  'context-gatherer': {
    description: '分析代码库，识别相关文件',
    mode: 'sync',
    tools: ['readCode', 'fileSearch', 'grepSearch'],
  },
  
  'custom-agent-creator': {
    description: '创建自定义 Agent',
    mode: 'sync',
    tools: ['fsWrite', 'readFile'],
  },
  
  'general-task-execution': {
    description: '通用任务执行',
    mode: 'sync',
    tools: '*', // 所有工具
  },
};

自定义 Agent

// .kiro/agents/my-agent.json
{
  "name": "code-reviewer",
  "description": "Review code for best practices",
  "systemPrompt": "You are a code reviewer...",
  "tools": ["readCode", "getDiagnostics"],
  "mode": "sync"
}

同步执行

实现

async function executeSyncAgent(
  input: AgentInput,
  context: AgentContext,
  systemPrompt: string
): Promise<ToolResult> {
  // 创建新的消息历史
  const messages = [
    { role: 'user', content: input.prompt },
  ];
  
  // 添加上下文文件
  if (context.files.length > 0) {
    messages[0].content += '\n\n' + formatContextFiles(context.files);
  }
  
  // 执行 Query Loop
  let finalResponse = '';
  
  for await (const event of query(messages, context.tools, {
    system: systemPrompt,
    model: context.model,
  })) {
    if (event.type === 'content') {
      finalResponse += event.content;
    }
  }
  
  return {
    success: true,
    output: finalResponse,
  };
}

特点

• 阻塞执行，等待完成

• 返回完整结果

• 适合需要结果的任务

异步执行

实现

async function executeAsyncAgent(
  input: AgentInput,
  context: AgentContext,
  systemPrompt: string
): Promise<ToolResult> {
  // 创建 worktree
  const worktree = await createWorktree(context.cwd);
  
  // 在后台启动 Agent
  const agentId = generateId();
  
  backgroundAgents.set(agentId, {
    status: 'running',
    worktree: worktree,
    startTime: Date.now(),
  });
  
  // 异步执行
  executeAgentInBackground(agentId, input, context, systemPrompt)
    .then(result => {
      backgroundAgents.get(agentId).status = 'completed';
      backgroundAgents.get(agentId).result = result;
    })
    .catch(error => {
      backgroundAgents.get(agentId).status = 'failed';
      backgroundAgents.get(agentId).error = error;
    });
  
  return {
    success: true,
    output: `Agent ${agentId} started in background. Use 'agent status ${agentId}' to check progress.`,
  };
}

特点

• 非阻塞执行

• 使用 worktree 隔离

• 适合长时间运行的任务

Worktree 隔离

创建 Worktree

async function createWorktree(basePath: string): Promise<string> {
  const worktreePath = path.join(
    basePath,
    '.git',
    'worktrees',
    `agent-${Date.now()}`
  );
  
  await exec(`git worktree add ${worktreePath}`);
  
  return worktreePath;
}

清理 Worktree

async function cleanupWorktree(worktreePath: string): Promise<void> {
  await exec(`git worktree remove ${worktreePath}`);
}

Context Gatherer

专门的代码分析 Agent

// context-gatherer 的 System Prompt
const CONTEXT_GATHERER_PROMPT = `
You are a specialized agent for analyzing codebases.

Your goal is to identify relevant files and code sections for a given issue.

Available tools:
- readCode: Read code structure
- fileSearch: Find files by name
- grepSearch: Search for patterns
- listDirectory: Explore directories

Process:
1. Understand the issue
2. Search for relevant files
3. Read code structure
4. Identify key files and sections
5. Return a focused list of relevant files
`;

使用示例

// 用户: "修复登录 bug"

// 主 Agent 调用 context-gatherer
const result = await invokeSubAgent({
  name: 'context-gatherer',
  prompt: '找出与登录功能相关的所有文件',
  explanation: '需要定位登录相关代码',
}, context);

// context-gatherer 返回:
// - src/auth/login.ts
// - src/components/LoginForm.tsx
// - src/api/authApi.ts

// 主 Agent 继续处理这些文件

Agent 通信

消息传递

interface AgentMessage {
  from: string;  // Agent ID
  to: string;    // Agent ID
  type: 'request' | 'response' | 'notification';
  payload: any;
}

async function sendToAgent(
  targetAgent: string,
  message: AgentMessage
): Promise<void> {
  const agent = backgroundAgents.get(targetAgent);
  agent.messageQueue.push(message);
}

结果聚合

async function aggregateAgentResults(
  agentIds: string[]
): Promise<AggregatedResult> {
  const results = await Promise.all(
    agentIds.map(id => waitForAgent(id))
  );
  
  return {
    success: results.every(r => r.success),
    outputs: results.map(r => r.output),
    summary: summarizeResults(results),
  };
}

下一步

• 了解 Swarm 模式 的多 Agent 协作

• 探索 Coordinator 的任务编排

• 查看 其他核心工具