AI原生架构入门：Agent与多智能体系统设计与实战

说实话，如果你现在还停留在“调大模型API、把返回的文本渲染到页面上”的阶段，那听到“AI原生架构”的时候心里发虚是很正常的。智能体（Agent）与多智能体系统，听起来像很高端的东西，但它并不是什么神秘技术，只是把过去“一问一答”的使用方式，升级成“让模型像同事一样自己动手干活”的系统设计。这篇文章面向小白程序员，不堆砌框架黑话，尽量用一个下午就能上手的思路，把Agent是什么、多智能体系统在编排什么、以及从零搭一个实战Demo的完整过程讲清楚。适合刚学会调用LLM、想往AI原生架构方向深入了解的开发者，也能帮有经验的人重新梳理一遍设计决策里的坑。

1. 从“问答机器人”到“能干活的同学”：Agent到底解决了什么问题

1.1 大模型只负责“想”，Agent负责“想+做+改”

很多人第一次接触大模型API时，会觉得“这不就是个高级问答接口吗”？你给它一段Prompt，它吐一段文字。但你让它“写一个登录接口的代码”，它写完就结束了，代码能不能编译、逻辑有没有漏洞、能不能调用真实服务，它一概不管。

Agent做的事情，本质上就是把“思考”和“行动”连接起来。你可以这么理解：单次模型调用像你请了一位知识渊博但行动力为0的同学，他只能口头告诉你答案；而Agent是请了一位能动笔、能查资料、能自查、能重写的同学。他会先分析需求，再决定调用什么工具（比如查数据库、执行Shell命令、读文件），然后根据工具返回的结果继续调整方案，直到任务完成。

这套“观察-思考-行动-再观察”的循环，才是Agent真正区别于普通API封装的地方。也正是因为这个循环，AI原生架构里的应用才敢让模型承担核心业务流程中的关键环节，而不是只做一个问答插件。

1.2 AI原生架构为什么绕不开Agent

“AI原生架构”这个词听起来很玄，但拆开看其实就一句话：系统的核心流程不是“人先定好所有规则，模型只做辅助”，而是“模型作为业务流程里的关键决策者和执行者，人负责定义目标和边界”。

举个例子，一个传统的代码审查工具，规则是人写死的，比如正则匹配、静态检查；而一个AI原生架构的代码审查Agent，会自己读代码、生成修改建议、调用测试工具验证、再把结果整理成报告。前者是“工具”，后者是“系统里的一等公民”。

为什么说绕不开Agent？因为大模型本身有“上下文有限”“会幻觉”“输出不稳定”这些缺陷，单次调用根本扛不住真实业务场景。Agent通过工具调用扩展能力边界，通过记忆补足上下文限制，通过循环迭代减少错误——这些恰好是为了解决大模型的实际缺陷而生的设计模式。所以当你看到越来越多招聘岗位在招“Agent开发工程师”时，那不是风口噱头，而是AI原生应用落地的基本盘。

2. 拆一台Agent：四个零件一个都不能少

一个Agent系统拆到底，就是四样东西：大脑（LLM主模型）、手和脚（工具调用）、记忆（上下文管理）、调度器（规划和循环）。咱们一个一个看清楚。

2.1 大脑：LLM主模型的选择与温度参数

模型选型这件事，小白最容易犯的错是“哪个贵选哪个”。其实Agent对模型的真实需求是分层的：如果任务是工具调用密集、逻辑链路长的，那模型的能力上限直接决定系统上限；如果只是从文档里抽取一段摘要再做分类，那一个小参数模型可能就够了，成本能省一大截。

除了选模型，还有一个经常被忽略的参数：temperature。这个参数控制模型输出的随机性。Agent的规划、工具调用、代码生成这类任务，我强烈建议把温度调到0到0.3之间，越低越稳定。我有一次做代码生成Agent，默认温度用的0.7，结果同一个需求跑五次，五次给出五种不同的接口命名，测试Agent报了三次“未定义函数”。把温度降到0.2之后，输出一致性立刻好很多。

这里给一个模型请求的最小示意：

response = llm_client.complete( model="your-model-name", messages=messages, tools=tools, temperature=0.2, )

2.2 手和脚：工具调用（Function Calling）的注册与执行

工具调用是Agent能“动手”的关键。原理其实不复杂：你把一组函数的描述（包括函数名、参数、用途）以JSON Schema的形式传给模型，模型在回答中不再直接输出纯文本，而是输出一个结构化调用请求，比如“我要调用get_weather，参数是{city: '目标城市'}”。

你的代码拿到这个请求之后，去真实执行对应的函数，再把执行结果作为一条新消息追加回对话里。模型看到结果后，要么继续调用下一个工具，要么给出最终回答。这个过程，就是Agent的“手和脚”。

给工具写描述时有个容易踩的坑：描述写得越含糊，模型越爱瞎猜。比如一个工具叫get_user_info，描述如果只写“获取用户信息”，模型在调用时可能不知道参数该传用户ID还是邮箱；但如果你写成“根据用户唯一ID获取用户基础资料，用户ID是整数类型，可从订单接口返回值中获得”，模型选错参数的概率会大幅下降。工具描述本质上是给模型看的API文档，写详细一点不会亏。

2.3 记忆：短期上下文与长期记忆的落地方案

大模型的上下文窗口是有限的，这就引出了Agent系统的第三块零件：记忆。

短期记忆最简单，就是维护一个对话消息列表。但问题在于列表会越来越长，一旦超过模型上下文限制，要么报错，要么被静默截断。小白最常见的处理方式是直接把所有消息全部塞进去，然后突然发现跑了几轮之后，Agent“忘记”了最开始的用户需求——那不是模型傻，是你把早期消息挤出了窗口。

更实用的做法是“滑动窗口+摘要”。比如只保留最近的10轮消息，更早的内容每隔几轮请模型生成一段摘要放进系统提示词里。这种方式成本低、实现快，适合绝大多数早期项目。

至于长期记忆，一般指的是跨会话保存知识。如果你只是做一个Demo，完全不需要一上来就引入向量数据库，用本地的JSON文件或者SQLite按“用户的偏好关键词”存一存就够跑了。等你真的碰到“要在几千条历史记录里检索相关信息”的场景，再考虑往向量检索升级。

2.4 调度器：规划和ReAct循环

最后一个零件是调度器，它负责驱动整个Agent循环。目前最经典、也最适合新手理解的模式是ReAct，也就是“推理（Reasoning）+ 行动（Acting）”的循环。

流程是这样的：

def agent_loop(user_question): messages = [SYSTEM_PROMPT, {"role": "user", "content": user_question}] for step in range(MAX_STEPS): response = llm_client.complete(messages, tools=TOOLS) if response.tool_call: messages.append(transform_tool_call_to_message(response.tool_call)) result = execute_tool(response.tool_call) messages.append(transform_tool_result_to_message(result)) else: return response.content return "已超过最大迭代次数，返回当前结论"

为什么要把循环次数设上限？因为真实的Agent经常会在一个问题上反复调用工具，出不来结果。不设上限的话，一次对话能烧掉你几十块钱的Token。MAX_STEPS从3到10之间比较合适，除非你的任务链路确实很长，再适当调高。

3. 单人桌还是流水线：多智能体系统到底在编排什么

等你把单个Agent跑通了，很快会碰到一个实际问题：一个Agent什么都能干，但什么都不精。比如你让它既做需求分析、又写代码、又做测试，它的上下文会迅速被不同类型的信息填满，角色切换还容易精神分裂。于是你自然会想到拆出多个Agent各管一摊——这就是多智能体系统。

3.1 三种常用协作拓扑：串行、编排执行与黑板模式

多智能体系统的结构设计，基本绕不开三种拓扑。

第一种是串行流水线：Agent A的最终输出，直接作为Agent B的输入，B的输出进C，链路固定。这种模式最简单，适合流程非常确定的场景，比如“需求分析→代码生成→测试检查”。

第二种是编排-执行模式：一个主控Agent负责任务分解，把一个大任务拆成几个子任务，分发给不同的执行Agent，最后再把结果汇总。这种模式灵活度更高，主控Agent可以动态决定谁干什么，适合需求变化较多的场景。

第三种是黑板模式：多个Agent共享一块“黑板”（一块共享的存储区域），谁有新信息就往上面写，谁需要信息就上去读，彼此不需要直接对话。这种模式适合探索性任务，但实现起来复杂，坐标跟踪和信息版本管理都是坑。

三种模式没有绝对的好坏，关键看你的任务边界有多清晰。

3.2 角色划分：写完代码谁来Review

多智能体系统不是随便把几个Agent扔到一起就能跑起来的，关键在于角色职责要清晰。我最常用的切分方式是按“专业分工+质量闭环”来拆：需求Agent负责把模糊的用户想法翻译成可验收的开发需求；代码Agent负责根据需求产出实现；测试Agent负责挑毛病，发现问题就返回给代码Agent修。

这里要特别提醒一句：每个Agent的System Prompt都要写清楚三件事——你是谁、你要输出什么格式、你什么时候把任务交回给谁。如果不定义清楚，你就会看到两个Agent互相“礼貌地客气”：一个说“请您补充场景”，另一个说“好的，已补充”，来回十轮没有任何实际产出。

角色数量上，新手千万别一上来就搞七个Agent的大团队。三个以内最合适：角色越多，消息流转就越复杂，排查问题的时间成倍增长。我见过有人把八个角色塞进一个Demo里，结果一半时间在处理Agent之间互相误解，任务产出反而不如单Agent。

3.3 通信协议：用结构化消息避免“鸡同鸭讲”

多Agent之间怎么“说话”，是另一个新手爱踩的坑。最自然的方案是让Agent直接用自然语言对话，但一旦消息变长，A的理解和B的理解很容易出现偏差。更稳的做法是给消息定义一套结构化格式，让每个Agent顺着字段去解析。

我习惯用下面这种纯JSON格式做通信：

{ "sender": "requirement_agent", "receiver": "code_agent", "task_type": "develop_request", "payload": { "requirement_id": "REQ-001", "spec": "用户输入城市名，返回七日天气走势图", "constraints": ["依赖免费天气接口", "限Python实现"] }, "status": "pending", "confidence": 0.9, "created_at": "2025-01-01T10:00:00Z" }

这种消息有几个好处：sender和receiver让链路清晰可追溯；status字段方便主控判断该继续还是该跳过；confidence是给下游Agent看的“你最好复核一下这里”的信号。哪怕你的多智能体系统暂时不接复杂框架，用这种结构化文本做交接，也能让系统稳定好几个档次。

4. 手把手搭一个“需求分析+代码生成+测试检查”三智能体Demo

理论讲再多，不如动手跑一个。下面这个Demo没有用任何Agent编排框架，纯靠Python代码和几十行封装逻辑实现。这样做的好处是你能看清每一步到底发生了什么，而不是被框架的抽象层遮住眼睛。

4.1 环境准备与基础函数封装

环境准备只需要：一个能调用大模型API的Python环境，以及一把API密钥。不管你是用闭源服务还是本地部署的开源模型，套路都一样。

先把LLM调用封装成一个统一函数，方便后续三个Agent复用：

import json def call_llm(messages, tools=None, temperature=0.2): response = llm_client.complete( model="your-model-name", messages=messages, tools=tools, temperature=temperature, ) return response def run_simple_agent(system_prompt, user_task, tools=None, max_steps=5): messages = [ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_task}, ] for _ in range(max_steps): response = call_llm(messages, tools=tools) if response.tool_call: tool_name = response.tool_call.name tool_result = execute_tool(tool_name, response.tool_call.arguments) messages.append(response.message) messages.append({ "role": "tool", "tool_call_id": response.tool_call.id, "content": tool_result, }) else: return response.content return "Agent达到最大步数，返回当前最后输出"

这套循环本身不神秘，但它是所有Agent系统的地基。你把run_simple_agent写出来之后，单Agent先跑通，再加多角色就有底了。

4.2 三个Agent的Prompt设计要点

三个Agent的Prompt是一点点试出来的。核心要点是：不要写“你是一个智能助手”，要写“你是需求分析Agent，你的任务是把模糊需求转成结构化规格说明，输出必须包含以下字段……”。

需求分析Agent的Prompt模板，我推荐强调“输出物校验”：

你是需求分析Agent。接收用户的一句话需求后，你必须输出： 1. 用户故事（我作为谁，想要什么，以便什么） 2. 功能拆解（列出核心功能点和边界条件） 3. 验收标准（能通过什么测试就算完成） 4. 未确认事项（有哪些信息缺失，需要在交付前与用户确认） 注意：如果输入需求本身含糊，不要自动脑补，要把疑问列入未确认事项。

代码生成Agent的Prompt模板，强调“可运行”和“依赖看清楚”：

你是代码生成Agent。你将收到一份需求规格说明。请输出完整可运行的Python代码。 要求： - 每个函数必须带Docstring和输入输出示例 - 涉及外部依赖时，在代码头部注释说明安装方式 - 如果规格说明存在信息缺失，在代码注释中标记“待确认”，不要擅自假设 - 输出格式为单个代码块

测试检查Agent的Prompt模板，强调“挑刺”而不是“夸赞”：

你是测试检查Agent。你将收到需求规格和对应代码。请做代码Review，输出： 1. 与需求规格的逐条对照结果 2. 潜在Bug清单（按严重程度排序） 3. 修复建议（具体到函数级别） 4. 结论：通过 / 退回修复 / 需补充需求信息 如果代码与规格不一致，直接标记“退回修复”。

这三段Prompt看起来简单，但每一句背后都有踩坑的影子。比如“未确认事项”那一条，是见了太多次需求Agent自信满满地瞎编功能之后加上的。

4.3 主控循环与结果流转

三个Agent各自是“独立会话”，消息不在它们之间共享。主控程序负责把上一个Agent的输出，作为下一个Agent的输入，并在测试不通过时打回重试。

主控循环长这样：

def multi_agent_pipeline(user_input, max_review_rounds=3): spec = run_simple_agent(REQUIREMENT_PROMPT, user_input) save_product("spec.md", spec) code_round = "无" review = "无" for round_idx in range(max_review_rounds): code = run_simple_agent( CODE_AGENT_PROMPT, f"需求规格如下:\n{spec}\n上次代码:\n{code_round}\n上次测试意见:\n{review}", ) save_product("code.py", code) review = run_simple_agent( TEST_AGENT_PROMPT, f"需求规格:\n{spec}\n代码实现:\n{code}", ) save_product("review.md", review) if "结论：通过" in review: return {"spec": spec, "code": code, "review": review, "rounds": round_idx + 1} code_round = code return {"spec": spec, "code": code, "review": review, "rounds": max_review_rounds}

这个流程里有几个设计值得注意。第一，每轮都把上一轮的代码和测试意见喂给代码Agent，让它基于反馈修复，而不是重写；第二，测试Agent每次拿到的是最新的代码和原始需求，避免它用旧记忆判断；第三，每个中间产物都落盘到文件，方便你排查问题。

我拿“帮我写一个命令行计算器，支持加减乘除和括号”试过一次，第一轮生成的代码在括号解析上直接抛异常，测试Agent给出了“括号嵌套场景未处理”的意见，代码Agent第二轮补了递归解析逻辑，第三轮才通过。整个过程大概消耗了一万多Token，如果没做落盘，我根本不知道是哪一轮引入的Bug。

5. 上线多智能体前必踩的五个坑（含解决办法）

Demo能跑通只是第一步。真把这套东西放到稍微真实一点的任务里，下面的五个坑你大概率会碰到，而且几乎每个都会让你怀疑人生。

5.1 Token烧钱：上下文指数膨胀的刹车策略

多智能体系统最隐蔽的耗钱点，就是各路上下文被来回拷贝。需求Agent的输出要传给代码Agent，代码Agent的代码要传给测试Agent，测试Agent的意见又传回代码Agent——如果中间再有几次工具调用，每个环节的消息都带着完整历史，Token消耗是成倍增长的。

我的刹车策略有三招：

• 每次传任务时只传“必要的最新信息”，不要把上个Agent的全部对话历史带过去；
• 中间产物超过一定长度，先让模型做一次摘要，再把摘要传给链路下游；
• 给每个Agent设置独立的上下文上限，比如最多保留最近8条消息，超出就触发摘要归档。

5.2 死循环：让Agent学会“承认失败”

多Agent系统最常见的失败模式不是报错，而是“无进展空转”。比如测试Agent每次都能挑出新问题，代码Agent每次修复后测试Agent又提一个不同的问题，永远到不了“通过”。

解决办法是双管齐下。第一，前面提过，max_steps必须设上限；第二，在Prompt里主动给出终止条件，例如告诉Agent“如果你连续两轮修复后测试意见的核心问题没有变化，直接输出‘无法解决’并返回当前代码和已尝试方案”。别不好意思，让人承认不行很难，但让Agent承认失败是必须的，否则你的系统会在没有意义的循环里烧光预算。

5.3 幻觉扩散：下游Agent轻信上游结论

单Agent的幻觉问题，到多Agent系统里会变成“幻觉扩散”：需求Agent漏掉一个关键场景，代码Agent很忠实地按残缺需求写代码，测试Agent也没发现，整个链路错得整整齐齐。

应对方案是在消息结构里引入“置信度”和“未确认事项”字段。上游Agent对拿不准的内容必须显式标注，下游Agent遇到置信度较低的关键输入时，可以选择触发人工确认节点。我在实践里会另加一条规则：凡是涉及权限、金额、删除操作的关键输出，必须经过人工节点，不允许全自动执行。这是对业务负责。

5.4 单点卡死：超时与降级

真实世界里，你调用的大模型API随时可能超时、限流或者返回坏格式。多Agent系统里任何一个Agent卡住，整条流水线就停摆。

我在每个Agent调用外层都包了一层超时控制和重试机制：

def safe_call_llm(messages, tools=None, timeout=30, retries=2): for attempt in range(retries): try: return call_llm(messages, tools=tools) except TimeoutError: if attempt == retries - 1: return fallback_result("当前任务因超时被跳过，请主控降级处理")

更关键的是主控层的降级策略。我会给每个Agent任务定义“最低可接受产物”：如果测试Agent完全不可用，至少要把代码Agent产出的代码和“未测试”的警告交给用户，而不是让整个系统崩溃。有降级路径的系统，才配有资格谈上线。

5.5 难调试：为每个Agent加日志和“思考过程”快照

多Agent系统的排错难度，是单Agent的指数级。因为输出不对的时候，你压根不知道是哪一环出了问题：是需求拆错了，代码写错了，还是测试标准错了？

我的习惯是每次任务跑完，都生成一份JSONL运行日志，每个关键节点记录一条：

{ "time": "2025-01-01T10:00:00Z", "agent": "code_agent", "round": 2, "input_spec": "命令行计算器，支持括号", "output_code_preview": "def evaluate(expr): ...", "tool_calls": ["run_python_syntax_check"], "tokens_used": 3200, "latency_ms": 2100 }

排查问题的时候，我会先看“哪一层的输出和预期差距最大”，再回去看那个Agent的输入和相关工具结果。没有日志，多智能体系统调试就是纯粹靠猜。

6. 从我自己的实践看：小白最容易高估和低估的事情

6.1 高估了“自动”：大部分时间花在拆任务和写Prompt

网上那些Agent演示视频看多了，会让人产生错觉：多智能体系统是“输入一句话，剩下全自动”。实际做起来完全不是这样。我搭这个三Agent Demo时，写业务循环只花了个把小时，但把三个Agent的Prompt打磨到“互相交接基本不跑偏”，花了好几天。

真正有价值的工作，是任务拆解：哪些环节适合让模型自由发挥，哪些环节必须用代码校验，哪些信息必须在交接时强约束。这本质上是系统设计能力，不是提示词工程能替代的。所以我的建议是：不要迷恋“全自动”，先追求每个环节的输出“稳定可校验”。

6.2 低估了评测：没有评分标准就无法迭代

大部分小白做完一个Agent Demo就停了，因为他“感觉效果还行”。但“感觉还行”是无法支撑后续优化的。你要想迭代Prompt、换模型、调参数，就必须先有一把尺子。

我自己会给每个Agent任务准备一组评测用例，比如20条需求代表不同场景，跑完之后记录四个指标：首次通过率、平均修复轮数、平均Token成本、人工介入次数。改一版Prompt，就用同一组用例重跑，对比前后变化。没有这个基准，你连“这版到底是变好了还是变坏了”都说不清。

6.3 实用建议：从单Agent做起，再上多智能体

最后一条经验，也是我最想对小白说的话：不要一上来就追求多智能体。如果你的任务用“一个Agent + 两个工具”就能跑通，那就别拆成三个角色。多智能体带来的收益是分工和并行，但代价是调试复杂度和Token成本成倍上升。

什么情况下值得上多智能体？我的判断标准有三条：任务天然能被拆成多个专业角色；单个Agent的上下文明显不够用；某个环节需要独立迭代而不影响整体。满足其中两到三条，再考虑拆。

我个人的学习路径是先花了两周把单Agent的工具调用和记忆跑熟，再用简单双Agent练手，最后才把三个角色串起来。每一次往上加，都是一次可预期的成本增加，而不是“免费的午餐”。

聊到这儿，基本把我这段时间摸索出的Agent和多智能体系统设计经验都交代完了。我心里最深的感触是：这套东西看着门槛不高，真正做出来稳定可用，拼的从来不是谁的模型强、谁的框架新，而是谁对任务拆解更细、对边界条件更敏感、对评测更认真。哪怕你只是个刚开始写代码的萌新，照着上面的方式先跑通一个三Agent小Pipeline，再不断往里面加你的业务细节，你对AI原生架构的理解会比看一百篇概念文章都扎实。