Agent 工具学习记录

学习日期：2026-03-13
所属阶段：阶段二 - 进阶技能

---

Agent 工具概述

Agent 是 Claude Code 的子代理工具，用于执行复杂、多步骤或需要独立处理的任务。

Agent vs 直接工具调用

特性	直接工具调用	Agent
执行方式	当前对话中执行	创建独立子进程
复杂度	简单、单步骤	复杂、多步骤
上下文	共享当前上下文	独立的上下文
并行性	顺序执行	可并行执行多个
适用场景	即时、简单的操作	耗时、独立的研究任务

---

参数说明

参数	类型	必需	说明
description	string	✅	简短任务描述（3-5个词）
prompt	string	✅	详细任务说明
subagent_type	string	❌	指定 Agent 类型
model	string	❌	指定模型（sonnet/opus/haiku）
isolation	string	❌	隔离模式（"worktree"）
run_in_background	boolean	❌	后台运行
resume	string	❌	恢复指定 Agent

---

内置 Agent 类型

类型	用途
Explore	代码库探索，快速查找文件和代码
Plan	制定实现计划
general-purpose	通用任务（默认）
claude-code-guide	Claude Code 相关问题
superpowers:code-reviewer	代码审查

---

使用场景

场景 1：代码库探索

需求：在项目中查找所有使用 Toast 的地方

使用 Agent：

Agent(
  description="查找 Toast 使用",
  prompt="在项目中搜索所有使用 Toast 的地方，包括：
  1. 查找导入语句 import android.widget.Toast
  2. 查找 Toast.makeText 调用
  3. 返回每个使用的文件路径、行号和代码片段
  4. 总结总共有多少处使用",
  subagent_type="Explore"
)

为什么用 Agent：
- 需要搜索多个模式
- 结果需要整理汇总
- 耗时操作，独立执行不阻塞主对话

---

场景 2：并行任务处理

需求：同时分析多个文件

使用多个 Agent：

# Agent 1：分析 UserRepository
Agent(
  description="分析 UserRepository",
  prompt="分析 UserRepository.kt 文件：
  1. 列出所有公共方法
  2. 检查是否有异常处理
  3. 返回方法列表和建议"
)

# Agent 2：分析 UserViewModel
Agent(
  description="分析 UserViewModel",
  prompt="分析 UserViewModel.kt 文件：
  1. 列出所有公共方法
  2. 检查是否正确使用 Repository
  3. 返回方法列表和建议"
)

# Agent 3：分析 UserAdapter
Agent(
  description="分析 UserAdapter",
  prompt="分析 UserAdapter.kt 文件：
  1. 检查 ViewHolder 实现
  2. 检查是否有内存泄漏风险
  3. 返回分析和建议"
)

为什么用 Agent：
- 三个文件分析相互独立
- 可以并行执行，节省时间
- 每个 Agent 返回结构化结果

---

场景 3：复杂研究任务

需求：研究项目中网络请求的实现方式

使用 Agent：

Agent(
  description="研究网络请求实现",
  prompt="研究项目中网络请求的实现方式：

  1. 查找使用的网络库（Retrofit、OkHttp、Volley 等）
  2. 查找网络请求的封装类
  3. 查找拦截器的实现
  4. 查找错误处理方式
  5. 查找请求/响应的数据模型

  要求：
  - 列出所有相关文件
  - 说明每个文件的作用
  - 绘制简单的架构图
  - 给出使用示例"
)

为什么用 Agent：
- 任务复杂，需要多步骤搜索
- 需要整理和总结
- 可能涉及多个目录和文件

---

场景 4：代码审查

需求：审查修改的代码

使用 Agent：

Agent(
  description="审查代码修改",
  prompt="审查最近修改的代码：
  1. 运行 git diff 查看变更
  2. 检查代码质量问题
  3. 检查是否有重复代码
  4. 检查是否有潜在 Bug
  5. 给出改进建议",
  subagent_type="superpowers:code-reviewer"
)

---

实践案例

案例 1：简单探索

任务：查找项目中所有的 Activity 类

执行：

Agent(
  description="查找所有 Activity",
  prompt="在项目中查找所有 Activity 类：
  1. 搜索继承自 AppCompatActivity 或 Activity 的类
  2. 列出每个 Activity 的名称和文件路径
  3. 统计总共有多少个 Activity"
)

预期结果：
- 返回所有 Activity 的列表
- 包含文件路径
- 统计数量

---

案例 2：使用 Explore Agent

任务：快速了解项目结构

执行：

Agent(
  description="探索项目结构",
  prompt="快速探索项目结构：
  1. 列出主要的源代码目录
  2. 找出核心模块和组件
  3. 识别使用的框架和库
  4. 返回项目架构概览",
  subagent_type="Explore"
)

特点：
- Explore Agent 专门用于代码库探索
- 比通用 Agent 更快
- 适合快速了解未知项目

---

案例 3：并行 Agents

任务：同时分析多个工具类

执行：

# 同时启动多个 Agent

Agent(description="分析日志工具", prompt="分析 LogUtil.kt...")
Agent(description="分析网络工具", prompt="分析 NetworkUtil.kt...")
Agent(description="分析存储工具", prompt="分析 StorageUtil.kt...")

结果处理：
- 等待所有 Agent 完成
- 汇总各自的结果
- 生成综合分析报告

---

最佳实践

✅ 推荐使用 Agent 的场景

1. 耗时任务 - 避免阻塞主对话
2. 独立任务 - 与其他任务无依赖
3. 复杂搜索 - 需要多步骤搜索和整理
4. 并行处理 - 多个独立任务同时执行
5. 代码探索 - 研究未知代码库

❌ 避免使用 Agent 的场景

1. 简单操作 - 直接用工具更快
2. 需要即时反馈 - Agent 是异步的
3. 上下文依赖 - 需要当前对话的完整上下文

---

Agent 工作流程

启动 Agent
    ↓
创建独立子进程
    ↓
执行任务（独立于主对话）
    ↓
返回结果
    ↓
主对话继续

---

与 Task 的区别

特性	Task	Agent
用途	跟踪任务进度	执行具体任务
创建	TaskCreate	Agent 工具
状态	pending/in_progress/completed	运行中/完成
关系	用于项目管理	用于任务执行

可以同时使用：
- Task 跟踪项目进度
- Agent 执行具体任务

---

常见问题

Q1: Agent 和直接调用工具有什么区别？

A: Agent 创建独立进程，适合复杂/耗时任务；直接调用在当前对话执行，适合简单/即时任务。

Q2: 如何选择 Agent 类型？

A:
- 代码探索 → Explore
- 制定计划 → Plan
- 代码审查 → superpowers:code-reviewer
- 其他 → general-purpose（默认）

Q3: 如何获取 Agent 结果？

A: Agent 完成时会自动返回结果，如果需要等待，使用 TaskOutput 工具。

Q4: 可以启动多少个 Agent？

A: 可以并行启动多个，但要注意系统资源和上下文限制。

Q5: Agent 失败了怎么办？

A: 可以重新启动，或使用 resume 参数恢复。

---

学习检查点

• [ ] 理解 Agent 和直接工具调用的区别
• [ ] 掌握 Agent 的基本参数
• [ ] 知道何时使用 Agent
• [ ] 能够使用不同类型的 Agent
• [ ] 能够并行使用多个 Agent

掌握度：⭐⭐⭐

---

下一步实践

1. 使用 Agent 探索代码库
2. 并行启动多个 Agent 分析不同文件
3. 结合 Plan Mode 使用 Agent 执行计划

---

相关文档：
- 008-07-技能系统学习