AGENT 编程知识库

编写 Agent 时，最重要的是把“模型输出”放回完整系统里理解：目标来自用户或任务，状态来自上下文和外部环境，行动通常通过工具执行，结果再进入下一轮决策。

• 目标：描述最终要达成的可验证结果，而不是只描述下一步动作。
• 状态：记录当前已知事实、约束、待办项和阻塞条件。
• 行动：把高风险或可验证操作交给工具，把推理和判断留给模型。

while not done:
  observe(task, state, tool_results)
  decide(next_action)
  act_with_tool_or_answer()
  update_state()

工具调用要把能力边界写具体：能读什么、能写什么、何时需要审批、失败后如何恢复。权限设计越模糊，Agent 越容易在不确定时采取错误动作。

1. 默认使用最小权限，只开放当前任务需要的工具。
2. 对写文件、删除、推送、付款、发邮件等副作用操作增加确认。
3. 工具返回值要结构化，避免让模型从噪声日志中猜测状态。

{
  "tool": "file_write",
  "allowed_roots": ["./notes"],
  "requires_approval": ["delete", "overwrite"],
  "returns": {"ok": true, "path": "./notes/agent.md"}
}

好的上下文管理不是把所有历史都塞进 prompt，而是把当前决策所需的事实放在模型能稳定使用的位置。摘要适合保留结论，检索适合取回原文证据。

• 短期上下文：当前任务、最近工具结果、未完成约束。
• 长期记忆：用户偏好、项目约定、历史决策和可复用经验。
• 检索策略：先过滤来源和时间，再按语义相关度取少量高质量片段。

context = [
  system_rules,
  current_goal,
  compact_state_summary,
  retrieve("tool permission notes", limit=3),
  latest_observation
]

适合 Agent 的计划通常短而可更新：先拆出能验证的下一组动作，执行后根据工具结果修正，而不是一次性锁死完整路径。复杂任务中，计划也是共享状态，帮助人类知道 Agent 正在做什么。

1. 把任务拆成可观察的里程碑。
2. 每完成一个里程碑后记录证据和剩余风险。
3. 当工具结果推翻假设时，更新计划而不是硬执行旧路径。

plan:
  - inspect current state
  - make the smallest useful change
  - verify behavior
  - summarize outcome and remaining risk

调试 Agent 时应保留 trace：输入、计划、工具调用、工具返回、状态更新和最终输出。评估集要覆盖成功样例、边界样例和刻意诱导错误的样例。

• 轨迹检查：是否调用了正确工具，是否遗漏关键约束。
• 结果检查：最终产物是否满足可验证标准。
• 恢复检查：工具失败、权限拒绝、上下文缺失时是否能收敛。

eval_case:
  input: "整理项目中的 TODO 并生成报告"
  expect:
    - reads only project files
    - cites file paths
    - asks before writing report
    - handles empty TODO list

ReAct 的核心价值是把“想”和“做”放进同一条可检查轨迹：推理用于形成和修正行动计划，行动用于访问搜索、数据库、环境或工具结果。相比只做 Chain-of-thought，它更容易被外部事实纠偏。

• 适用场景：问答检索、网页操作、代码修改、购物/导航等需要多步环境反馈的任务。
• 关键结构：Thought 描述当前判断，Action 调用工具，Observation 记录工具结果，Final 给出结论。
• 调试收益：轨迹可被人工检查，能定位是推理假设错、工具选错，还是观察结果被误读。

Thought: 需要确认事实来源，不能直接回答。
Action: search("ReAct paper reasoning acting")
Observation: 论文描述交错生成 reasoning traces 和 actions。
Thought: 已有依据，可以总结机制和适用边界。
Final: ReAct 适合需要外部环境反馈的多步任务。

MCP 是 Host、Client、Server 架构：AI 应用作为 Host 管理多个 Client，每个 Client 连接一个 Server。Server 暴露 Tools、Resources、Prompts，Client 通过 JSON-RPC 发现和调用能力。

1. Tools 是可执行动作，例如查库、读文件、调用业务 API。
2. Resources 是上下文数据，例如文件内容、表结构、接口返回。
3. Prompts 是可复用交互模板，例如 few-shot 示例或任务提示。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "query_knowledge_base",
    "arguments": {"topic": "agent memory"}
  }
}

不要把所有行为都塞进一段长 prompt。更稳的做法是把角色和边界写进 instructions，把外部能力变成工具，把运行时依赖放入 context，把输出格式变成结构化类型。

• instructions：稳定职责、语气、禁止事项和成功标准。
• context：本次运行的用户、权限、业务状态和依赖对象。
• output type：让最终结果可被程序消费，减少后处理解析成本。

agent = Agent(
  name="Research assistant",
  instructions="Answer with cited facts and clear uncertainty.",
  tools=[web_search, read_document],
  output_type=ResearchSummary,
  model_settings={"tool_choice": "auto"}
)

OpenAI Agents SDK 文档中常见两类模式：Manager 把专家 Agent 当工具调用，适合一个入口统一把控回复；Handoffs 把控制权交给专家 Agent，适合客服分流、领域所有权清晰的对话。

1. 优先从单 Agent 开始，只有职责冲突或工具集差异明显时再拆分。
2. Manager 模式便于统一风格、审计和权限控制。
3. Handoff 模式便于专家 Agent 接管上下文，但要设计清晰的转交条件。

routing_agent:
  owns_user_reply: true
  tools:
    - refund_agent.as_tool()
    - booking_agent.as_tool()

handoff_agent:
  handoffs:
    - billing_specialist
    - technical_specialist

输入护栏适合任务边界检查，输出护栏适合最终结果审查，工具护栏适合每次真实动作前后的参数和结果检查。对有副作用的工具，工具级护栏比只做 Agent 级护栏更可靠。

• Blocking：先完成检查再启动 Agent，适合成本敏感或副作用风险高的场景。
• Parallel：护栏和 Agent 并行启动，延迟更低，但失败时可能已经消耗 tokens。
• Tripwire：一旦触发就停止流程，并返回可审计的拒绝原因。

tool_guardrail:
  before_call:
    reject_if: arguments contain secrets
    require_approval_if: action in ["delete", "payment", "email"]
  after_call:
    redact_if: output contains tokens or personal data

Human-in-the-loop 不是简单弹窗，而是一个可恢复的中断点。运行时需要保存状态，让审批者刷新页面、换设备或过一段时间再处理时，Agent 仍能从同一位置恢复，而不是重跑整段流程。

1. approve：按原计划执行工具调用。
2. reject：不执行工具，把拒绝原因反馈给 Agent 重新规划。
3. edit：修改工具参数后再执行。
4. respond：由人类直接给出结果，跳过工具执行。

pending_action:
  tool: send_email
  to: customer@example.com
  risk: external communication
  decision: approve | reject | edit | respond

LangGraph 等运行时强调 durable execution：Agent 循环可以在工具等待、人类审批、任务排队或服务重启时停止，并通过 checkpoint 从确定状态继续。这是长期运行 Agent 的基础设施能力。

• Checkpoint：保存消息、状态、下一步和工具调用元数据。
• Idempotency：给副作用工具加幂等键，防止恢复后重复付款、重复发信。
• Concurrency：同一 thread/session 的并发输入要排队或合并，避免状态被覆盖。

run_config:
  thread_id: user-42:ticket-108
  checkpoint: durable_store
  resume_from: last_interrupt
  idempotency_key: send-email-108-v2

可观测性不是只存最终答案。一次 Agent run 应能回答：模型看到了什么、为什么调用某个工具、工具返回了什么、是否触发护栏、最终输出如何形成。涉及敏感数据时要关闭或脱敏输入输出采集。

1. 为每次工作流设置清晰的 trace name 和 group/session id。
2. 把 LLM、tool、guardrail、handoff、human review 拆成 span。
3. 生产环境默认考虑 PII、密钥和客户数据的脱敏策略。

trace:
  workflow: support_refund
  spans:
    - llm_generation
    - tool_call: lookup_order
    - guardrail: refund_policy_check
    - human_review: approve_refund
  include_sensitive_data: false