从零搭建生产级AI Agent：规划、记忆、工具调用与多智能体协作实战

摘要

大模型从“单次问答”走向“自主智能体”，核心挑战在于构建具备规划推理、持久记忆、工具调用与多智能体协作能力的生产级系统。本文系统阐述从零搭建生产级AI Agent的完整技术路径，涵盖规划与推理机制、跨会话持久记忆设计、工具调用与安全隔离、多智能体协作架构四大核心模块。配套提供基于LangGraph的完整代码实现，以及Agentica框架的记忆管理、自进化机制等工程实践，为企业构建可扩展、可治理的AI Agent系统提供可落地的技术方案。

关键词：AI Agent；规划推理；持久记忆；工具调用；多智能体协作；LangGraph

一、引言：从Demo到生产的跨越

过去两年，AI Agent从概念走向实践，大量团队跑通了“调用模型+调用工具”的POC，但真正将Agent推向生产环境的比例依然偏低。原因在于：生产级Agent的要求远不止“能跑通”，而是需要具备自主决策、状态持久化、异常恢复、安全隔离、可观测等工程化能力。

真正的生产级Agent系统，不是一次简单的模型API调用，而是一个持续运行的决策循环，它需要：

• 规划能力：将复杂任务拆解为可执行的子步骤，并根据执行结果动态调整方案
• 记忆能力：跨会话保留上下文、用户偏好和历史决策，避免每次对话都“格式化大脑”
• 工具调用能力：安全地调用文件系统、数据库、API等外部服务完成具体操作
• 协作能力：多Agent分工协作，各自发挥领域专长处理复杂任务

本文将沿着这四个维度，系统阐述生产级AI Agent的构建方法论与代码实践。

二、核心架构：七大模块与设计理念

一个生产级AI Agent系统可拆解为七大核心模块：

核心设计原则：将LLM从“知识源”降级为“理解与生成引擎”，所有事实性信息和确定性操作从可验证的外部系统中获取。这种分层设计使各模块可独立演进，一个模块的变更不影响其他模块。

三、规划：让Agent“想清楚再干”

3.1 规划的核心挑战

Agent的规划能力决定了它能否有效解决复杂任务。实践中主要面临三类挑战：

• 长流程编排：跨工具链的复杂任务拆解与状态管理，每一步的上下文需要妥善传递
• 动态调整：执行过程中出现错误或意外结果，Agent需要有能力重新规划
• 死循环防护：缺乏明确的终止条件，Agent可能在无效路径上无限循环

3.2 基于LangGraph的规划实现

LangGraph将Agent建模为有状态的工作流图，每个节点代表一个处理步骤，边代表状态流转。以下代码实现一个带规划与执行分离的Agent系统：

# planner_agent.py 基于LangGraph的规划Agent
from typing import TypedDict, List, Dict, Literal
from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
import json

class AgentState(TypedDict):
    """Agent状态定义"""
    task: str
    plan: List[Dict]  # 步骤列表
    current_step: int
    results: Dict  # 各步骤执行结果
    final_answer: str
    retry_count: int

class PlannerAgent:
    """规划-执行分离的Agent"""
    
    def __init__(self, model_name: str = "deepseek-chat"):
        self.llm = ChatOpenAI(model=model_name, temperature=0.3)
        
    def plan_node(self, state: AgentState) -> AgentState:
        """规划节点：将任务拆解为步骤"""
        plan_prompt = f"""
        将以下任务分解为具体步骤，以JSON数组输出。
        每个步骤格式：{{"step_id": 序号, "action": "行动描述", "tool": "工具名或none"}}
        
        任务：{state['task']}
        
        可用工具：search_database, query_order, send_email, generate_report
        """
        response = self.llm.invoke(plan_prompt)
        try:
            plan = json.loads(response.content)
            state["plan"] = plan
            state["current_step"] = 0
        except:
            # 规划失败时的兜底
            state["plan"] = [{"step_id": 0, "action": "直接回答", "tool": "none"}]
        return state
    
    def execute_node(self, state: AgentState) -> AgentState:
        """执行节点：执行当前步骤"""
        step = state["plan"][state["current_step"]]
        tool_name = step.get("tool", "none")
        
        if tool_name == "none":
            # 无工具调用，直接用LLM生成
            result = self.llm.invoke(f"执行任务：{step['action']}，上下文：{state['results']}")
            state["results"][step["step_id"]] = result.content
        else:
            # 调用工具（简化示例）
            result = self._call_tool(tool_name, step.get("params", {}))
            state["results"][step["step_id"]] = result
        
        state["current_step"] += 1
        return state
    
    def should_continue(self, state: AgentState) -> Literal["execute", "reflect", "end"]:
        """判断是否继续执行"""
        if state["current_step"] >= len(state["plan"]):
            return "end"
        # 检查是否需要重试
        if state.get("retry_count", 0) > 3:
            return "end"
        return "execute"
    
    def build_graph(self):
        """构建工作流图"""
        workflow = StateGraph(AgentState)
        workflow.add_node("plan", self.plan_node)
        workflow.add_node("execute", self.execute_node)
        
        workflow.set_entry_point("plan")
        workflow.add_edge("plan", "execute")
        workflow.add_conditional_edges(
            "execute",
            self.should_continue,
            {
                "execute": "execute",
                "end": END
            }
        )
        return workflow.compile()

3.3 Plan-and-Execute vs ReAct

两种主流规划范式的对比：

生产实践中，Plan-and-Execute更受青睐——规划Agent专门负责任务分解，执行Agent深度访问工具，关注点分离使系统的可观测性和可控性大幅提升。

四、记忆：让Agent“记住”和“遗忘”

4.1 为什么记忆是Agent的刚需

大模型在本质上是无状态的（Stateless）——每次交互都像第一次见面。这带来的问题包括：

• 跨会话状态断裂：用户昨天告诉Agent的偏好、上周达成的架构决策，下次对话全部归零
• 上下文窗口限制：多轮对话或复杂任务中，早期信息会被挤出窗口
• 无法个性化：每次互动都像是第一次见面，无法积累用户画像

生产级Agent需要短期记忆（维护当前对话上下文）和长期记忆（跨会话持久化知识）两套系统协同工作。

4.2 短期记忆实现

# short_term_memory.py 短期记忆管理
from collections import deque
from typing import List, Dict

class ShortTermMemory:
    """滑动窗口式短期记忆"""
    
    def __init__(self, max_turns: int = 10):
        self.messages = deque(maxlen=max_turns)
        self.work_memory = {}  # 当前任务的临时状态
        
    def add_message(self, role: str, content: str):
        """添加对话消息"""
        self.messages.append({"role": role, "content": content})
    
    def get_context(self) -> List[Dict]:
        """获取当前上下文窗口"""
        return list(self.messages)
    
    def set_work_state(self, key: str, value):
        """设置工作记忆"""
        self.work_memory[key] = value
    
    def get_work_state(self, key: str):
        """获取工作记忆"""
        return self.work_memory.get(key)

4.3 长期记忆：Agentica的Workspace实践

Agentica框架提供了完整的持久化记忆方案——Workspace记忆系统。其核心设计是“索引与内容分离”：

• 每条记忆独立存储为文件
• 通过语义相关性召回最相关的记忆，而非全量注入上下文
• 支持四种记忆类型：user（用户偏好）、feedback（反馈意见）、project（项目上下文）、reference（参考资料）

# workspace_memory.py 基于Agentica的持久记忆
from agentica import Agent, Workspace, OpenAIChat
from agentica.agent.config import WorkspaceMemoryConfig

# 初始化Workspace
workspace = Workspace("./workspace", user_id="alice")
workspace.initialize()

# 写入长期记忆
await workspace.write_memory_entry(
    title="Python Code Style",
    content="用户偏好使用类型注解和列表推导式",
    memory_type="feedback",  # 用户反馈类记忆
    description="python coding style",
    sync_to_global_agent_md=True  # 同步到全局配置，新会话自动继承
)

# 创建带长期记忆的Agent
agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    workspace=workspace,
    long_term_memory_config=WorkspaceMemoryConfig(
        max_memory_entries=5,  # 每次最多注入5条相关记忆
        sync_memories_to_global_agent_md=True,
    ),
)

# Agent会根据当前query自动召回最相关的记忆，而非全量注入
result = agent.run_sync("帮我写一个Python函数")  # 自动参考用户偏好的代码风格

4.4 高级记忆机制：艾宾浩斯遗忘与语义图谱

更成熟的记忆系统会模拟人类记忆的“遗忘-强化”机制。以Engram记忆服务为例：

遗忘曲线：每条记忆有一个强度值，随时间按指数衰减。不同类型的记忆有不同的衰减率：

• Strategy（策略）：~38天半衰期，被验证的方法论要记最久
• Fact（事实）：~24天半衰期，用户偏好、技术选型
• Failure（失败经验）：~11天半衰期，踩过的坑自然消退

智能去重与矛盾消解：存入新记忆时，系统先和已有记忆做语义比对。相似度≥0.85时只增加回忆次数不重复存储；检测到语义矛盾时用新内容覆盖旧的。

语义图谱：每条记忆自动和已有记忆建立关联，形成知识网络。检索时通过联想发现相关记忆——即使与查询词没有直接的语义相似度，也能通过图谱找到关联知识。

五、工具调用：让Agent“会干活”

5.1 工具体系设计原则

工具调用是Agent从“思考者”变为“行动者”的关键能力。生产级工具体系遵循以下原则：

1. 最小权限原则：每个工具仅授予必要的操作权限
2. 输入验证：对工具参数进行类型检查和边界校验
3. 执行隔离：高风险操作在Docker容器等沙箱中执行
4. 超时控制：每个工具调用设置合理的超时阈值

5.2 工具定义与注册

# tools.py 工具定义与注册
from typing import Dict, Any
import asyncio

class ToolRegistry:
    """工具注册与调用管理"""
    
    def __init__(self):
        self.tools = {}
        self.tool_schemas = []
        
    def register(self, name: str, description: str, parameters: Dict, func):
        """注册工具"""
        self.tools[name] = func
        self.tool_schemas.append({
            "type": "function",
            "function": {
                "name": name,
                "description": description,
                "parameters": parameters
            }
        })
        return self
    
    async def execute(self, name: str, params: Dict, timeout: float = 30.0) -> Dict:
        """执行工具调用，带超时控制"""
        if name not in self.tools:
            return {"success": False, "error": f"未知工具: {name}"}
        
        try:
            result = await asyncio.wait_for(
                self._safe_call(self.tools[name], params),
                timeout=timeout
            )
            return {"success": True, "result": result}
        except asyncio.TimeoutError:
            return {"success": False, "error": "工具调用超时"}
        except Exception as e:
            return {"success": False, "error": str(e)}
    
    async def _safe_call(self, func, params):
        """安全调用包装"""
        # 实际应做参数校验、权限检查等
        return func(**params) if asyncio.iscoroutinefunction(func) else func(**params)

# 示例：注册业务工具
registry = ToolRegistry()

def query_order(order_id: str) -> Dict:
    """查询订单状态"""
    return {"order_id": order_id, "status": "shipped", "tracking": "SF123456"}

registry.register(
    "query_order",
    "通过订单号查询订单状态和物流信息",
    {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
    },
    query_order
)

六、多智能体协作：让团队干活

6.1 为什么需要多智能体

单个Agent配备大量工具时，常面临以下问题：

• 工具选择困难：过长工具列表导致调用效率低下
• 上下文爆炸：工作记忆需要承载过多信息
• 角色迷失：一个Agent同时扮演数据分析师、软件工程师、客服等多个角色，提示词冗长矛盾

多智能体系统的解法是借鉴现代公司的分工模式：每个Agent专注于特定领域，通过明确的通信协议协作。

6.2 主管模式（Supervisor）

主管模式下，一个中央主管Agent控制所有通信流和任务委派，根据上下文决定调用哪个专业Agent。

# supervisor_agent.py 主管模式多智能体
from typing import Annotated
from langchain_core.tools import tool, InjectedToolCallId
from langgraph.prebuilt import create_react_agent, InjectedState
from langgraph.graph import StateGraph, START, MessagesState
from langgraph.types import Command

def create_handoff_tool(agent_name: str, description: str = None):
    """创建移交工具"""
    description = description or f"Transfer to {agent_name}"
    name = f"transfer_to_{agent_name}"
    
    @tool(name, description=description)
    def handoff_tool(
        state: Annotated[MessagesState, InjectedState],
        tool_call_id: Annotated[str, InjectedToolCallId],
    ) -> Command:
        tool_message = {
            "role": "tool",
            "content": f"已移交给 {agent_name}",
            "name": name,
            "tool_call_id": tool_call_id,
        }
        return Command(
            goto=agent_name,
            update={"messages": state["messages"] + [tool_message]},
            graph=Command.PARENT,
        )
    return handoff_tool

# 创建移交工具
transfer_to_hotel = create_handoff_tool("hotel_assistant", "移交给酒店预订助手")
transfer_to_flight = create_handoff_tool("flight_assistant", "移交给航班预订助手")

# 定义各专业Agent
flight_assistant = create_react_agent(
    model="deepseek-chat",
    tools=[book_flight, transfer_to_hotel],
    prompt="你是航班预订助手",
    name="flight_assistant"
)

hotel_assistant = create_react_agent(
    model="deepseek-chat",
    tools=[book_hotel, transfer_to_flight],
    prompt="你是酒店预订助手",
    name="hotel_assistant"
)

# 构建多Agent图
multi_agent_graph = (
    StateGraph(MessagesState)
    .add_node(flight_assistant)
    .add_node(hotel_assistant)
    .add_edge(START, "flight_assistant")
    .compile()
)

# 执行：Agent会根据需要自动移交
for chunk in multi_agent_graph.stream({
    "messages": [{"role": "user", "content": "订一张从北京到上海的机票和一家附近的酒店"}]
}):
    print(chunk)

6.3 多智能体架构对比

七、自进化：让Agent越用越聪明

生产级Agent的终极形态是具备自进化能力——从错误和成功中持续学习，无需人工干预。

Agentica框架将Agent在执行过程中产生的所有信号（工具失败、用户纠正、成功序列）采集成经验卡片。同一规则被反复确认N次后，自动生成一个SKILL.md技能文件，新会话的Agent可以直接复用之前学到的做事方式。

# self_evolution.py 自进化Agent启用
from agentica import Agent, Workspace, OpenAIChat
from agentica.agent.config import ExperienceConfig, SkillUpgradeConfig
from agentica.hooks import ExperienceCaptureHooks

workspace = Workspace("./workspace", user_id="alice")
workspace.initialize()

# 配置自进化参数
hooks = ExperienceCaptureHooks(
    ExperienceConfig(
        capture_tool_errors=True,          # 捕获工具失败（零LLM成本）
        capture_success_patterns=True,     # 捕获成功模式（零LLM成本）
        promotion_count=3,                 # 同一规则被确认3次→生成技能
        skill_upgrade=SkillUpgradeConfig(
            mode="shadow",                 # shadow=自动安装到workspace
            min_repeat_count=3,
        )
    )
)

agent = Agent(
    model=OpenAIChat(id="gpt-4o-mini"),
    workspace=workspace,
    _default_run_hooks=hooks
)

# Agent在运行中自动采集经验，沉淀为可复用技能
agent.run_sync("帮我读取 ./docs/agent.md")

整条链路本地、可审计、零外部依赖——工具失败和成功模式的采集是确定性的，不消耗LLM；只有“用户纠正分类”和“是否生成新技能”两步使用辅助模型判定。

八、生产部署要点

将AI Agent投入生产环境，需重点关注以下方面：

安全与权限

• 高风险操作（文件删除、系统命令、资金操作）强制人工审核
• 使用Docker容器隔离工具执行环境
• 实施JWT令牌认证，审计日志保留180天以上

可观测性

• 为每个Agent调用添加追踪（Trace），记录输入、输出、耗时
• 设置关键SLA指标（任务完成率>99.9%，95分位延迟<500ms）
• 配置异常告警机制（Slack/PagerDuty通知）

性能与成本

• 使用语义缓存避免重复计算
• 根据任务复杂度动态选择模型（简单任务用便宜模型）
• 设置Token预算上限，防止成本失控

可靠性

• 实现指数退避重试机制
• 工具调用超时后自动降级到备用方案
• 状态机设计支持从断点恢复

九、总结

从零搭建生产级AI Agent，是一场从“模型调用”到“工程闭环”的范式转移。核心要点可归纳为：

1. 规划即架构：Plan-and-Execute将任务分解与执行分离，使系统更可控、更可观测
2. 记忆即资产：持久记忆系统让Agent积累经验、提供个性化服务，是区别于“调用API”的本质差异
3. 工具即行动力：安全的工具体系让Agent从“思考者”变为“行动者”，但必须伴随严格的权限和隔离控制
4. 协作即规模化：多智能体系统实现专业化分工，让复杂任务可以被体系化解决
5. 自进化即可持续：从错误和反馈中学习的能力，决定Agent能否长期创造价值

当基础模型能力逐渐趋同，真正拉开企业差距的，将不再是“谁调用了更大的模型”，而是“谁能构建出更可靠的Agent工程体系”。从规划到记忆，从工具到协作，再到自进化——这五步构成的闭环，是AI Agent从“玩具”走向“工具”的必经之路。