L2 · 专题文章

核心模块

Agent 架构模块化设计智能体工程

模块化是构建可生产级 Agent 的唯一路径

5核心模块
3关键接口
2控制维度
先记住模块解耦 ≠ 功能堆砌

每个模块必须有明确输入输出契约,否则将退化为难以维护的 Prompt 迷宫

LIVE
CORE Agent Core
01 WHAT

是什么

Agent 核心模块是构成智能体能力的标准化组件集合,包含规划、记忆、工具调用、状态管理与工作流编排。

02 WHY

为什么

单一 Prompt 无法处理长链路、多依赖与外部交互任务;模块化让系统可调试、可复用、可独立演进。

03 HOW

怎么做

先明确任务边界,再按 Planning→Memory→Tool→State→Workflow 顺序组装最小闭环,逐步接入真实业务数据。

04 WHEN

什么时候

适用于需多步推理、外部系统交互或长期上下文保持的场景;简单问答或固定规则流程无需引入。

THIS PAGE INCLUDES
PlanningMemoryToolStateWorkflow

FOCUS

先记住这些

只留最重要的判断,细节见下方实践
01 独特价值

为什么需要模块化

单体 Prompt 无法应对复杂任务链,模块化提供可测试、可替换、可监控的工程基础

02 复杂度

真正难在哪里

状态一致性维护、工具调用失败恢复、记忆检索噪声过滤与多模块并发协调

03 使用判断

什么时候用

任务需多步推理、外部交互或长期记忆时启用;简单场景用 Prompt 模板更高效

ROUTE

学习路径

建议按此顺序逐步深入
01
理解模块契约

掌握各模块输入输出格式与错误信号定义

02
搭建最小闭环

用 Planning+Tool+State 实现单任务自动化

03
接入 Memory 与 Workflow

扩展上下文保持与多分支流程控制

PROBLEM / POSITION / INTERFACE

先弄清它为什么存在,以及谁在使用

不从历史开始,从真实工作关系开始。
  1. 01 解决的问题

    当任务涉及多步骤决策、需调用外部 API 或依赖历史交互信息时

    无模块化设计会导致 Prompt 膨胀、状态丢失、错误难以定位、扩展成本指数上升

    成功标准
    各模块职责清晰、接口稳定、可独立测试与替换,整体链路可观测且失败可恢复
  2. 02 AI 生态位

    作为 Agent 架构的中枢层,承接上游意图解析,向下游执行器提供结构化决策与上下文

    上游
    依赖用户输入、业务规则、外部数据源与基础 LLM 能力
    下游
    为具体业务场景(如客服、数据分析、自动化操作)提供可组合的智能体能力
  3. 03 人的生态位

    人类定义模块边界、配置控制参数、验收输出质量并处理异常兜底

    适合使用
    任务需多步推理、外部系统交互、长期上下文保持或需多人协作开发维护
    不必使用
    单次问答、固定规则流程、低延迟要求或团队无工程化能力时
  4. 04 独特价值

    通过解耦实现独立优化与热替换,避免单体 Prompt 的脆弱性与不可调试性

    模块间状态同步、工具调用幂等性、记忆检索精度与工作流异常恢复的协同设计

    复杂度判断
    复杂度不是功能数量,而是控制与验证成本。

INTERFACE FLOW

谁在操作,信息怎样流动

  1. WHO OPERATES

    HUMAN定义任务目标、选择模块组合、设置控制参数、验收结果与处理异常

    AGENT按工作流调度各模块,执行规划、检索记忆、调用工具、维护状态

    BACKEND提供持久化存储、API 网关、权限校验与监控日志

  2. INPUT

    用户请求、业务上下文、历史交互记录、工具 Schema 与状态快照

  3. CONTROL

    Prompt 模板、工具白名单、记忆检索策略、状态持久化规则、工作流分支条件

  4. OUTPUT

    结构化执行结果、状态变更日志、工具调用记录、异常信号与人工介入请求

FLOW

标准执行流程

01接收请求解析用户输入,提取意图与约束条件
02规划路径Planning 模块生成任务分解与执行顺序
03调度执行Workflow 按计划调用 Tool 并更新 State
04状态同步将关键中间结果写入 Memory 供后续使用
05结果输出聚合各模块输出,生成最终响应或触发人工介入

MODULES

关键模块职责

01

02

03

04

05

COMPARE

模块化 vs 单体 Prompt

维度模块化架构单体 Prompt
可维护性高:独立测试与替换低:牵一发而动全身
调试能力强:模块级日志与指标弱:黑盒输出难定位
扩展成本线性:新增模块不影响现有逻辑指数:Prompt 膨胀导致性能下降
适用场景复杂任务、多系统交互简单问答、固定流程

PRACTICE

最小可用检查清单

明确定义任务边界与成功标准
为每个模块编写输入输出 Schema
实现基础错误处理与重试机制
配置关键状态持久化策略
设置人工介入触发条件
记录模块调用日志与性能指标
CODE / PYTHON最小闭环示例
from langgraph.graph import StateGraph, END
from typing import TypedDict

class AgentState(TypedDict):
    query: str
    result: str

def plan_node(state: AgentState):
    # 简化版规划逻辑
    return {"result": f"Planning: {state['query']}"}

def tool_node(state: AgentState):
    # 模拟工具调用
    return {"result": state['result'] + " → Tool executed"}

workflow = StateGraph(AgentState)
workflow.add_node("plan", plan_node)
workflow.add_node("tool", tool_node)
workflow.add_edge("plan", "tool")
workflow.add_edge("tool", END)
workflow.set_entry_point("plan")

app = workflow.compile()
result = app.invoke({"query": "查询用户订单状态"})
print(result)

使用 LangGraph 实现 Planning→Tool→State 基础链路

JSON / RESPONSE典型返回结构
{
  "query": "查询用户订单状态",
  "result": "Planning: 查询用户订单状态 → Tool executed",
  "metadata": {
    "nodes_executed": [
      "plan",
      "tool"
    ],
    "execution_time_ms": 1250,
    "state_snapshot": {
      "query": "查询用户订单状态",
      "result": "Planning: 查询用户订单状态 → Tool executed"
    }
  }
}

FAQ

常见问题

选型、用法与失败,不复述定义。
01谁在实际使用这些模块?

AI 工程师负责架构设计与集成,业务开发者配置参数,运维人员监控指标。

明确角色分工决定接口设计与权限控制策略。
02模块化和单体 Prompt 的核心区别是什么?

模块化提供可测试、可替换的组件,单体 Prompt 是黑盒且难以调试。

避免在简单场景引入不必要的复杂度。
03最小可用方式是什么?

用 Planning 生成执行计划,Tool 调用外部接口,State 记录结果。

快速验证架构可行性后再扩展 Memory 与 Workflow。
04生产环境最容易在哪里失败?

状态不一致、工具调用超时、记忆检索噪声导致规划错误。

需提前设计重试、降级与人工介入机制。
05什么时候不需要模块化?

单次问答、固定规则流程或低延迟要求场景。

避免过度工程化导致维护成本上升。