简介：这份PDF文档系统梳理了华为首次提出的智能体参考架构，面向政企数字化转型决策者、智慧城市方案设计者及AI架构学习者。内容围绕云网边端协同展开，涵盖智能交互、智能联接、智能中枢、智慧应用四层架构，并延伸至全场景智慧城市、企业与行业三个层面，同时结合新基建战略与鹏城智能体等落地案例，帮助读者理解智能体如何重构体验、优化流程并支撑未来五到十年的竞争力。资源包内含1个PDF文件，约503KB，篇幅精炼，适合快速通读与要点摘录。目前已有75人学习，可作为智慧城市顶层设计与政企智能升级方向的入门参考材料，便于在方案讨论或技术选型时快速建立整体认知框架。
1. 一份被名字耽误的智能体入门材料：从概念到落地的完整拆解
很多人第一次看到「什么是智能体.pdf」这个文件名，第一反应是——又是一份概念科普。我最初也这么想，直到把它从头翻完，才发现这份材料的价值不在「定义智能体是什么」，而在于它把智能体从概念到工程落地的那条链路讲通了。它适合两类人：一类是刚接触 AI 应用开发、分不清 Agent、Workflow、Chain 区别的从业者；另一类是想把大模型能力封装成可调度、可编排、可观测系统的工程师。这份材料不是代码仓库，也不是某个框架的官方文档，它更像一份结构化的知识底稿，把智能体的核心组件、决策循环、工具调用、记忆机制这些关键模块拆开讲了一遍。如果你正在做 AI 应用架构选型，或者被「智能体到底怎么落地」这个问题卡住，这份 PDF 值得花两个小时认真过一遍。
2. 智能体的核心组件拆解：从感知到执行的闭环怎么搭
2.1 智能体不是「更聪明的聊天机器人」
很多人把智能体理解成「带记忆的 ChatGPT」，这个认知偏差会导致架构设计直接跑偏。聊天机器人的核心是「一轮输入对应一轮输出」，而智能体的核心是「一个目标驱动多轮决策循环」。这份材料里把智能体的最小闭环拆成四个模块：感知（Perception）、决策（Decision）、执行（Action）、记忆（Memory）。四个模块缺一个，系统就会退化成脚本或者退化成聊天框。
感知模块负责把外部输入转成模型能理解的格式。常见做法是：用户输入走一遍意图识别，把自然语言转成结构化任务描述；环境状态通过 API 拉取后序列化成 JSON 注入上下文。这一步的坑在于，很多人直接把原始用户输入丢给模型，结果模型在长上下文里迷失目标。我一般会强制加一层「任务重述」，让模型先用自己的话把目标写一遍，再进入决策循环。
决策模块是智能体的核心。材料里提到两种主流范式：ReAct（Reasoning + Acting）和 Plan-and-Execute。ReAct 是边想边做，每一步都根据上一步结果调整；Plan-and-Execute 是先出完整计划再逐步执行。前者适合探索性任务，后者适合流程确定性高的场景。选型时看任务的可逆性——如果每一步做错了都能回滚，用 ReAct；如果中间步骤有副作用（比如发邮件、写数据库），先用 Plan-and-Execute 把计划锁死。
执行模块负责把决策转成具体工具调用。这里的关键是工具描述的质量。材料里给了一个很实用的原则：工具描述要写成「什么时候用」而不是「这个工具是什么」。比如一个搜索工具，描述写成「当需要获取实时信息或验证事实时调用」，比写成「搜索互联网」的命中率高出一截。
记忆模块分短期和长期。短期记忆就是上下文窗口里的对话历史，长期记忆通常用向量库做检索增强。材料里提醒了一个容易被忽略的点：不是所有历史都值得存。我一般会加一个「记忆压缩」步骤，每 N 轮把历史摘要一次，只保留目标、关键决策和未完成事项。
2.2 用 Python 搭一个最小可运行智能体循环
理论讲完，直接上手。下面这段代码是一个不依赖任何框架的最小智能体循环，用 OpenAI 兼容接口就能跑。它的作用是让你看清智能体的骨架——去掉所有封装之后，核心就是一个 while 循环加一个工具路由。
import json from openai import OpenAI client = OpenAI(base_url="https://api.example.com/v1", api_key="your-key") # 工具定义：描述写清楚"什么时候用"，而不是"是什么" tools = [ { "type": "function", "function": { "name": "search_knowledge", "description": "当需要查询内部知识库或验证事实时调用，输入为自然语言查询语句", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "查询语句"} }, "required": ["query"] } } } ] def execute_tool(name, args): # 实际项目中这里路由到真实工具 if name == "search_knowledge": return f"模拟检索结果：关于'{args['query']}'的资料已找到" return "未知工具" def agent_loop(user_goal, max_steps=5): messages = [ {"role": "system", "content": "你是一个任务型智能体。先重述目标，再决定是否调用工具。每次只做一个决策。"}, {"role": "user", "content": user_goal} ] for step in range(max_steps): resp = client.chat.completions.create( model="gpt-4o-mini", messages=messages, tools=tools, tool_choice="auto" ) msg = resp.choices[0].message messages.append(msg) # 如果没有工具调用，说明模型认为任务完成 if not msg.tool_calls: return msg.content # 执行所有工具调用并回填结果 for call in msg.tool_calls: args = json.loads(call.function.arguments) result = execute_tool(call.function.name, args) messages.append({ "role": "tool", "tool_call_id": call.id, "content": result }) return "达到最大步数，任务未完成" print(agent_loop("帮我查一下智能体的记忆机制有哪些常见实现"))这段代码的逻辑说明：agent_loop是核心循环，每一步都让模型决定「继续调工具」还是「输出最终答案」。max_steps是安全阀，防止模型陷入死循环。tool_choice="auto"让模型自己判断是否需要工具。参数上，max_steps一般设 5 到 10，太少任务做不完，太多容易烧 token。messages列表就是短期记忆，每轮追加，不做压缩的话长任务会爆上下文。
跑通之后你会看到一个关键现象：模型有时候会在第一步就重述目标，有时候直接调工具。这个行为不稳定是正常的，材料里也提到了——智能体的确定性不来自模型，来自你的循环控制和工具设计。想让行为稳定，要么在 system prompt 里加约束，要么在代码层做状态机。
2.3 工具调用的参数设计与失败处理
工具调用是智能体最容易翻车的地方。材料里列了几个常见问题：参数类型不匹配、工具返回格式模型看不懂、工具超时没有兜底。我自己的血泪经验是，工具返回结果一定要做「模型友好化」处理。比如数据库查询返回一堆字段，不要直接丢给模型，先转成自然语言摘要再注入。
def safe_tool_call(name, args, timeout=10): try: # 参数校验：模型可能传错类型 if name == "search_knowledge" and not isinstance(args.get("query"), str): return "参数错误：query 必须是字符串" result = execute_tool(name, args) # 结果截断：防止超长返回撑爆上下文 if len(str(result)) > 2000: result = str(result)[:2000] + "...(已截断)" return result except TimeoutError: return "工具调用超时，请尝试其他方式或告知用户稍后重试" except Exception as e: return f"工具执行失败：{str(e)}，请检查参数或换一种方式"这段代码的关键在「防御性编程」。模型不是可靠的调用方，它会传错参数、会在不该调的时候调。safe_tool_call做了三件事：参数类型校验、结果截断、异常兜底。参数上，timeout根据工具类型设，检索类 10 秒够用，生成类可能要 30 秒以上。结果截断阈值 2000 字符是个经验值，超过这个长度模型注意力会分散。
3. 记忆机制与上下文管理：让智能体记住该记的
3.1 短期记忆的压缩策略
短期记忆就是上下文窗口。材料里给了一个很实用的分类：目标记忆、决策记忆、状态记忆。目标记忆是用户最初的任务描述，决策记忆是每一步做了什么选择，状态记忆是当前环境的状态快照。这三类记忆的保留优先级不同——目标记忆永远保留，决策记忆保留最近 N 步，状态记忆只保留最新。
我一般用「滑动窗口 + 摘要」的组合策略。每轮对话追加到 messages 列表，当 token 数超过阈值（比如 3000）时，把最早的一半消息做一次摘要，用摘要替换原始消息。摘要的 prompt 可以这样写：「用三句话总结以下对话中与当前目标相关的关键信息和未完成事项，忽略寒暄和重复内容。」
def compress_messages(messages, keep_recent=4): if len(messages) <= keep_recent + 2: return messages # 保留 system prompt 和最近几轮 system_msg = messages[0] recent = messages[-keep_recent:] to_compress = messages[1:-keep_recent] # 调用模型做摘要 summary_resp = client.chat.completions.create( model="gpt-4o-mini", messages=[ {"role": "system", "content": "用三句话总结以下对话中与任务目标相关的关键信息和未完成事项。"}, {"role": "user", "content": json.dumps(to_compress, ensure_ascii=False)} ] ) summary = summary_resp.choices[0].message.content return [system_msg, {"role": "system", "content": f"历史摘要：{summary}"}] + recent参数说明：keep_recent=4表示保留最近 4 条消息不压缩，这个值根据任务复杂度调，简单任务 2 到 3 就够，复杂任务可以到 6。摘要模型用便宜的小模型就行，不需要用主力模型。注意摘要会丢失细节，所以关键决策点最好在摘要 prompt 里明确要求保留。
3.2 长期记忆的检索增强实现
长期记忆解决的是「跨会话记住用户偏好和历史决策」的问题。材料里提到的方案是向量库加检索。常见做法是：把重要交互存成向量，查询时用相似度检索召回。但这里有个坑——不是所有交互都值得存。我一般只存三类：用户明确表达的偏好、已经确认的决策、失败过的方案（避免重复踩坑）。
# 伪代码示意长期记忆的存取逻辑 def save_long_term_memory(content, memory_type): # memory_type: preference / decision / failure embedding = get_embedding(content) vector_db.upsert({ "id": generate_id(), "vector": embedding, "metadata": {"type": memory_type, "timestamp": now()} }) def recall_long_term_memory(query, top_k=3): embedding = get_embedding(query) results = vector_db.search(embedding, top_k=top_k) # 按类型加权：偏好和决策优先于普通记录 weighted = sorted(results, key=lambda x: x["score"] * type_weight(x["metadata"]["type"]), reverse=True) return [r["content"] for r in weighted]参数上，top_k一般设 3 到 5，太多会引入噪声。type_weight是个经验函数，偏好和决策权重设 1.2，普通记录设 1.0，失败记录设 0.8（避免模型被失败经验过度影响）。检索回来的内容不要直接拼到上下文，先做一次相关性过滤——让模型判断「这条记忆和当前任务是否相关」，不相关的丢掉。
3.3 上下文窗口的预算分配
材料里给了一个很实用的框架：把上下文窗口当成预算来分配。系统提示占 10%，工具描述占 15%，长期记忆占 20%，短期记忆占 35%，输出预留占 20%。这个比例不是固定的，但思路是对的——每一块都要有配额，不能无限膨胀。
我自己的习惯是，在代码里显式做 token 计数，超过预算就触发压缩或丢弃。常见做法是用 tiktoken 做计数，但如果你用的是非 OpenAI 模型，可以用字符数粗略估算（中文 1 字符约 1.5 token，英文 1 字符约 0.25 token）。这个估算不精确，但足够做预算控制。
4. 多智能体协作与任务编排：什么时候该拆，什么时候不该拆
4.1 单智能体 vs 多智能体的选型边界
材料里对多智能体的态度很克制——它明确说了「多智能体不是默认选项」。很多团队一上来就搞一堆 Agent 互相通信，结果调试成本爆炸。选型边界其实很简单：如果任务可以拆成独立的、有明确输入输出的子任务，且子任务之间不需要频繁共享中间状态，可以考虑多智能体；如果任务是一个连续决策流，中间状态高度耦合，单智能体加工具就够了。
我一般用「通信频率」来判断。两个子任务之间如果每步都要交换信息，拆成两个 Agent 反而增加同步开销。如果两个子任务只在开始和结束时有交互，拆开就合理。材料里给了一个参考：子任务数量超过 5 个、且每个子任务有独立的工具集时，多智能体的收益开始显现。
4.2 用状态机编排多智能体
多智能体的编排方式常见有三种：中心化调度、去中心化协商、流水线。材料里重点讲了中心化调度，因为它的可控性最好。中心化调度就是一个 Orchestrator Agent 负责拆任务、派任务、收结果，其他 Agent 只负责执行。
# 中心化调度的简化实现 class Orchestrator: def __init__(self): self.workers = { "researcher": ResearchAgent(), "writer": WriterAgent(), "reviewer": ReviewAgent() } def run(self, task): # 第一步：拆解任务 plan = self.decompose(task) results = {} for step in plan: worker = self.workers[step["worker"]] # 注入前序结果作为上下文 context = {k: v for k, v in results.items() if k in step.get("depends_on", [])} results[step["id"]] = worker.execute(step["instruction"], context) return self.aggregate(results) def decompose(self, task): # 实际项目中这里调用模型做任务拆解 return [ {"id": "r1", "worker": "researcher", "instruction": "检索相关资料", "depends_on": []}, {"id": "w1", "worker": "writer", "instruction": "基于资料撰写初稿", "depends_on": ["r1"]}, {"id": "v1", "worker": "reviewer", "instruction": "审核初稿并给出修改意见", "depends_on": ["w1"]} ]这段代码的关键在depends_on字段——它定义了任务之间的依赖关系，Orchestrator 根据依赖决定执行顺序。参数上，decompose返回的计划质量直接决定系统上限，我一般会在 prompt 里要求模型「每个子任务必须有明确的输入和输出，且输出可以被下一个任务直接使用」。aggregate负责把多个子任务结果合并成最终输出，合并策略根据任务类型定，常见的是拼接加摘要。
4.3 多智能体的通信协议设计
多智能体之间怎么传消息，材料里给了一个原则：消息格式要结构化，不要传自然语言。自然语言消息在 Agent 之间传递会引入歧义，而且每次都要重新解析。常见做法是定义一个 JSON schema，所有 Agent 的输入输出都按这个 schema 来。
{ "task_id": "r1", "status": "completed", "output": { "type": "research_result", "content": "检索到的关键信息摘要", "confidence": 0.85, "sources": ["source1", "source2"] }, "next_action": "pass_to_writer" }这个 schema 里，status让 Orchestrator 知道任务是否完成，confidence让下游 Agent 知道结果可信度，next_action是可选的建议下一步。参数上，confidence低于 0.6 时我一般会触发重试或人工介入。sources字段用于追溯，出问题时能定位到原始数据。
5. 避坑与排查：智能体落地时最容易翻车的五个地方
5.1 模型陷入循环调用同一个工具
现象：智能体反复调用同一个工具，参数几乎不变，步数耗尽也没产出结果。原因通常是工具返回结果没有给模型提供新信息，或者 system prompt 里没有「避免重复调用」的约束。解决方式是在工具返回里加一个「已尝试过的方式」列表，让模型看到自己已经做过什么；同时在循环控制里加一个「相同工具连续调用超过 2 次就强制中断」的规则。
5.2 工具描述太模糊导致调用错误
现象：模型在不该调工具的时候调了，或者调了错误的工具。原因多半是工具描述写成了「这个工具是什么」而不是「什么时候用」。解决方式是重写工具描述，用「当……时调用」的句式，并在参数描述里给出具体示例。我一般会拿 10 条典型用户输入做回归测试，看工具命中率是否达标。
5.3 上下文超长导致模型「失忆」
现象：任务进行到一半，模型突然忘了最初的目标，开始胡言乱语。原因是上下文窗口被历史消息撑满，最早的目标描述被挤出去了。解决方式是做上下文预算控制，目标描述永远放在 system prompt 里而不是对话历史里，历史消息定期压缩。参数上，当 token 数超过窗口的 70% 时就该触发压缩，不要等到 100%。
5.4 工具返回格式模型解析不了
现象：工具返回了正确的数据，但模型理解错了或者直接忽略。原因是返回格式太复杂或者包含模型不熟悉的字段名。解决方式是在工具返回后加一层「格式化」步骤，把结果转成自然语言摘要再注入。常见做法是让一个小模型做格式化，成本低且效果好。
5.5 多智能体之间状态不同步
现象：Agent A 认为任务完成了，Agent B 还在等 A 的输出。原因是通信协议里没有明确的状态字段，或者状态更新有延迟。解决方式是定义严格的状态机，每个 Agent 的输出必须包含status字段，Orchestrator 只在收到completed状态后才推进下一步。参数上，加一个超时机制，超过 N 秒没收到状态更新就标记为失败并触发重试。
6. 从能跑到好用：智能体评估与迭代的一个具体技巧
智能体做完之后，怎么判断它「好用」？材料里没有给完整的评估框架，但给了一个很实用的切入点：用「任务完成率」和「平均步数」两个指标做基线。任务完成率低于 70% 说明工具设计或 prompt 有问题；平均步数超过预期步数的 2 倍说明模型在绕路。这两个指标不需要标注数据，跑一批测试用例就能算出来。
我自己的习惯是建一个「回归测试集」，包含 20 到 30 条典型任务，每次改完 prompt 或工具描述就跑一遍。测试集要覆盖三类场景：简单任务（1 到 2 步完成）、中等任务（3 到 5 步）、边界任务（工具失败、参数缺失、目标模糊）。边界任务最重要，因为线上出问题多半出在边界上。
# 回归测试的简化框架 test_cases = [ {"goal": "查询智能体的记忆机制", "expected_steps": 2, "expected_tools": ["search_knowledge"]}, {"goal": "帮我写一份智能体选型对比", "expected_steps": 4, "expected_tools": ["search_knowledge", "write_doc"]}, {"goal": "把不存在的文件删掉", "expected_steps": 1, "expected_tools": [], "expect_failure": True} ] def run_regression(agent, cases): results = [] for case in cases: output = agent.run(case["goal"]) steps = agent.last_run_steps tools_used = agent.last_run_tools results.append({ "goal": case["goal"], "completed": output is not None, "steps": steps, "tools_match": set(tools_used) == set(case["expected_tools"]), "step_ok": steps <= case["expected_steps"] * 2 }) pass_rate = sum(1 for r in results if r["completed"] and r["tools_match"]) / len(results) return pass_rate, results这个框架的关键在expect_failure字段——有些任务本来就该失败，模型能正确识别并告知用户，也算通过。参数上，expected_steps * 2是容忍上限，超过说明效率有问题。tools_match用集合比较，不关心调用顺序。
从那以后我每次改完智能体的 prompt 或工具描述，都强制走一遍回归测试，哪怕只改了一个词。因为智能体的行为是涌现的，你永远不知道哪个改动会触发连锁反应。希望这份材料和你自己的测试集，能帮你把智能体从「能跑」推到「好用」。
本文还有配套的精品资源，点击获取
