agent-development

Agent 开发

概述

设计并构建能够有效使用工具、管理记忆、规划多步骤任务、与其他 Agent 协调，并在安全防护措施范围内运行的 AI Agent。本技能涵盖从架构设计到评估的完整 Agent 开发生命周期，重点关注可观测、可测试且安全的 Agent 行为。

阶段 1：Agent 设计

1. 定义 Agent 的用途和范围
2. 确定所需的工具和能力
3. 设计记忆架构（短期、长期）
4. 规划 Agent 循环结构（观察、思考、行动）
5. 定义安全边界和防护措施

停止 — 在开始实施前，向用户展示 Agent 设计并征求批准。

Agent 架构决策表

Agent 类型	适用场景	循环模式	复杂度
单轮工具调用 Agent	带工具调用的简单查询	请求 -> 工具 -> 响应	低
ReAct Agent	多步骤推理任务	思考 -> 行动 -> 观察 -> 循环	中
规划并执行	有依赖关系的复杂任务	规划 -> 执行步骤 -> 验证	中高
多 Agent 编排器	并行或专业化子任务	分派 -> 收集 -> 综合	高
自主循环（Ralph 风格）	长时间运行的迭代开发	规划 -> 构建 -> 验证 -> 退出关卡	高

阶段 2：实施

1. 构建带工具分派的 Agent 循环
2. 实现记忆管理（上下文窗口、持久化）
3. 添加规划和任务分解逻辑
4. 集成错误恢复和重试模式
5. 实现输出验证

停止 — 在增加复杂性之前，对 Agent 循环运行冒烟测试。

工具使用模式

工具定义最佳实践

原则	规则	示例
命名清晰	动词-名词格式	search_documents, create_file
描述详尽	说明何时使用以及何时不要使用	"用于关键词搜索。不要用于语义相似度搜索。"
参数类型明确	为每个参数提供描述和示例	query: string // "e.g., 'user authentication'"
返回值可预测	各工具采用一致的格式	始终返回 { success, data, error }
错误可自我纠正	帮助 Agent 恢复	"日期格式无效。应为 ISO 8601：YYYY-MM-DD"

工具选择策略

Given a task:
1. Identify required information and actions
2. Map to available tools
3. Determine tool call order (dependencies)
4. Execute with result validation
5. Retry or try alternative tool on failure

工具设计原则

• 可组合：工具应小巧，可组合完成复杂任务
• 幂等：可安全重试且不会产生副作用（尽可能如此）
• 可观测：返回足够的上下文，供 Agent 验证是否成功
• 有界：为所有操作设置超时和大小限制
• 有文档说明：描述每个参数和返回值

记忆管理

记忆类型决策表

类型	持续时间	存储	使用场景
工作记忆	当前轮次	上下文窗口	活跃推理
短期记忆	当前会话	上下文内或缓冲区	最近的对话
长期记忆	跨会话	数据库/文件	学到的模式、用户偏好
情景记忆	特定事件	索引存储	过去的任务结果
语义记忆	知识	向量数据库	领域知识检索

上下文窗口管理

Strategy: Sliding window with importance-based retention

1. Always retain: system prompt, tool definitions, current task
2. Summarize: older conversation turns into compressed summaries
3. Evict: least relevant context when approaching limit
4. Retrieve: pull relevant long-term memory on demand

Budget allocation:
  System prompt + tools: ~20%
  Current task context:  ~40%
  Conversation history:  ~25%
  Retrieved memory:      ~15%

记忆更新触发条件

触发条件	操作
用户纠正	更新学到的模式
任务完成	保存结果和处理方法
错误恢复	记录失败之处和有效做法
新的领域知识	建立索引以便未来检索

规划策略

分层任务分解

1. Break high-level goal into sub-goals
2. For each sub-goal, identify required actions
3. Order actions by dependencies
4. Execute with checkpoints between phases
5. Re-plan if intermediate results change the approach

ReAct 模式（推理 + 行动）

Thought: I need to find the user's recent orders to answer their question.
Action: search_orders(user_id="123", limit=5)
Observation: Found 5 orders, most recent is #456 from yesterday.
Thought: The user asked about order #456. I have the details now.
Action: respond with order details

规划并执行模式

1. Create a complete plan before any action
2. Execute each step, checking preconditions
3. After each step, validate the result
4. If a step fails, re-plan from current state
5. Never modify the plan mid-step (finish or abort first)

反思模式

After completing a task:
1. Was the result correct?
2. Was the approach efficient?
3. What could be improved?
4. Should any memory be updated?

阶段 3：评估与安全

1. 构建包含测试场景的评估框架
2. 衡量准确性、效率和安全指标
3. 测试边界情况和对抗性输入
4. 添加监控和日志记录
5. 为失控行为实现熔断机制

停止 — 部署前必须测试所有安全护栏。

多 Agent 协调

协调模式决策表

模式	描述	适用场景
编排器	中央 Agent 将任务委派给专用 Agent	任务层级明确
流水线	Agent 按顺序处理	线性工作流
辩论	Agent 提出方案并进行评议	需要多元视角
投票	多个 Agent 参与，少数服从多数	方案存在不确定性
监督者	一个 Agent 监控其他 Agent	对安全要求极高的任务

通信协议

Agent-to-Agent message:
{
  "from": "planner",
  "to": "executor",
  "type": "task_assignment",
  "content": { "task": "...", "context": "...", "constraints": "..." },
  "priority": "high",
  "deadline": "2025-01-15T10:00:00Z"
}

协调规则

• 明确划分所有权边界
• 在 Agent 之间使用结构化消息
• 实现死锁检测
• 为 Agent 间通信设置超时
• 记录所有 Agent 间消息以便调试

评估框架

指标决策表

指标	衡量内容	衡量方式	目标
任务成功率	正确完成数 / 总数	自动评估 + 人工评估	> 90%
效率	实际步骤数与最优路径的对比	步骤数比较	< 2x 最优值
工具准确率	正确工具调用数 / 总数	日志分析	> 95%
安全性	违规次数 / 总交互次数	安全护栏检查	0 次违规
延迟	完成任务所需时间	墙上时钟	< SLA
成本	每项任务的令牌用量	API 用量跟踪	不超预算

评估数据集结构

{
  "test_cases": [
    {
      "id": "tc_001",
      "input": "Find all orders over $100 from last week",
      "expected_tools": ["search_orders"],
      "expected_output_contains": ["order_id", "amount"],
      "category": "retrieval",
      "difficulty": "easy"
    }
  ]
}

安全护栏

输入护栏

• 检测并拒绝提示词注入尝试
• 处理前验证所有用户输入
• 按用户／会话限制请求频率
• 过滤有害请求内容

输出护栏

• 执行前验证工具调用参数
• 检查输出是否包含敏感信息（PII、机密）
• 强制执行响应格式约束
• 防止无限工具调用循环

运行护栏

• 每项任务的最大工具调用次数（熔断机制）
• 每条响应的最大令牌数
• 整个任务时长的超时限制
• 置信度较低时转交人工处理
• 对所有操作进行审计日志记录

熔断阈值

条件	阈值	操作
每项任务的最大工具调用次数	20	停止执行，返回错误
最大连续错误数	3	停止、记录日志并返回可恢复的错误
最长任务时长	5 分钟	超时，返回部分结果
生成的最大令牌数	10,000	停止生成
模式重复	5 次相同错误	打开熔断器并提醒操作员

Agent 提示词工程

系统提示词结构

1. Identity and purpose (who the agent is)
2. Available tools (what it can do)
3. Constraints (what it must not do)
4. Output format (how to respond)
5. Examples (few-shot demonstrations)
6. Error handling (what to do when stuck)

关键提示词模式

• 草稿区：鼓励在采取行动前逐步推理
• 自我纠正：“如果你的首种方法失败，请尝试……”
• 置信度校准：“只有在你有把握时才继续”
• 优雅降级：“如果无法完成任务，请说明原因”

反模式 / 常见错误

反模式	错误原因	应对方法
未经推理就调用工具	浪费调用，遗漏上下文	使用 ReAct 模式（先思考）
未设置最大迭代次数	导致无限循环、成本失控	设置熔断阈值
信任所有工具输出	错误数据会持续传播	验证工具结果
硬编码工具调用顺序	无法适应故障	根据状态动态选择工具
没有错误恢复策略	Agent 会在首次失败时卡住	实现重试，并提供替代方案
只道歉，不采取行动	浪费用户时间	采取纠正措施，然后汇报
过度依赖单一工具	该工具一旦故障，系统就很脆弱	提供备用工具
没有评估框架	盲目上线，缺乏质量反馈	部署前构建评估测试框架
上下文无限增长	上下文溢出，质量下降	实施记忆管理

集成点

技能	集成方式
mcp-builder	MCP 服务为 Agent 提供工具
planning	Agent 规划使用结构化计划生成
autonomous-loop	Ralph 风格循环是一种专门的 Agent 模式
dispatching-parallel-agents	多 Agent 协调模式
circuit-breaker	为 Agent 循环提供运行安全保障
verification-before-completion	验证 Agent 输出
test-driven-development	对 Agent 工具实现采用 TDD

技能类型

FLEXIBLE — 根据具体用例调整 Agent 架构、记忆策略和协调模式。强烈建议所有生产环境中的 Agent 都设置安全防护措施并采用评估框架。