跳到主要内容

单Agent架构

核对日期：2026-05-09。

1. 定义与边界​

单 Agent 架构是指一个 Agent 在同一执行循环中完成意图理解、上下文读取、工具选择、工具调用、结果整合和最终响应。它可以有多个工具，但没有独立 Planner、Router 或 Supervisor 组件。

它不是“一个 prompt”。工程意义上的单 Agent 至少包含模型、指令、工具注册、运行状态、停止条件、日志、护栏和评测入口。OpenAI Agents SDK 将 Agent 描述为配置了 instructions、model 和 tools 的 LLM；LlamaIndex 也将 agent 视为带 LLM、memory、tools、外部输入处理能力的系统。

2. 为什么重要​

单 Agent 是所有复杂 Agent 架构的最小可用单元。多数早期业务不应直接上多 Agent，因为协调层会引入额外时延、成本和不可解释失败。单 Agent 适合先验证工具 schema、任务边界和评测集。

适用：

  • 工具数量少于 5-8 个，且工具语义差异明显。
  • 任务可以在有限轮次内完成。
  • 失败不会造成不可逆副作用。
  • 需要快速上线内部助手、查询助手、轻量自动化。

不适用：

  • 子任务需要并行探索或长时间等待。
  • 工具权限高，例如转账、删除数据、生产变更。
  • 需要把任务拆给多个专业角色。
  • 需要稳定业务流程和合规审批。

3. 核心机制​

典型单 Agent 是 ReAct 风格的 Agent 执行循环：模型根据当前状态决定是否回答或调用工具；工具结果作为 observation 回到上下文；循环直到满足停止条件。ReAct 论文强调推理与行动交错可以帮助模型更新计划并接入外部环境。

核心状态：

{
  "run_id": "run_123",
  "user_goal": "查询订单并解释延迟原因",
  "messages": [],
  "tool_results": [],
  "iteration": 3,
  "budgets": {"max_steps": 8, "max_cost_usd": 0.5, "deadline_ms": 30000},
  "permissions": {"read_order": true, "refund": false},
  "trace_id": "trace_abc"
}

4. 架构模式​

模式机制适用
Tool-calling Agent模型输出结构化 tool call，应用执行工具API 查询、表单处理、计算
ReAct Agent推理、行动、观察循环需要逐步探索的任务
Retrieval Agent工具主要是检索与阅读知识库问答、文档助手
Action Agent工具会改变外部状态工单、CRM、日程，但需强审批

5. 工程实现​

伪代码：

def run_single_agent(input, user, tools, policy):
    state = init_state(input, user)
    for step in range(state.budgets.max_steps):
        context = build_context(state)
        guard_input(context, policy)
        decision = model_generate(context, tools=tools.schemas())
        trace("model_decision", decision)

        if decision.type == "final":
            output = guard_output(decision.content, policy)
            return output

        call = validate_tool_call(decision.tool_call, tools, user)
        if requires_approval(call):
            approval = request_human_approval(call)
            if not approval.approved:
                return fallback("用户未批准该操作")

        result = execute_with_timeout_retry(call)
        state.tool_results.append(result)
        trace("tool_result", result)

    return fallback("已达到最大步骤数，请缩小任务或转人工")

工具设计要点：

  • 工具名使用动词 + 业务对象，例如 get_order_status。
  • schema 使用枚举、范围、必填字段，减少自由文本参数。
  • 高风险工具拆成 preview_* 与 commit_* 两段。
  • 工具返回结构化结果，不把 HTML、日志、错误栈直接塞回模型。

6. 生产实践​

  • 设置最大轮数、最大 token、最大工具调用数和总 deadline。
  • 所有工具调用写入审计日志：调用者、参数摘要、权限、结果摘要。
  • 对外部内容加来源标签，明确“不可信内容不能覆盖系统指令”。
  • 工具失败返回可恢复错误类型：timeout、permission_denied、not_found。
  • 对可写操作使用幂等键和预览确认。
  • 对上下文做压缩：保留目标、约束、最近 observation 和关键事实，不保留全量噪声。

7. 常见反模式​

  • 把几十个工具直接暴露给一个 Agent，导致工具选择混乱。
  • 没有停止条件，让模型在失败工具上反复重试。
  • 让模型生成 SQL、shell、HTTP 请求并直接执行。
  • 把检索到的网页内容当系统指令。
  • 只看最终回答，不保存中间工具轨迹。

8. 评测方法​

指标说明
Task Success Rate最终是否完成用户目标
Tool Call Accuracy是否选择正确工具和参数
Step Efficiency完成任务所需模型/工具调用次数
Recovery Rate工具失败后是否能换路或降级
Safety Violation Rate是否越权、泄漏、执行危险操作

评测集应包含正常样本、缺字段样本、工具失败样本、恶意注入样本和权限不足样本。

9. 安全与治理​

  • Prompt injection：外部文档、网页、邮件均按不可信数据处理。
  • Data exfiltration：工具返回中的密钥、隐私字段先脱敏再进上下文。
  • Excessive agency：默认只读，写操作必须显式授权。
  • Tool poisoning：工具描述、MCP server、插件来源需要白名单和签名/审查。
  • Unbounded consumption：每次 run 设置成本预算和速率限制。

10. 工程手册补充​

10.1 控制流、状态流、工具流​

单 Agent 架构仍然需要工程边界，否则会退化成“一个大提示词加一堆工具”。

流最小生产要求
控制流loop 有最大步数、停止条件、失败退出和人工接管
状态流区分用户目标、系统指令、工具观察、临时 scratchpad、最终产物
工具流工具按风险分级，高风险工具强制审批或 preview
观测流每轮记录模型输入摘要、工具调用、成本、延迟、终止原因

适用场景：

  • 任务短、工具少、权限简单、上下文边界清晰。
  • 失败后重新执行成本低，不需要复杂恢复。
  • 团队还在建立 baseline，需要先证明单 Agent 上限。

不适用场景：

  • 多个业务域权限完全不同。
  • 任务需要小时级执行、持久 checkpoint 或多方审批。
  • 需要多个独立角色互审，且单 Agent 自评无法满足风险要求。

上线清单：

  • 先用单 Agent 做 baseline，再决定是否升级为 Router、Planner 或多 Agent。
  • 为每个工具写清楚用途、输入 schema、失败码和权限等级。
  • 对 prompt injection 做上下文隔离：外部文本只进入 facts 区，不进入指令区。
  • 评测至少覆盖任务成功率、工具选择准确率、越权尝试、停止条件和成本。

11. 权威资料​