版本对比与选型建议
新版智能体为大多数应用场景提供了更优的性能和开发体验，在没有旧版本依赖需求时，推荐使用新版。
| 对比维度 | 旧版本（Agent 1.0） | 新版本（Agent 2.0） |
|---|
| 规划与调度 | 智能体在检索知识库后，再决策是否调用 MCP 等其他工具。 | 将知识库、MCP 统一为工具，由智能体自主规划在何时、以何种顺序进行调用。 |
| 过程透明度 | 只展示最终结果，无法完整回溯中间决策。 | 能完整展示每一轮的"规划-执行-反思"链路的全过程。 |
| 适用场景 | 适用于意图单一、流程固定的简单任务。 | 能够完成从简单问答到复杂规划的各类任务。 |
Agent 2.0 应用也可通过阿里云百炼 CLI 调用：bl app call --app-id <APP_ID> --prompt "你的问题"。详见使用 CLI。 快速开始：创建一个基础智能体
- 访问阿里云百炼控制台应用管理，单击创建应用，选择智能体应用 > Agent 2.0。
- 填写应用名称，单击立即创建。创建完毕后自动跳转至应用配置界面。
- 在模型选择器的下拉菜单中选择模型，例如
千问-Plus-Latest。
- 在右侧对话框中输入问题：
你是谁？。
能力配置
模型选择
在模型选择器的下拉菜单中，可以选择两类选项：
- 智能模式：由平台自动取得成本与效果的平衡，无需手动挑选模型。
- 指定模型：直接选择某个具体模型。为确保多步规划效果，推荐选用具备强工具调用能力的模型，如
千问-Max 系列模型；单击更多模型可选择其他模型。
其中，智能模式包含 AUTO、性能、均衡、经济四个档位，均由你手动选定。AUTO 与其他三档的区别在于：选中 AUTO 后，由平台自动判断任务复杂度并动态路由到合适的档位；选中其余三档则固定使用该档位。
| 模式 | 定位 | 特点 |
|---|
| AUTO | 自动路由、多模型、上下文自适应 | 智能匹配最适合的思考深度与模型 |
| 性能 | 高质量模型，速度质量兼顾 | 快速响应、1M 上下文、工具调用 |
| 均衡 | 高级推理能力，高质量输出 | 推理增强、1M 上下文、稳定输出 |
| 经济 | 标准推理能力，高性价比 | 标准推理、1M 上下文、高性价比 |
- 简单任务（单步明确、简短问答、闲聊等）→ 经济
- 中等任务（单文件代码、中等写作、多步推理等）→ 均衡
- 复杂任务（多文件架构、长文创作、多工具编排等）→ 性能
判断复杂度时会同时考虑用户最新消息与当前上下文长度：当上下文 Token 数超过 200K 时，将至少路由到性能档，以保证长上下文任务的处理效果。
- 最长回复长度：模型生成的长度限制，不包含提示词。
- 温度系数：控制生成随机性和多样性，数值越高随机性越强。
- enable_thinking：是否开启思考模式。开启后有助于提升智能体的反思效果；不支持思考模式的模型无法配置该参数。
提示词
系统提示词用于定义智能体角色、行为指令与能力边界，以确保其在交互中始终保持一致性、可控性和任务合规性。
-
配置系统提示词：配置系统提示词为
请你模仿《百年孤独》的风格来回答我的问题，以下是效果对比：
- 无系统提示词：模型以默认身份回复。
- 配置系统提示词：模型以指定风格回复。
-
在系统提示词中使用自定义变量（可选）：除了支持输入静态文本，系统提示词还允许嵌入自定义变量。
- 单击提示词右上方的自定义变量，设置自定义变量，单击确定保存。
- 输入
/，使用已配置的变量。
预解析文件
预解析文件功能用于控制上传文件的处理方式。
- 关闭预解析：关闭后，系统不会主动解析文件。文件的 URL 会作为上下文信息传递给智能体，智能体可在后续步骤中决策是否调用工具，并将该 URL 作为参数传入。
- 开启预解析：开启后，系统将使用预置解析器处理上传的文档、图像、视频、音频等文件，并返回解析后的文本内容给模型作为参考。
千问-VL 系列模型由于具备多模态能力，即使关闭预解析文件，也能够直接解析图片和视频文件。
内置工具
内置工具在隔离的沙箱环境中运行，提供代码执行和文件操作能力。全部工具默认关闭，按需开启。
| 工具 | 说明 |
|---|
bash | 执行 shell 命令，支持 bash、python3、pip 等命令行操作。 |
write | 创建或覆盖文件，自动创建父目录。 |
read | 读取文件内容，支持按行范围读取大文件。 |
edit | 在文件中做精确文本替换（find and replace）。 |
glob | 按模式搜索文件，返回匹配的文件路径列表。 |
grep | 在文件中搜索内容，支持正则表达式。 |
download_file | 将执行过程中生成的文件导出为可下载链接。 |
知识库
知识库使智能体能够查询外部信息，并将检索到的内容作为生成答案的依据。这种主动获取知识的方式，在处理私有知识或垂直领域问答时，能提升回答的准确率并有效减少内容幻觉。知识库的创建与管理，请参见知识库。
新版智能体通过关联知识检索服务使用知识库。一个知识检索服务可以包含一个或多个知识库，支持单知识库检索或多知识库联合检索；一个应用同时只关联一个知识检索服务，关联其他服务会替换已关联的服务。关联前，请确认已创建知识检索服务，为服务添加所需知识库，并完成发布，参见知识检索。
在回复设置中开启展示回答来源可以展示知识来源和源文件地址。
关联知识检索服务
-
进入 Agent 2.0 应用的配置页面，在知识库下找到检索策略区域。首次配置时，页面提示尚未配置知识检索服务，点击立即配置，打开服务选择面板；也可以点击该区域右上角的配置进入。
-
在配置检索服务面板中找到目标服务。可使用搜索框查找已发布的检索服务，并根据服务名称、版本、包含的知识库及知识库数量确认关联对象。
-
点击目标服务右侧的关联，将该知识检索服务关联到当前应用。
关联完成后，检索策略区域显示服务名称、调用设置，以及该服务包含的知识库和权重。
调整调用设置
在服务卡片中可调整调用方式和多轮改写，控制应用如何使用检索服务：
| 配置项 | 选项 | 说明 |
|---|
| 调用方式 | 智能调用 | 模型根据问题和对话上下文，自主判断是否需要调用知识检索服务 |
| 调用方式 | 必定调用 | 每次请求中，在模型首次推理前先执行一次知识检索 |
| 多轮改写 | 开 | 模型自主调用知识检索时，结合当前问题和对话上下文生成检索问题 |
| 多轮改写 | 关 | 使用当前输入的原文检索，不采用模型生成的改写问题 |
管理已关联的服务
服务卡片右上角提供以下操作：
- 设置：点击齿轮图标，跳转至对应的知识检索服务页面，修改服务包含的知识库及检索策略。
- 删除：点击删除图标，解除当前应用与该知识检索服务的关联。此处删除的是应用中的关联，不是知识检索服务或知识库本身。
修改检索服务配置并发布
点击服务卡片上的设置后，进入对应知识检索服务的服务配置页面。
- 添加知识库：点击知识库区域右上角的添加，为该服务添加新的知识库。
- 调整检索策略：按需调整知识库权重、知识库路由、混排模型等配置。具体可配置项以服务页面为准。
- 发布修改：配置完成后，点击页面右上角的发布，发布本次知识检索服务配置。修改配置后请务必完成此操作。
- 返回应用确认：返回 Agent 2.0 应用页面，点击检索策略区域右上角的刷新图标，确认服务包含的知识库及相关展示信息已更新。
旧版知识库以 MCP 工具形式接入，在新版百炼页面位于工具 → MCP 服务下。如需添加旧版知识库，请前往旧版百炼页面操作。 MCP
在新版智能体中，外部工具均以 MCP 协议接入智能体，并纳入调度体系，包括来自 MCP 广场 的官方 MCP 和自定义 MCP 服务。智能体能够在多步推理中，对 MCP 进行动态的、非固定顺序的调用，以解决更复杂的任务。此外，插件也支持一键转换为 MCP 服务。
数据连接器
数据连接器是阿里云百炼平台上智能体、工作流、知识库等访问外部数据的桥梁。通过配置数据连接器，智能体可以直接查询和操作外部数据源中的数据。
应用组件
将已创建的智能体或工作流作为工具接入。需要先将智能体或工作流应用发布为组件。
技能（Skill）是可添加到智能体的能力包，用于让智能体在对话中自动处理特定类型的任务。添加技能后，智能体可在对话中自动识别匹配的任务并调用对应技能进行处理，无需额外编写代码。
- 短期记忆：新版智能体支持短期记忆功能，即在多轮会话中为智能体提供上下文信息。可以设置 0 到 30 轮的上下文（0 代表不传递多轮对话记录）；轮数越多，对话相关性越强，但输入长度也会相应增加。
- 长期记忆：该功能计划在未来的迭代中支持。
环境用于配置技能调用所需的鉴权密钥和环境变量。配置后，智能体在调用技能时会自动注入对应的凭证和参数，无需在技能代码中硬编码敏感信息。
回复支持展示回答来源。开启后，将以角标形式展示知识来源和源文件/源网页地址。该功能推荐与知识库和联网搜索 MCP 组合使用。
运行与结果分析
完成应用配置后，可在页面右侧的对话窗口中运行智能体。对于需要多步规划的复杂请求，新版智能体会以卡片流的形式，展示其决策过程和运行轨迹，该过程主要包含以下两种步骤：
- 思考 (Thinking)：此步骤展示模型的推理逻辑，便于分析其决策路径并定位非预期行为的根源**（仅当选用支持思考模式的模型时出现）**。
- 工具调用：此步骤记录了模型执行的具体工具调用入参及其返回的结果。
ReAct 最大轮次（取值范围 1-50）用于限制智能体在单次会话中可以调用工具的最大次数。当超出此限制后，智能体将自动退出工具调用链路并生成最终回复。
应用发布与集成
应用发布是后续所有智能体应用调用、集成的前提条件。
应用发布
在应用配置页面的右上角，单击发布按钮，在弹出窗口中会展示自上次发布以来的配置变更差异。确认发布信息无误后，单击确认发布，即可完成应用发布。
通过 API 调用
您可以在智能体应用发布渠道页签，单击 API 调用右侧的查看 API，查看通过 API 调用新版智能体应用的方法。
应用管理
版本管理
通过版本管理功能，可以编辑历史版本描述信息，或回滚发布过的历史版本。
- 在应用配置页，单击顶部导航栏右侧的版本管理。
- 选中需要回滚的历史版本，将鼠标悬浮至卡片上，单击右上角编辑图标，在编辑版本信息对话框中按需完成修改后，单击确定，即可修改历史版本描述信息。单击覆盖当前草稿，即可回滚至该版本。
计费说明
智能体功能计费主要体现在以下几个方面：
- 模型调用
- 智能体会产生模型调用费用，具体费用取决于模型类型、输入和输出 Token 数量。
- 具体的模型类型和对应的计费规则请参见模型列表。选用智能模式时的各档位刊例价见下方明细。
- 知识库
- 知识库按量付费。
- 从知识库召回的文本切片会增加模型输入 Token 数量，可能导致模型推理（调用）费用的增加。
- MCP
- 部分官方 MCP 按模型调用计费，如文生图、文生视频、语音合成等 MCP。
- 部分 MCP 服务涉及第三方 API 调用，使用后可能会产生费用。这部分费用由第三方收取，阿里云百炼不收取费用。
智能模式计费明细
价格单位为元 / 百万 Token。其中 AUTO 按统一价计费，与实际路由到的模型无关；直接选择性能 / 均衡 / 经济档时，按所选档位计费。价格明细如下：
| 模式 | 输入 | 输出 |
|---|
| AUTO | ¥3 | ¥12 |
| 性能 | ¥6.4 | ¥22.4 |
| 均衡 | ¥1.6 | ¥6.4 |
| 经济 | ¥0.5 | ¥2 |
| 模式 | 隐式缓存命中 | 显式缓存创建 | 显式缓存命中 |
|---|
| AUTO | ¥0.75 | — | — |
| 性能 | ¥1.6 | — | — |
| 均衡 | ¥0.32 | ¥2.5 | ¥0.2 |
| 经济 | ¥0.12 | ¥0.75 | ¥0.06 |
常见问题
支持将旧版智能体升级到新版本吗？
不支持。旧版智能体和新版智能体基于不同的技术架构，彼此不兼容，无法进行直接的版本切换、升级或降级。
如果您当前在使用旧版智能体，并希望体验新版智能体的功能，请您前往控制台重新创建一个新版智能体应用。
为什么智能体未按预期调用已配置的工具？
可从以下四个层面进行排查：
- 技能配置与挂载：请核实该技能是否已成功创建并正确挂载到当前智能体应用中。
- 系统提示词的引导性：请检查系统提示词是否清晰地描述了该技能的功能、参数以及适用的场景。模型依赖这些描述信息来决策何时调用技能。
- 意图与技能的相关性：请评估问题的表述是否清晰，其意图是否能明确指向特定技能。如果意图模糊或与技能功能不相关，模型可能选择不调用。
- 执行轮次限制：请检查是否达到了 ReAct 轮次上限。智能体可能已规划调用该技能，但在执行到该步骤前因轮次耗尽而被强制终止。
智能体应用是否支持上下文缓存？
支持隐式缓存，暂不支持在应用中配置显式缓存。
- 隐式缓存：智能体在调用支持隐式缓存的模型时会自动生效，无需任何配置、也无法关闭。系统会自动识别并缓存请求的公共前缀（如相同的系统提示词、多轮对话历史、知识库召回内容等），命中缓存的输入 Token 按标准输入单价的 20% 计费，可相应降低模型调用成本。
- 显式缓存：需要在模型调用请求中主动为指定内容创建缓存标记。智能体应用由平台统一构造模型请求，暂不支持配置显式缓存。
