27 KiB
阿里云百炼 — 智能体应用指南
来源：百炼控制台文档 采集日期：2026-02-28
目录
一、新版智能体应用（Agent 2.0）
新版智能体应用（Agent 2.0）将知识库、MCP 等多种能力统一为工具，并通过自主思考和规划来调用，以解决复杂任务。
1.1 版本对比与选型建议
新版智能体为大多数应用场景提供了更优的性能和开发体验，在没有旧版本依赖需求时，推荐使用新版。
| 对比维度 | 旧版本（Agent 1.0） | 新版本（Agent 2.0） |
|---|---|---|
| 规划与调度 | 智能体在检索知识库后，再决策是否调用 MCP 等其他工具。 | 将知识库、MCP 统一为工具，由智能体自主规划在何时、以何种顺序进行调用。 |
| 过程透明度 | 只展示最终结果，无法完整回溯中间决策。 | 能完整展示每一轮的"规划-执行-反思"链路的全过程。 |
| 适用场景 | 适用于意图单一、流程固定的简单任务。 | 能够完成从简单问答到复杂规划的各类任务。 |
示例对比
| 旧版 | 新版 |
|---|---|
| 知识库检索先行，再决策是否调用后续工具 | 知识库与 MCP 统一作为工具，由智能体自主规划调用 |
| 缺乏任务规划，无法完成复杂研究任务 | 自主规划并拆解复杂任务，生成完整回复 |
1.2 快速开始：创建一个基础智能体
- 访问阿里云百炼控制台 应用管理，单击创建应用，选择 智能体应用 > Agent 2.0。
- 填写应用名称，单击立即创建。创建完毕后自动跳转至应用配置界面。
- 在模型选择器的下拉菜单中选择模型，例如
千问-Plus-Latest。 - 在右侧对话框中输入问题：
你是谁？。
1.3 能力配置
模型选择
为确保多步规划效果，推荐选用具备强工具调用能力的模型，如 千问-Max 系列模型。
- 在模型选择器的下拉菜单中选择模型。单击更多模型可以选择其他模型。
- 单击模型选择器右侧的参数配置器，支持修改的参数如下：
- 最长回复长度：模型生成的长度限制，不包含提示词。
- temperature：控制生成随机性和多样性，数值越高随机性越强。
- enable_thinking：是否开启思考模式。开启思考模式有助于提升智能体的反思效果。不支持思考模式的模型无法配置此参数。
系统提示词
系统提示词用于定义智能体角色、行为指令与能力边界，以确保其在交互中始终保持一致性、可控性和任务合规性。
- 配置系统提示词：例如配置为
请你模仿《百年孤独》的风格来回答我的问题，可改变智能体的回复风格。 - 在系统提示词中使用自定义变量（可选）：
- 除了支持输入静态文本，系统提示词还允许嵌入自定义变量。
- 单击系统提示词右上方的新建变量，设置自定义变量，单击确定保存。
- 输入
/，使用已配置的变量。
预解析文件
预解析文件功能用于控制上传文件的处理方式。
- 关闭预解析：系统不会主动解析文件。文件的 URL 会作为上下文信息传递给智能体，智能体可在后续步骤中决策是否调用工具，并将该 URL 作为参数传入。
- 开启预解析：系统将使用预置解析器处理上传的文档、图像、视频、音频等文件，并返回解析后的文本内容给模型作为参考。
千问-VL 系列模型由于具备多模态能力，即使关闭预解析文件，也能够直接解析图片和视频文件。
在其他所有情况下（例如，使用不具备多模态能力的文本模型，或使用千问-VL 系列模型处理非图像/视频文件时），智能体的文件处理能力则严格遵循上述"开启"或"关闭"的逻辑。
知识库
知识库使智能体能够查询外部信息，并将检索到的内容作为生成答案的依据。在新版智能体中，知识库作为智能体的一项技能，作为工具由智能体自主规划调用。这种主动获取知识的方式，在处理私有知识或垂直领域问答时，能提升回答的准确率并有效减少内容幻觉。详情请参考 知识库。
在"回复"中开启展示回答来源可以展示知识来源和源文件地址。
新版智能体支持通过标签来限定知识库的查询范围。通过为知识库文件设置标签，并在系统提示词（Prompt）中定义使用规则，可以引导智能体根据用户意图，在更小的、更精准的文件范围内进行检索，从而显著提升回答的准确性和相关性。详情请参考 新版智能体知识库标签过滤。
MCP
在新版智能体中，外部工具均以 MCP 协议接入智能体，并纳入调度体系，包括来自 MCP 广场 的官方 MCP 和自定义 MCP 服务。智能体能够在多步推理中，对 MCP 进行动态的、非固定顺序的调用，以解决更复杂的任务。此外，插件也支持一键转换为 MCP 服务。
应用组件
将已创建的智能体或工作流作为工具接入。需要先将智能体或工作流应用 发布为组件。
记忆
- 短期记忆：新版智能体支持短期记忆功能，即在多轮会话中为智能体提供上下文信息。可以设置 0 到 30 轮的上下文（0 代表不传递多轮对话记录）；轮数越多，对话相关性越强，但输入长度也会相应增加。
- 长期记忆：该功能计划在未来的迭代中支持。
回复
回复支持展示回答来源。开启后，将以角标形式展示知识来源和源文件/源网页地址。该功能推荐与知识库和联网搜索 MCP 组合使用。
1.4 运行与结果分析
完成应用配置后，可在页面右侧的对话窗口中运行智能体。对于需要多步规划的复杂请求，新版智能体会以卡片流的形式，展示其决策过程和运行轨迹，该过程主要包含以下两种步骤：
- 思考 (Thinking)：此步骤展示模型的推理逻辑，便于分析其决策路径并定位非预期行为的根源（仅当选用支持思考模式的模型时出现）。
- 工具调用：此步骤记录了模型执行的具体工具调用入参及其返回的结果。
通过配置 ReAct 最大轮次（取值范围 1-50），用于限制智能体在单次会话中可以调用工具的最大次数，当超出此限制后将会自动退出工具调用链路，并由智能体生成最终回复。
1.5 应用发布与集成
重要：应用发布是后续所有智能体应用调用、集成的前提条件。
应用发布
在应用配置页面的右上角，单击发布按钮，在弹出窗口中会展示自上次发布以来的配置变更差异。确认发布信息无误后，单击确认发布，即可完成应用发布。
通过 API 调用
您可以在智能体应用发布渠道页签，单击 API 调用 右侧的 查看 API，查看通过 API 调用新版智能体应用的方法。详情参考 新版智能体应用 API 参考。
1.6 应用管理
版本管理
通过版本管理功能，可以编辑历史版本描述信息，或回滚发布过的历史版本。
- 在应用配置页，单击顶部导航栏右侧的版本管理。
- 选中需要回滚的历史版本，将鼠标悬浮至卡片上，单击右上角编辑图标，在编辑版本描述对话框中按需完成修改后，单击确定，即可修改历史版本描述信息。单击覆盖当前草稿，即可回滚至该版本。
1.7 安全与合规
若应用对外提供服务，必须遵守国家网信办《生成式人工智能服务管理暂行办法》等法规，完成必要的 应用合规备案。
1.8 计费说明
- 模型调用：智能体会产生模型调用费用，具体费用取决于模型类型、输入和输出 Token 数量。具体的模型类型和对应的计费规则请参考 模型列表。
- 知识库：知识库按量付费，详情请参见 知识库计费说明。从知识库召回的文本切片会增加模型输入 Token 数量，可能导致模型推理（调用）费用的增加。
- MCP：部分官方 MCP 按模型调用计费，如文生图、文生视频、语音合成等 MCP。部分 MCP 服务涉及第三方 API 调用，使用后可能会产生费用。这部分费用由第三方收取，阿里云百炼不收取费用。
1.9 常见问题
Q: 支持将旧版智能体升级到新版本吗？
不支持。旧版智能体和新版智能体基于不同的技术架构，彼此不兼容，无法进行直接的版本切换、升级或降级。如果您当前在使用旧版智能体，并希望体验新版智能体的功能，请您前往控制台重新创建一个新版智能体应用。
Q: 为什么智能体未按预期调用已配置的工具？
可从以下四个层面进行排查：
- 技能配置与挂载：请核实该技能是否已成功创建并正确挂载到当前智能体应用中。
- 系统提示词的引导性：请检查系统提示词是否清晰地描述了该技能的功能、参数以及适用的场景。模型依赖这些描述信息来决策何时调用技能。
- 意图与技能的相关性：请评估问题的表述是否清晰，其意图是否能明确指向特定技能。如果意图模糊或与技能功能不相关，模型可能选择不调用。
- 执行轮次限制：请检查是否达到了 ReAct 轮次上限。智能体可能已规划调用该技能，但在执行到该步骤前因轮次耗尽而被强制终止。
二、智能体应用（Agent 1.0）
大语言模型（LLM）无法直接访问专有知识库或获取实时动态信息。针对这一瓶颈，阿里云百炼提供了智能体（Agent）应用。智能体支持以零代码方式，将大模型与外部工具进行集成，从而扩展模型的能力边界。
2.1 基本原理
智能体（Agent）由提示词（Prompt）驱动，通过协同多种外部能力来完成复杂任务。在接收请求后，大模型进行意图理解和任务规划，自主决策并调用一个或多个外部能力来执行任务，最终整合信息生成响应。
百炼智能体支持核心能力包括：
- 知识库（RAG）：通过连接外部知识库，使应用能基于私有数据回答问题，解决大模型无法访问特定信息的问题。
- 插件：能调用平台预置的效率工具（如代码执行、图像生成、天气查询等）。
- MCP：允许将第三方服务封装并接入智能体，智能体可调用这些外部服务来完成特定工作。
- 复用智能体与工作流：允许将其他智能体或工作流应用封装为模块化组件，实现复杂功能的复用。
- 记忆：使应用能够跨会话存储和回忆关键信息，实现个性化、连贯的对话体验。
2.2 快速开始
创建一个基础智能体
- 访问阿里云百炼控制台 应用管理，单击创建应用，选择智能体应用。
- 配置应用名称、描述信息、应用头像，点击立即创建。
- 在应用管理界面，在模型选择器的下拉菜单中选择模型，例如
千问-Plus-Latest。 - 创建完成后，在右侧对话框中输入问题进行测试。
通过官方模板创建应用
访问阿里云百炼控制台 应用管理，选择智能体应用。选择一个官方模板，例如知识问答，单击立即创建。
2.3 智能体能力
模型
模型是驱动智能体进行思考、推理和决策的核心。百炼智能体支持选择千问系列、Deepseek 等官方模型，也支持选择自定义部署的模型。
- 模型选择：在应用配置界面，在右侧下拉菜单中选择一个模型，例如
千问-Plus-Latest。单击更多模型可以选择其他模型。 - 参数配置：
- 最长回复长度：模型生成的长度限制，不包含提示词。允许的最大长度因模型不同有所改变。
- temperature：控制生成随机性和多样性，数值越高多样性越强，数值越低一致性越强，取值范围为 [0, 2)。
- enable_thinking：是否开启推理模式。部分不支持推理模式的模型无法配置此参数。
开启推理模式后，模型在生成回复时进行更多的内部推理和上下文处理，Token 消耗会增加。
系统提示词（System Prompt）
系统提示词是为智能体预设的元指令，用于定义其角色、行为准则与能力边界，以确保其在交互中始终保持一致性、可控性和任务合规性。
DeepSeek R1 系列模型不建议设置系统提示词。
- 配置提示词：例如配置为
请你模仿《百年孤独》的风格来回答我的问题。 - 在系统提示词中使用自定义变量（可选）：
- 输入
/，单击新增变量，配置自定义变量。 - 再次输入
/，使用已配置的变量。
- 输入
知识库（RAG）
知识检索增强（Retrieval-Augmented Generation, RAG）能够使智能体查询外部知识库，并将检索到的最相关的信息作为生成答案的直接依据。在处理私有知识或垂直领域问答时，RAG 能显著提升智能体的回答准确率，减少幻觉问题。详情请参考 知识库。
RAG 检索到的文本也会占用大模型的上下文窗口长度（Context Window），因此需要根据实际情况调整检索策略和文本长度，以充分利用上下文窗口并避免超出限制。
MCP
模型上下文协议（Model Context Protocol, MCP）是连接智能体与外部世界能力的关键桥梁，允许智能体调用外部工具。当智能体接收到无法仅凭自身知识完成的任务时（例如查询实时天气），它会调用 MCP 来执行这些任务。
阿里云百炼提供了多种 官方 MCP 服务，同时也支持创建 自定义 MCP 服务。
插件
智能体应用通过调用插件，可完成代码执行、网络搜索、基于文本生成图片等具体任务。阿里云百炼提供了多种官方插件，同时也支持添加自定义插件，详情参见 插件概述。
复用智能体与工作流
百炼智能体应用支持接入模块化的智能体或工作流组件，实现功能复用。
接入前需要将智能体和工作流应用 发布为组件。
记忆
智能体应用的记忆功能分为短期记忆和长期记忆。
- 短期记忆：会话中提供给智能体的上下文信息。轮数越多，对话相关性越强，输入长度也会增加。支持记忆的上下文轮数为 0 到 30（0 代表不传递多轮对话记录）。
- 长期记忆：可以提取对话的关键信息并保存至对应的记忆体（Memory ID）中，详细的功能介绍请参考 长期记忆。
2.4 智能体交互
智能体应用支持多种交互方式，包括文本对话、文本生成、语音和视频互动。
视频互动仅限千问 VL 系列模型。
文本对话
文本对话是智能体应用的核心交互方式，能够提供智能和个性化的多轮对话体验。
文本对话支持两种主要输入方式：
- 文本输入：输入文字与智能体进行对话。
- 文件上传：上传文件作为附件给到智能体，支持文档、图片、视频、音频等多种格式。详情请参考 文件问答。
文本生成
文本生成是面向单轮任务的生成式交互，适合对文章进行信息抽取与文本创作。
文本生成支持配置两种内置变量：
- Prompt：用户指令，用来指导应用生成回复。
- Files & Images：支持上传文档、图片、视频、音频等多种格式，自动识别类型并分类处理。
- 自定义变量：传入变量值将替换提示词中对应的变量位置。
语音和视频互动
重要 - 计费模式：阿里云百炼与视频云分别产生应用调用的账单。
- 阿里云百炼按照应用 API 调用计费（如果 TTS 选择阿里云百炼 CosyVoice，则模型调用也会计费），详情请参见 大模型产品计费说明。
- 视频云按照 AI 实时互动计费模式计费，AI 实时互动每日为未订阅套餐包的用户赠送 20 通免费电话额度用于产品体验。详情请参见 AI 实时互动计费说明。
说明：
- 不推荐使用深度思考模式的模型进行实时音视频对话，会影响对话体验，如 DeepSeek-R1、QwQ 系列模型。
- DeepSeek V3 模型不支持视频对话功能。
智能体应用支持语音和视频互动，可以与智能体进行实时语音和视频通话。
- 语音互动：智能体能依托 语音合成-CosyVoice 模型将文本回复转换为自然语音输出，从而进行实时的语音通话。
- 视频互动：智能体能依托 图像与视频理解 模型识别画面中的物体、场景、人物动作等，从而进行实时的视频通话。
个性化交互体验
通过设置欢迎语、添加预设问题，进一步完善智能体应用体验。
- 欢迎语：智能体的开场白，帮助营造友好积极的对话氛围。仅文本对话模式支持。
- 预设问题：预设一系列启发性的问题，帮助快速了解智能体的核心能力。仅文本对话模式支持。
- 测试样例：预置一组输入数据，配置完成后可快速发起测试。仅文本对话、文本生成模式支持。
2.5 智能体发布与调用
百炼智能体支持通过 API 外部调用，同时支持一键发布到三方平台，并通过组件或魔笔分享渠道集成到其他业务流程中。
重要：应用发布是后续所有智能体应用调用、集成的前提条件。
应用发布
单击智能体应用管理界面右上角的发布按钮，单击确认发布，即可完成应用发布。
若应用非首次发布，弹窗会展示自上次发布以来的变更详情。
说明：如果应用为 RAM 账号所创建，发布应用前请确认已拥有服务关联角色权限
ram:CreateServiceLinkedRole，详情请参考 服务关联角色。
通过 API 调用
您可以在智能体应用发布渠道页签，单击 API 调用 右侧的 查看 API，查看通过 API 调用智能体应用的方法。
将
DASHSCOPE_API_KEY替换为实际的百炼 API Key 才可发起调用。
发布为官方网页版
单击官方渠道右侧的生成分享链接，可以分享给任意阿里云账号进行登录体验。
发布为钉钉机器人
集成智能体应用与钉钉机器人后，可在钉钉内访问和使用该应用。此集成需要在钉钉平台创建机器人，并将其与阿里云百炼应用关联。详细步骤，请参阅 通过钉钉发布应用。
发布为微信公众号
集成智能体应用与微信公众号后，可通过微信公众号访问和使用智能体应用。此集成需要创建微信公众号，并将其与阿里云百炼应用相关联。详细步骤，请参阅 通过微信发布应用。
在应用的发布渠道页签下，将鼠标悬停在微信公众号右侧的二维码图标上，即可显示公众号的二维码。用户可以通过微信扫一扫功能，扫描此二维码来关注您的公众号，进而访问已集成的阿里云百炼应用。
发布为组件
将智能体应用发布为组件，以便于在其他智能体或工作流应用调用。详细的组件配置方法请参考 发布为组件。
通过魔笔渠道分享应用
将百炼智能体发布为生产级 Web/H5 应用，或嵌入已有的 Web/H5/App/小程序中。魔笔分享渠道功能现已迁移至 UI 设计。
发布为百炼应用模板
如有需要，您可以将您的应用上架为官网模板。请填写 阿里云百炼应用模板上架申请，团队将与您取得联系。应用审核通过后，应用将会被上架至 应用广场。
2.6 智能体管理
删除与复制
可以在应用管理找到已发布的应用卡片，在 更多 > 复制应用/删除应用 进行删除与复制智能体、修改应用名操作。
版本管理
通过版本管理功能，可以编辑历史版本描述信息，或选择和使用发布过的历史版本。
- 在智能体应用的配置页签，单击顶部导航栏右侧的版本管理。
- 在历史版本列表中，选中目标版本后：
- 如果需要修改版本信息，请将鼠标悬浮至编辑图标位置单击，在编辑版本描述对话框中按需完成修改后，单击确定。
- 如果需要使用该历史版本，请单击覆盖当前草稿，在二次确认对话框中单击确认。
该历史版本内容将覆盖当前版本草稿内容。
2.7 应用于生产环境
启动和备份多轮对话
百炼智能体应用默认开启多轮对话功能，通过内置缓存保存对话记录，有效期为 1 小时。对话记录也支持备份至 ADB-PG。在应用管理找到已发布的应用卡片，单击设置图标，单击高级配置，选择多轮对话。
ADB-PG 的更多功能与计费信息，请参阅 云原生数据仓库 AnalyticDB PostgreSQL 版 帮助文档。
内容安全与风控
发布应用后，可以在内置的安全规则基础上，自定义内容干预规则，确保大模型生成的内容安全可控。
- 使用快速干预工具：可以及时拦截和处理对话中存在潜在的违规、敏感或不当内容。该工具基于自定义的规则，检测用户输入或模型生成的文本，一旦触发条件就会执行预先设置的干预操作。
- 创建输入话术规则
- 创建生成结果规则
快速干预工具仅通过规则方式快速处理用户输入的违规话术或者大模型生成的风险内容，该工具无法替代内容安全检测类的专业产品。
- 配置内容安全策略：智能体应用内置了一套内容安全策略，当大模型生成的内容触发此策略时，智能体应用将拦截全部生成内容，并提示内容存在安全问题。目前，阿里云百炼仅提供"全部拦截"的风险内容拦截方式，您无需手动配置此项。
应用合规备案
若应用对外提供服务，必须遵守国家网信办《生成式人工智能服务管理暂行办法》等法规，完成必要的 应用合规备案。
2.8 计费说明
- 模型调用：智能体会产生模型调用费用，具体费用取决于模型类型、输入和输出 Token 数量。具体的模型类型和对应的计费规则请参考 模型列表。
- 知识库：知识库采取按量付费，详情请参见 知识库计费说明。从知识库召回的文本切片会增加模型输入 Token 数量，可能导致模型推理（调用）费用的增加。
- MCP：部分官方 MCP 按模型调用计费，如文生图、文生视频、语音合成等 MCP。部分 MCP 服务涉及第三方 API 调用，使用后可能会产生费用。这部分费用由第三方收取，阿里云百炼不收取费用。
- 长期记忆：长期记忆的数据存储不收费。在调用应用进行问答时，记忆体内容会合并到 Prompt 传递给大模型，从而增加 Token 消耗。被记忆体内容占用的 Token 暂不计费。
2.9 支持的模型
数据更新可能存在延迟，模型的支持情况以智能体应用内显示为准。
- 千问-Plus
- 千问-Max
- 千问 3-Coder-Plus
- 千问 3 开源模型
- 千问 VL-Max
- 千问 VL-Plus
- 千问-QwQ-Plus
- DeepSeek
- 千问 2.5 开源模型
- 千问-Turbo
- 千问-QwQ
- 千问 2 开源模型
- Qwen-Long
2.10 常见问题
- 百炼应用如何计费？ — 参见上方计费说明章节。
- 配置了知识库，但智能体的回答和知识库内容不相关，该如何解决？ — 检查知识库配置、检索策略和系统提示词引导。
- 自定义插件是否有超时限制？ — 有，具体限制请参考官方文档。
- 是否支持通过 API 创建智能体应用？ — 请参考百炼 API 文档。