AI Agent 构建操作指南

AI Agent 构建操作指南

本指南**完全源自Agent面试11问**，剔除面试话术，保留工程落地实操逻辑，专为后端开发、AI应用开发设计。严格遵循后端架构设计思想：配置化、状态机、分层隔离、网关适配、流式推送、多租户隔离。分为单Agent构建手册、多Agent构建手册，全程可直接落地开发。

第一部分：单Agent 标准构建操作指南

单Agent定义：单一智能体独立完成任务，包含记忆、工具、检索、状态管理，适用于通用对话、单一业务场景。

一、整体架构设计（必遵循分层原则）

1. 五层基础架构

1. 接入层：接收前端请求，基于SSE协议实现流式推流，维护HTTP长连接。统一规范事件格式：外层SSE协议（event+data），内层data为JSON格式。

2. 网关适配层（模型网关）：核心设计，隔离业务与模型厂商。包含Adapter适配器、Router路由组件。Adapter适配各类大模型；Router根据成本、延迟、租户、场景自动选择模型。上层Agent不直接依赖任何模型。

3. 核心调度层：状态机管理+任务编排。严格定义Agent运行状态，管控全生命周期流转。

4. 能力执行层：三大核心能力模块拆分，各司其职。记忆模块、工具调用模块、知识检索模块。

5. 数据持久层：存储会话、租户配置、长期记忆、知识库数据，实现配置热更新。

2. 核心设计硬性规范

• 禁止硬编码模型参数、租户配置，全部采用配置化管理，支持无停机热更新。

• 所有执行流程封装为状态机，规避模型不可控问题。

• 请求级快照隔离，保证单次请求配置不被中途修改干扰。

二、核心模块实操搭建步骤

1. 会话与用户体系搭建

严格绑定UserID与SessionID，实现会话隔离：

• UserID：唯一标识用户身份，用于权限、数据隔离；

• SessionID：唯一标识单次对话，一个Session仅归属一个用户；

• 校验规则：每次请求必须携带SessionID，后端校验该Session是否归属当前UserID、AgentID，防止会话串号。

2. 记忆系统搭建（分层记忆）

（1）三类记忆划分

• 短期记忆：当前会话上下文，存储实时对话记录，依托模型上下文窗口，仅服务单次对话；

• 长期记忆：跨会话沉淀数据，包含用户偏好、业务背景、历史总结，持久化存储至数据库/向量库；

• 工作记忆：系统提示词、角色设定、任务约束，全程常驻不可修改。

（2）优化方案

• 上下文超限：采用滑动窗口+LLM摘要压缩，保留关键信息，丢弃无效冗余对话；

• 记忆管理：新增记忆版本化、过期记忆降权清理。

3. 工具调用模块搭建（核心流程）

（1）完整执行链路

用户提问 → 后端创建Agent Run → 加载上下文（记忆+工具+知识库）→ 模型判断是否调用工具 → 输出ToolCall → 后端权限/参数校验 → 执行工具 → 结果回传给模型 → 生成最终回答。

（2）工具调用强制约束

• 格式约束：强制JSON结构化输出，搭配后端正则解析、格式纠错；

• 异常处理：超时采用指数退避重试，参数错误自动纠错，接口宕机降级兜底；

• 事件推送：工具执行全过程通过SSE推送事件，包含tool_call、tool_result事件。

4. 知识检索模块搭建

依托向量知识库，用户发起请求后，语义召回相关知识，拼接至Prompt辅助模型作答，实现私有知识问答，和工具模块、记忆模块相互独立。

5. 状态机系统搭建（字节重点考点）

（1）必备基础状态

已创建、执行中、等待模型、知识检索中、工具调用中、等待工具结果、暂停中、执行完成、执行失败、用户取消、执行超时。

（2）进阶业务状态

规划中、反思中、重试中，用于复杂任务精细化管控。

三、流式交互（SSE）开发规范

1. 交互原理

前端发起HTTP长连接，后端持续推送事件，实现打字机效果实时输出。

2. 固定事件类型

start（开始）、token（字符推送）、tool_call（工具调用）、tool_result（工具结果）、status（状态变更）、error（异常）、done（结束）。

3. 工具事件必填字段

run_id、session_id、agent_id、tool_call_id、tool_name、arguments、status、result、error_code、error_message、timestamp。

四、多租户适配方案（单Agent通用）

若单Agent需要服务多个租户，必须做好三层隔离：

1. 数据隔离：会话、记忆、知识库租户独立存储，杜绝数据串漏；

2. 配置隔离：租户独立配置模型、Prompt、工具、超时参数，支持热更新；

3. 资源隔离：限流、并发控制、Token配额管控，防止租户抢占资源。

第二部分：多Agent 标准构建操作指南

多Agent定义：多个独立单Agent协同分工，拆解复杂任务，各司其职，适用于复杂业务流程、多步骤综合任务。

一、多Agent架构设计原则

1. 职责拆分：每个Agent只负责单一职能，解耦业务逻辑；

2. 统一网关：共用模型网关，统一模型调度、限流、权限；

3. 通信标准化：Agent之间通过固定消息格式通信，共享会话上下文；

4. 全局隔离：租户、资源、数据全局隔离，兼容多租户场景。

二、通用多Agent角色划分（工业通用模板）

1. 规划调度Agent（总指挥）：接收用户原始需求，拆解子任务，分配给对应子Agent，管控整体流程；

2. 工具执行Agent：专门负责各类工具调用，处理接口、数据库、业务API请求；

3. 知识检索Agent：专注向量知识库、文档检索，处理私有知识问答；

4. 记忆管理Agent：统一管控短期、长期记忆，负责记忆压缩、存储、召回；

5. 复盘优化Agent：任务结束后复盘执行流程，记录错误、优化下次执行逻辑。

三、多Agent核心配套能力搭建

1. 智能模型路由（控成本核心）

• 复杂推理、规划任务：调度高价大模型；

• 摘要、格式整理、简单问答：调度廉价小模型；

• 路由依据：场景、延迟要求、成本预算、模型负载。

2. 限流熔断机制

• 限流：采用令牌桶算法，限制单租户、单Agent调用频次；

• 熔断：下游模型/工具失败率过高，直接熔断停止请求，防止服务雪崩。

3. 全局监控体系

监控指标：任务完成率、工具调用成功率、Token消耗、接口耗时、异常报错率，用于迭代优化。

四、多Agent执行流程

1. 用户请求接入，网关校验权限、租户配置；

2. 规划Agent拆解任务，分配至对应子Agent；

3. 各子Agent并行/串行执行任务，通过消息池共享数据；

4. 所有子任务完成，汇总结果；

5. 复盘Agent记录流程，优化记忆与任务模板；

6. 通过SSE向前端推送最终结果与全流程事件。

第三部分：通用落地硬性规范

一、必守工程准则

1. 所有配置拒绝硬编码，全部配置化，支持热更新；

2. 所有流程状态机管控，杜绝模型自由执行，提升可控性；

3. 所有异常分级处理，重试、降级、告警三层兜底；

4. 所有数据分层隔离，租户、会话、资源互不干扰。

二、技术选型推荐

• 后端语言：Go（高并发）、Python（业务开发）；

• 模型网关：自研适配层/火山方舟；

• 存储：Redis（短期会话）、向量库（长期记忆）、MySQL（租户配置）；

• 通信：SSE流式推送、异步任务队列；

• 框架：LangGraph、自研轻量Agent框架。

三、避坑总结

• 禁止Agent直连大模型，必须加模型网关；

• 禁止无状态执行，一定要设计状态机；

• 禁止配置写死，无法热更新；

• 禁止工具结果用assistant角色回传，必须使用user角色；

• 禁止多租户无隔离，造成数据串漏。