Agent Engine
Agent Engine 是 AI 应用中负责 Agent 推理-动作循环的核心组件，包含 LLM 调用、工具分发、状态管理、记忆管理和可观测性。它是 AI Service 的核心模块。
#type / concept
#status / evergreen
#tech / ai
#tech / architecture
[!info] related notes
- 所属 MOC: AI Agent Application MOC
- 上游概念: Agent, Augmented LLM
- 并列概念: Agent Runtime
- 下游组件: Tool Registry, Memory Manager, RAG Engine
Agent Engine
一句话定义
Agent Engine 是 AI Service 中负责驱动 Agent 推理-动作循环的核心组件。它不是 LLM 本身，而是包住 LLM 的那层逻辑：决定何时调用模型、如何分发工具、怎样管理状态、何时停止。
它解决什么问题
直接调用 LLM API 只能得到一次问答。但 Agent 需要：
- 多轮推理：模型说”我要先查数据”→ 执行查询 → 结果回传 → 模型继续推理
- 工具管理：注册、发现、执行、结果处理
- 状态维护：当前任务进度、已执行步骤、中间结果
- 记忆管理：短期对话历史、长期用户画像
- 可观测性：每次 LLM 调用的 token 消耗、延迟、决策路径
Agent Engine 把这些能力封装成一个可复用的模块。
核心原理
与 Agent Runtime 的关系
这两个概念容易混淆：
| Agent Engine | Agent Runtime | |
|---|---|---|
| 关注点 | 推理逻辑、工具编排、知识检索 | 执行环境、生命周期、状态持久化 |
| 类比 | 大脑 | 身体 |
| 典型组件 | LLM 调用、Tool Registry、RAG、Memory | Run、Step、Checkpoint、Trace、Timeout |
在很多框架中（如 LangGraph），这两个概念是融合在一起的。但在三层架构中，Engine 更偏 Python AI Service 侧的业务逻辑，Runtime 更偏执行环境的基础设施。
Engine 的核心组成
┌─────────────────────────────────────┐
│ Agent Engine │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ Planner │ │ LLM Gateway │ │
│ │ (规划器) │ │ (模型网关) │ │
│ └────┬─────┘ └──────┬───────┘ │
│ │ │ │
│ ┌────▼───────────────▼───────┐ │
│ │ Agent Loop │ │
│ │ (推理-动作循环) │ │
│ └────┬───────────┬───────────┘ │
│ │ │ │
│ ┌────▼────┐ ┌────▼──────────┐ │
│ │ Tool │ │ RAG Engine │ │
│ │Executor │ │ (检索增强) │ │
│ └─────────┘ └───────────────┘ │
│ │
│ ┌─────────────────────────────┐ │
│ │ Memory Manager │ │
│ │ (短期 + 长期记忆) │ │
│ └─────────────────────────────┘ │
└─────────────────────────────────────┘Agent Loop 核心逻辑
class AgentEngine:
def __init__(self, llm, tools, memory, rag):
self.llm = llm
self.tools = tools
self.memory = memory
self.rag = rag
async def run(self, context: Context) -> AsyncIterator[Event]:
messages = self.build_messages(context)
for step in range(self.max_steps):
# 1. 检索知识（如果需要）
if self.should_retrieve(context):
knowledge = await self.rag.retrieve(context.current_query)
messages = self.inject_knowledge(messages, knowledge)
# 2. 调用 LLM
response = await self.llm.chat(messages, tools=self.tools.schemas())
# 3. 处理响应
if response.has_tool_calls():
for tool_call in response.tool_calls:
yield ToolCallStartEvent(tool_call)
result = await self.tools.execute(tool_call, context)
messages.append(tool_result_message(tool_call, result))
yield ToolCallResultEvent(tool_call, result)
else:
yield TextDeltaEvent(response.text)
break
# 4. 更新记忆
self.memory.save(context.session_id, messages)在 React + Go + Python AI Service 架构中的位置
Agent Engine 位于 Python AI Service 内部，是其核心模块：
- 向上: 接收 Go 后端传来的 Context Bundle
- 向下: 调用 LLM Provider、Tool Executor、RAG Engine、Memory Manager
- 对外: 通过 SSE 流式输出事件到 Go 后端
典型工程实现
模块结构
apps/ai-service/
engine/
agent_engine.py # Agent Engine 主逻辑
planner.py # 任务规划器
loop.py # Agent Loop
tools/
registry.py # Tool Registry
executor.py # Tool Executor
rag/
retriever.py # 检索器
reranker.py # 重排序
memory/
short_term.py # 短期记忆（对话历史）
long_term.py # 长期记忆（用户画像）
llm/
provider.py # LLM Provider 抽象
gateway.py # Model Gateway与 LangGraph 的关系
LangGraph 的 StateGraph 本质上就是一种 Agent Engine 的实现方式：
from langgraph.graph import StateGraph
graph = StateGraph(AgentState)
graph.add_node("llm", call_llm)
graph.add_node("tool", execute_tool)
graph.add_edge("llm", "tool", should_call_tool)
graph.add_edge("tool", "llm")常见设计模式
- ReAct 模式: Reasoning + Acting 的循环
- Plan-and-Execute 模式: 先规划步骤，再逐步执行
- Evaluator-Optimizer 模式: 生成 + 评估的闭环
- Multi-Agent 模式: 多个 Engine 协作
常见坑
- Engine 和 Runtime 职责不分: Engine 管推理逻辑，Runtime 管执行环境
- 没有最大步数限制: Agent 可能无限循环
- 工具执行不做隔离: 一个工具崩溃影响整个 Engine
- 记忆管理缺失: 每轮都传全量历史，token 爆炸
和其他概念的关系
- vs Agent Runtime: Engine 是推理层，Runtime 是执行环境层
- vs Planner: Planner 是 Engine 的一个子模块
- vs AI Service: Engine 是 AI Service 的核心组件
- vs Agent Loop: Agent Loop 是 Engine 的核心执行逻辑
总结
Agent Engine 是”让 LLM 从单次问答变成多步推理”的关键组件。它的质量直接决定了 Agent 的可靠性和效率。