在 AI Agent 开发中Prompt 组装是决定 Agent 推理能力、工具调用准确性、场景适配性的核心底层逻辑。很多 Agent 项目看似功能复杂其核心底层均依靠一套分层、动态、可扩展的 Prompt 组装机制。本文将基于完整的项目源码逻辑层层拆解AI Agent 三段式 Prompt 组装架构涵盖模板定义、动态注入、LLM 格式化全流程附源码片段、执行时序、数据流图与核心设计思想帮你彻底吃透 Agent Prompt 运行原理。一、核心整体架构三层分层设计项目将 Prompt 组装拆分为三层独立职责各层各司其职、解耦协作兼顾静态模板统一性与动态场景灵活性Layer 1模板定义层app/prompt/*.py静态字符串模板为每一类 Agent 独立配置专属的系统提示词SYSTEM_PROMPT和下一步思考提示词NEXT_STEP_PROMPT是所有 Prompt 的基础模板。Layer 2Agent 注入层think() 方法核心动态逻辑层负责读取静态模板、填充动态占位符、将下一步提示词注入对话记忆memory实现每轮推理的动态引导。Layer 3LLM 格式化层ask_tool / format_messagesAPI 适配层将项目自定义的 Message 对象转为 OpenAI API 兼容字典格式专门处理多模态图片、Token 计算、消息格式标准化。架构极简总结静态模板定义 → 动态内容注入 → 标准化 API 格式化二、模板定义层各类型 Agent 专属 Prompt 模板项目中不同功能的 Agent 均拥有独立的 Prompt 模板文件区分系统定位SYSTEM_PROMPT和迭代思考引导NEXT_STEP_PROMPT部分模板支持动态占位符。所有 Agent 模板配置汇总如下文件Agent 类型SYSTEM_PROMPT系统定位NEXT_STEP_PROMPT下一步引导toolcall.pyToolCallAgentYou are an agent that can execute tool callsIf you want to stop interaction, use terminate toolmanus.pyManusYou are OpenManus, an all-capable AI assistant... 含 {directory} 动态占位符主动选择工具、拆解任务、解释执行结果browser.pyBrowserAgent详细浏览器自动化规则JSON响应、元素交互、导航、错误处理含 {url_placeholder} 等5个动态占位符mcp.pyMCPAgentMCP协议说明、动态工具适配、异常错误处理规则思考并选择最优 MCP 工具执行下一步操作swe.pySWEAgent命令行编程环境专属定位限制单次仅调用一个工具空字符串无需额外引导planning.pyPlanningAgent结构化任务规划专家定位校验计划完整性执行规划的下一步任务visualization.pyVisualizationAgent数据分析与可视化专属定位含 {directory} 占位符单次仅选一个工具遇到报错自动修复重试三、Agent 注入层think() 核心双路径逻辑注入层是 Prompt 动态组装的核心通过think()方法实现两条核心路径系统提示词独立前置、下一步提示词入库迭代两者逻辑完全隔离。3.1 System Prompt永久前置不参与 Memory 截断系统提示词用于定义 Agent 核心身份与能力设计上不存入对话记忆 memory每次调用 LLM 时单独前置拼接永久不受max_messages100截断规则影响保证 Agent 身份定位全程不变。核心源码toolcall.py 47-55行response await self.llm.ask_tool( messagesself.messages, # 对话历史不含 system prompt system_msgs( [Message.system_message(self.system_prompt)] if self.system_prompt else None ), toolsself.available_tools.to_params(), tool_choiceself.tool_choices, )LLM 内部拼接逻辑llm.py 684-688行核心特性System 消息永远位于消息列表最首位全程保留不会被对话历史截断。3.2 Next Step Prompt逐轮注入 Memory引导迭代思考下一步提示词是每轮推理的引导核心会以伪用户消息的形式追加到 memory 末尾强制引导 LLM 基于当前对话状态思考后续操作实现任务迭代。核心源码toolcall.py 41-43行if self.next_step_prompt: user_msg Message.user_message(self.next_step_prompt) self.messages [user_msg] # 追加到 memory 对话历史末尾执行效果每一轮 Agent 推理都会新增一条用户侧引导消息让 LLM 持续对齐任务目标、推进流程。四、LLM 格式化层统一 API 消息格式format_messages()是底层适配核心负责将项目自定义的 Pydantic Message 对象转为标准 OpenAI API 字典格式同时专门处理多模态图片资源兼容图文混合推理。核心源码llm.py 267-352行staticmethod def format_messages(messages, supports_imagesFalse) - List[dict]: formatted_messages [] for message in messages: # Pydantic 对象转为字典 if isinstance(message, Message): message message.to_dict() # 处理 base64 图片适配 OpenAI 多模态格式 if supports_images and message.get(base64_image): message[content] [ {type: text, text: message[content]}, {type: image_url, image_url: { url: fdata:image/jpeg;base64,{message[base64_image]} }} ] del message[base64_image] # 过滤有效消息 if content in message or tool_calls in message: formatted_messages.append(message) return formatted_messages核心能力自动兼容纯文本/图文多模态场景统一 API 入参格式上层业务无需感知底层适配逻辑。五、动态 Prompt 占位符机制场景化实时适配静态模板无法适配动态场景如浏览器 URL、页面滚动位置、标签页数量因此项目设计了动态占位符填充机制以 BrowserAgent、Manus Agent 为典型代表。5.1 BrowserAgent 动态 Prompt 逻辑BrowserAgent 每次推理前会实时获取浏览器状态填充 5 个专属占位符同时支持截图注入多模态消息。think() 主流程源码browser.py 120-125行async def think(self) - bool: self.next_step_prompt ( await self.browser_context_helper.format_next_step_prompt() ) return await super().think()占位符填充核心逻辑browser.py 47-79行async def format_next_step_prompt(self) - str: # 1. 获取浏览器实时状态 browser_state await self.get_browser_state() # 2. 提取状态信息组装占位符内容 url_info fURL: {browser_state.url}, Title: {browser_state.title} tabs_info f{len(tabs)} tab(s) available content_above_info f({pixels_above} pixels) if pixels_above else content_below_info f({pixels_below} pixels) if pixels_below else # 3. 截图注入将浏览器截图转为多模态用户消息 if self._current_base64_image: image_message Message.user_message( contentCurrent browser screenshot:, base64_imageself._current_base64_image, ) self.agent.memory.add_message(image_message) # 4. 批量替换模板占位符 return NEXT_STEP_PROMPT.format( url_placeholderurl_info, tabs_placeholdertabs_info, content_above_placeholdercontent_above_info, content_below_placeholdercontent_below_info, results_placeholderresults_info, )5.2 Manus Agent 动态切换 PromptManus 作为通用 Agent支持场景自适应 Prompt 切换检测到使用浏览器工具时自动切换为浏览器专属动态 Prompt执行完成后恢复默认模板。核心源码manus.py 140-165行async def think(self) - bool: # 检测最近消息是否调用浏览器工具 browser_in_use any( tc.function.name BrowserUseTool().name for msg in recent_messages if msg.tool_calls for tc in msg.tool_calls ) # 浏览器场景动态替换Prompt if browser_in_use: self.next_step_prompt ( await self.browser_context_helper.format_next_step_prompt() ) result await super().think() # 执行后恢复默认Prompt self.next_step_prompt original_prompt return result六、完整 Prompt 组装时序案例以Manus Agent 执行「搜索 Python 最新版本」任务为例完整还原两轮推理的 Prompt 组装、消息入库、API 拼接全流程。初始状态Memory.messages []Step 1第一轮推理1、think() 注入下一步引导 Promptmemory 新增伪用户消息Memory.messages [ Message(roleuser, contentBased on user needs, proactively select...) ]2、ask_tool 完成最终消息拼接系统消息前置# 前置系统消息 Message(rolesystem, contentYou are OpenManus, an all-capable AI assistant...) # 后续对话历史 Message(roleuser, contentBased on user needs..) # 附带全局工具列表 tools: [{name:python_execute,...}, {name:browser_use,...}, ...]3、LLM 返回工具调用结果memory 存入助手消息Message(roleassistant, content我来搜索一下, tool_calls[{name:web_search, args:{query:Python latest version}}])4、act() 执行工具存入工具返回结果消息第一轮结束Memory.messages [ Message(roleuser, contentBased on user needs...), Message(roleassistant, content我来搜索一下, tool_calls[...]), Message(roletool, contentObserved output of cmd web_search..., tool_call_idcall_1) ]Step 2第二轮推理1、再次执行 think()注入新的下一步 PromptMemory.messages [ # 上一轮历史消息 Message(roleuser, contentBased on user needs...), Message(roleassistant, content我来搜索一下, tool_calls[...]), Message(roletool, contentObserved output...), # 本轮新增引导消息 Message(roleuser, contentBased on user needs...) ]2、最终 API 消息结构系统消息永久前置完整拼接历史对话七、全链路数据流总图为方便整体理解梳理从模板定义到 API 调用的全链路闭环流程①模板定义app/prompt/ 下定义静态 SYSTEM、NEXT_STEP 模板预留动态占位符②Agent 初始化实例化 Agent填充固定占位符如 workspace 目录绑定 Prompt 模板③每轮 think() 执行动态替换场景占位符、注入下一步引导 Prompt、追加截图多模态消息④LLM 格式化组装系统消息前置、历史消息标准化、图片格式转换、Token 校验、挂载工具列表⑤API 调用组装完成的标准消息体、工具参数传入 OpenAI 接口获取推理结果八、核心设计决策与底层原理这套 Prompt 架构的所有设计均为解决 Agent 推理稳定性、场景适配性、可扩展性问题核心设计决策汇总设计点具体实现方式核心设计原因System Prompt 不入库 Memory单独传递 system_msgs调用时前置拼接不受 max_messages 截断影响永久保留 Agent 身份定位Next Step Prompt 逐轮入库每轮以伪 user 消息追加至对话历史贴合 LLM 对话交互逻辑精准引导迭代思考原生 str.format() 占位符自定义 {key} 占位符代码动态填充无需引入 Jinja2 等模板引擎轻量化、低依赖、可读性强截图独立多模态传递base64 字段单独存储格式化时转为标准图片格式不污染文本对话历史最大化利用多模态模型能力工具列表动态生成每次 think() 调用 to_params() 重新生成工具参数适配 MCPAgent 动态增减工具的场景保证工具列表实时准确无复杂模板语法纯字符串 format 替换实现所有动态能力降低项目复杂度便于 Prompt 调试、修改、维护九、Memory 最终消息形态实战落地一次完整的 Manus 任务执行后Memory 中真实存储的对话序列无 System 消息仅存交互历史索引角色内容说明消息来源0user帮我搜索 Python 最新版本用户原始输入1userBased on user needs, proactively...第一轮 Next Step 注入2assistant我来搜索 Python 最新版本 工具调用第一轮 LLM 推理返回3tool网页搜索结果数据第一轮工具执行返回4userBased on user needs, proactively...第二轮 Next Step 注入5assistant输出结果 terminate 结束工具第二轮 LLM 推理返回6tool任务结束提示第二轮工具执行返回十、总结这套三层 Prompt 组装架构是 AI Agent 实现智能化、动态化、场景化推理的核心基石1、分层解耦静态模板、动态注入、API 格式化三层分离各司其职2、设计精巧系统提示永久常驻、迭代提示逐轮更新兼顾稳定性与灵活性3、场景适配支持动态占位符、多模态图文、场景自适应 Prompt 切换4、轻量化可维护无冗余模板依赖逻辑清晰便于迭代优化。理解这套机制就能彻底掌握 AI Agent 「如何思考、如何调用工具、如何迭代任务」的底层核心逻辑。