[!info] related notes

• 所属 MOC: AI Agent Application MOC, Agent MOC
• 上游概念: Agent, Augmented LLM
• 并列概念: Agentic Application Stack
• 下游概念: Agent Runtime, Tool Calling 工程化, Context Engineering

AI Agent Application

一句话定义

AI Agent Application 是以 LLM 为推理核心、以工具调用为执行手段、以状态管理为控制基础的交互式智能应用。其特点是部分动作选择由模型动态提出，再由代码定义的工具、权限和停止规则控制执行；不是把整个控制流和业务授权交给模型。

它解决什么问题

预定义业务流程适合已知步骤，而以下任务可能受益于模型在执行中选择下一步：

• 用户用自然语言描述复杂需求（“帮我分析这个数据集的趋势”）
• 任务需要多步推理和动态决策（“先搜索相关信息，再整理成报告”）
• 执行路径取决于中间结果（“如果检索到的内容不够，换个关键词再搜”）

LLM 可以提出工具选择、顺序和完成判断；runtime 必须验证这些提议，并保留独立的预算、取消、授权和终态控制。

核心原理

与传统应用的本质区别

传统应用:
  用户输入 → 预定义逻辑 → 输出
  (控制流在代码中)

AI Agent 应用:
  用户输入 → LLM 推理 → 动态选择工具 → 执行 → 结果回传 LLM → 继续推理或输出
  (模型提出动态动作，运行时与业务规则约束执行)

核心组成

常见组成如下；长期记忆、RAG 和图形交互界面按任务选用，后台 Agent 也可以只暴露 API 或任务入口：

组件	职责	例子
LLM	推理与决策	GPT-4, Claude
Tools	执行具体动作	搜索、数据库查询、API 调用
Context / State	提供调用上下文并维护权威执行状态	必要消息、run state；长期记忆可选
Runtime	管理执行循环	超时、重试、并发、权限控制
Interface	用户交互层	Chat UI、审批界面、结果展示

Anthropic 的分类

Anthropic 在 “Building Effective Agents” 中区分了两类系统：

• Workflow: 通过预定义代码路径编排 LLM 和工具（确定性控制流）
• Agent: LLM 动态决定自己的执行流程（模型控制流）

两者可以组合，例如在预定义 workflow 中嵌入模型动态选择动作的节点；不能由此断言所有生产应用都采用同一种结构。

在 React + Go + Python AI Service 架构中的位置

下图是一种分工方案，完整取舍见 agentic-application-stack；语言和进程并非概念成立的前提。

┌─────────────────────────────────────────────┐
│  React 前端                                  │
│  - Chat UI (消息输入/输出)                    │
│  - Tool Call UI (工具调用状态展示)            │
│  - Human Approval UI (审批界面)               │
│  - Artifact Viewer (结果/文件查看)            │
│  - SSE Client (流式事件消费)                  │
└──────────────────┬──────────────────────────┘
                   │ HTTP / SSE
                   ▼
┌─────────────────────────────────────────────┐
│  Go 后端 (BFF 层)                            │
│  - Session & Message 管理                    │
│  - Context Builder (上下文组装)              │
│  - SSE Gateway (流式事件转发)                │
│  - Auth & RBAC (权限控制)                    │
│  - Audit Log (审计日志)                      │
│  - Event Contract (事件协议)                 │
└──────────────────┬──────────────────────────┘
                   │ gRPC / HTTP + SSE
                   ▼
┌─────────────────────────────────────────────┐
│  Python AI Service (Agent 引擎)              │
│  - Agent Runtime (执行循环)                  │
│  - Tool Registry & Executor                  │
│  - RAG Engine (检索增强生成)                  │
│  - Memory Manager (记忆管理)                 │
│  - LLM Provider Abstraction                 │
│  - Trace & Observability                    │
└─────────────────────────────────────────────┘

典型工程实现

一次 Agent 调用的完整流程

1. 用户在 Chat UI 输入: "帮我查一下最近一周的销售数据，做个趋势分析"
2. React 前端发送 POST /api/chat/message
3. Go 后端:
   a. 鉴权、创建 turn_id
   b. ContextBuilder 组装上下文（历史消息 + 用户画像 + 工具列表）
   c. 转发请求到 Python AI Service
   d. 开始 SSE 流式转发
4. Python AI Service:
   a. Agent Runtime 启动 Run
   b. LLM 推理: 决定先调用 query_database 工具
   c. Tool Executor 执行数据库查询
   d. 结果回传 LLM
   e. LLM 推理: 决定调用 create_chart 工具生成图表
   f. Tool Executor 生成图表
   g. LLM 生成最终文本回复
   h. Run 完成
5. Go 后端通过 SSE 逐步转发事件到前端
6. React 前端渲染: 文本 + 图表 + 工具调用状态

Agent Loop 的关键约束

最小循环见 Agent Engine。应用层需额外核对：

• assistant 的工具调用消息与对应 call ID 的工具结果都进入后续上下文。
• 拒绝执行的调用必须得到明确结果或使 run 终止，不能留下无结果的调用后无限重试。
• 步数、总时限与费用预算由 runtime 维护，不依赖模型自行更新计数或停止。
• 最终回复、工具产物和业务状态变更经过各自的交付与授权检查。

常见设计模式

1. 单 Agent 模式: 一个 LLM + 一组工具，适合简单任务
2. Multi-Agent 模式: 多个 Agent 协作，每个负责一个子任务
3. Orchestrator-Worker 模式: 一个编排者 Agent + 多个工作 Agent
4. Evaluator-Optimizer 模式: 生成 Agent + 评估 Agent 的闭环
5. Human-in-the-loop 模式: 关键节点引入人类审批

常见坑

1. 把所有逻辑都交给 Agent: 不是所有任务都需要 Agent，确定性逻辑应该用代码
2. 工具集合难以辨别: 重叠职责和模糊参数会影响选择；没有适用于所有模型与任务的“20 个工具”门槛
3. 没有停止条件: Agent 可能无限循环，必须设置 max_steps
4. 忽略错误处理: 工具执行失败时的降级策略
5. 上下文爆炸: 不控制历史消息长度，导致 token 超限

和其他概念的关系

• vs Agent: Agent 是概念，AI Agent Application 是工程实现
• vs Agentic Workflow Patterns: Workflow 是其中一种编排模式
• vs Agent Runtime: Runtime 是 Application 的执行引擎层
• vs Context Engineering: Context Engineering 是 Application 的信息组装层

学习检查

• 模型判断任务已完成时，运行时还需验证哪些条件？
• 没有长期记忆、没有 Chat UI 的系统能否成为 Agent 应用？
• 为什么工具调用被拒绝后不能只跳过结果回填？

参考资料

• Building Effective Agents - Anthropic
• OpenAI Agents SDK
• LangGraph Concepts