腾讯云智能体开发平台完整教程：安装部署、环境配置、使用技巧、订阅与充值

从零完成腾讯云 ADP 开通、智能体配置、知识库与工具接入、应用发布和 Docker 对话端部署，并掌握套餐订阅、PU 资源、账户充值及生产治理。

摘要： 腾讯云智能体开发平台（Tencent Cloud ADP）是一套面向企业的 AI 应用开发、发布与运营平台，支持标准智能体、单工作流、Multi-Agent 与 Claw 等模式，并可连接知识库、MCP、企业系统和多种发布渠道。本文完整讲解实名认证与开通、工作空间规划、应用创建、知识库与工具配置、API/SDK 接入、ADP-Chat-Client Docker 部署、公有云与云部署选择、套餐订阅、PU 资源包、腾讯云账户充值、费用监控、安全治理和常见报错。建议个人或小团队先用免费版验证场景，企业按实际并发、知识量和治理要求选择专业版、企业版或云部署方案。

核心结论

使用腾讯云智能体开发平台的正确路径是：先在公有云完成最小智能体和效果验证，再决定是否订阅付费套餐、部署独立对话端，或购买 License 在自有腾讯云环境部署。不要把“腾讯云账户充值”“ADP 套餐订阅”和“PU 资源包充值”当成同一个操作。

普通用户无需安装平台本体。 公有云 ADP 是 SaaS；本地或服务器侧通常只需部署自己的业务后端，或使用官方开源 ADP-Chat-Client 构建 Web 对话端。
应用模式要按任务确定。 标准模式适合单智能体，单工作流适合固定流程，Multi-Agent 适合专家分工，Claw 适合需要独立工作空间、代码和多工具协作的复杂任务。
计费已转向订阅制。 当前公有云采用“平台按月/按年订阅 + 增购包”，套餐和资源包通过 PU 统一管理；免费版不支持 PU 充值。
云部署不等于传统离线私有化。 官方云部署方案交付 License，运行在客户自己的腾讯云 TKE、VPC 与云资源中，客户负责资源和运维，另需计算 IaaS 成本。
生产上线必须分权。 CAM 密钥、应用 AppKey、知识库、插件和工具权限应隔离；删除、付款、发消息、生产写入等动作必须增加人工审批和审计。

腾讯云智能体开发平台是什么？

Tencent Cloud ADP 的前身是腾讯云大模型知识引擎，已经升级为面向企业智能体开发与运营的平台。官方定位覆盖智能客服、知识助手、经营分析等场景，并提供模型、RAG、工作流、多智能体、工具连接、API/SDK、多渠道发布、监控和权限体系。

平台当前提供四种主要应用模式：

模式	核心特点	适合场景	主要风险
标准模式	单个智能体，按需加入知识与工具	FAQ、知识助手、简单客服	提示词过度复杂后难维护
单工作流	用节点固定步骤和条件	工单流转、审核、网页总结	流程变更需同步修改节点
Multi-Agent	主智能体调度多个专家智能体	研究、综合分析、风控与报告	调用链长、成本与调试复杂
Claw 模式	独立工作空间，可运行代码和调用 Skills/连接器/工具	数据分析、内容生产、复杂自动化	工具权限与沙箱边界更重要

另外还有面向企业员工的“智能工作台”，能连接企业知识库和工具并拆解任务。官方产品动态说明，沙箱等能力可能处于限时体验或后续调整阶段，因此上线前应核对当前计费与可用状态。

四种部署方式怎样选择？

“安装部署”在 ADP 场景下至少有四种含义。选错会导致费用、运维和数据边界完全不同。

1. 公有云 SaaS

这是最适合快速开始的方式。腾讯云负责平台运维、升级和安全，用户在浏览器中创建应用、知识库和工作流，再通过 API、SDK、企业微信、小程序或组件接入业务。费用采用套餐订阅和增购包体系。

2. 官方开源 ADP-Chat-Client

ADP-Chat-Client 是对话端解决方案，而不是把整套 ADP 平台本地化。它提供前端、后端、对话历史、语音输入、图片理解和第三方账户体系对接，可通过 Docker 部署为 Web 应用或嵌入多端。平台侧智能体仍由 ADP 提供。

3. 轻量应用服务器模板

腾讯云 Lighthouse 提供 Tencent-Cloud-ADP 应用模板，可快速创建实例并完成初始化。它适合需要独立服务入口、又不想手动配置 Docker 的用户。服务器、流量、存储和 ADP 公有云套餐可能分别产生费用。

4. 云部署 License

官方云部署方案把软件部署到客户自有腾讯云 TKE 集群、VPC 与云资源中，核心数据保留在指定云账号和私有网络。用户购买产品 License，同时承担计算、数据库、存储、网络、日志、监控和运维成本。适合有合规、内网连接和自主运维要求的企业。

Tencent Cloud ADP 以企业和工作空间为治理边界，将模型、知识库、工具与工作流组合成智能体，再发布到 API、Web、企业微信和小程序。

开通前准备：账号、实名认证与工作空间

首次使用需要腾讯云个人或企业实名认证。企业项目建议直接使用企业主体，避免后续合同、发票、权限、数据和资源迁移带来的额外工作。首次进入平台时，系统会为主账号创建一个企业和一个默认工作空间。

工作空间是团队、资源和应用的关键隔离边界。不要让所有部门共用默认空间。建议按环境或业务线建立 开发、测试、生产 空间，分别管理成员、应用、知识库和密钥。主账号只做财务、企业和最高权限操作；日常开发使用子账号并通过 CAM 或平台权限分配最小权限。

生产项目前还要确定部署形态、模型来源、数据区域、知识库容量、预期并发、发布渠道以及是否调用外部系统。若应用需要访问 CRM、ERP 或数据库，应优先考虑只读 API 和内网访问，不要让 Agent 直接持有数据库管理员凭证。

从零创建并发布第一个智能体

下面是一套可复用的十步流程，适合先在公有云验证。

完成实名认证并激活 ADP。 登录控制台进入智能体开发平台，确认当前账号主体与购买主体正确。
创建工作空间。 按项目和环境命名，例如 customer-service-dev，添加必要成员并分配角色。
创建应用。 简单问答选择标准模式；固定审批或数据处理选单工作流；复杂协作才使用 Multi-Agent 或 Claw。
选择模型。 在控制台查看当前支持模型、价格或 PU 消耗规则，不要根据旧文章写死模型名称。
编写系统提示词。 明确角色、数据范围、输出格式、拒答条件、工具规则和升级到人工的条件。
创建知识库。 上传已清洗的文档，配置切片、检索与引用，准备真实问题进行命中测试。
配置连接器和工具。 先启用只读工具；写操作增加参数校验、幂等键和人工审批。
对话调试和批量评测。 检查召回、正确性、拒答、工具选择、敏感内容与越权提示。
发布应用。 根据需求选择 API/SDK、Web、企业微信、公众号或小程序，并为正式环境生成独立 AppKey。
监控运营。 跟踪请求量、成功率、响应时间、Token/PU 消耗、失败工具调用和用户反馈，持续清洗知识库。

环境配置与 API 接入

ADP 的业务接入通常需要腾讯云身份凭证或应用侧的 AppKey。两者用途不同：SecretId/SecretKey 属于腾讯云账号 API 凭证，权限更广；AppKey 用于指定 ADP 应用的对话调用。前端浏览器和移动端都不应直接保存高权限 SecretKey。

建议在服务端使用环境变量：

export TENCENTCLOUD_SECRET_ID="YOUR_SECRET_ID"
export TENCENTCLOUD_SECRET_KEY="YOUR_SECRET_KEY"
export ADP_APP_KEY="YOUR_APP_KEY"
export ADP_APP_ID="YOUR_APP_ID"

Windows PowerShell：

$env:TENCENTCLOUD_SECRET_ID="YOUR_SECRET_ID"
$env:TENCENTCLOUD_SECRET_KEY="YOUR_SECRET_KEY"
$env:ADP_APP_KEY="YOUR_APP_KEY"
$env:ADP_APP_ID="YOUR_APP_ID"

调用协议可能包括 HTTP SSE、WebSocket、RESTful API 与官方 SDK。应从目标应用的发布或接入页面复制当前接口地址、签名要求和参数，而不是套用不明来源的 Endpoint。流式对话应处理断线、取消、超时和重复消息；业务请求使用稳定的用户标识与会话标识，避免不同用户共享记忆。

平台变量也要正确选择。官方文档区分系统变量、环境变量、API 参数、应用变量和工作流变量：环境变量通常不是用户隔离的，适合保存插件地址等共享配置；用户 ID、订单号等应通过 API 参数传入；工作流临时值使用会话隔离变量。Secret 是否可见及加密方式应以平台当前配置能力为准。

使用 Docker 部署 ADP-Chat-Client

官方文档给出的最低条件为 2 核 CPU、4 GiB 内存，支持 Linux/macOS；Windows 建议使用 WSL 或 Linux 云服务器。生产环境还应考虑数据库、磁盘、备份、HTTPS 和并发，而不能只按最低配置上线。

git clone https://github.com/TencentCloudADP/adp-chat-client.git
cd adp-chat-client

根据操作系统执行官方初始化脚本后，再运行：
cp server/.env.example deploy/default/.env

编辑 .env 时，至少需要配置腾讯云 AppID、SecretId、SecretKey、ADP 应用 AppKey、应用标识和随机 JWT 密钥。以下仅是结构示例，字段应以项目当前 .env.example 为准：

TC_SECRET_APPID=YOUR_TENCENT_APP_ID
TC_SECRET_ID=YOUR_SECRET_ID
TC_SECRET_KEY=YOUR_SECRET_KEY
SECRET_KEY=YOUR_RANDOM_JWT_SECRET

APP_CONFIGS=[{"Vendor":"Tencent","ApplicationId":"YOUR_APP_ID","Comment":"production","AppKey":"YOUR_APP_KEY","International":false}]

随后按官方项目命令构建并启动：

sudo make pack
sudo make deploy
sudo docker ps
sudo make logs

生产环境必须使用自有域名、HTTPS 和 Nginx/Caddy 反向代理。官方文档提醒，纯 HTTP 可能导致语音识别、复制等浏览器能力异常。Secret 文件不要提交 Git；容器日志要脱敏；服务器安全组只开放必要端口；数据库和备份设置访问控制。

如果使用 OAuth，对 GitHub、Microsoft Entra ID 或自建账号体系分别设置正确回调地址。简单 URL 跳转登录必须校验时间戳和 HMAC 签名、防止重放，不能只相信 URL 中传来的用户名。

知识库、工作流、MCP 与 Multi-Agent 技巧

知识库质量通常比模型大小更影响企业问答。上传前删除重复、旧版和扫描噪声，为文档增加产品、版本、部门、日期和权限元数据。评测集至少包括可回答、不可回答、权限边界、冲突文档和恶意提示五类问题。

单工作流适合确定性强的流程。把输入校验、检索、条件判断、API 调用、输出格式拆成独立节点，并为每个外部调用设置超时、错误分支和重试上限。不要让工作流失败后无限回到同一节点。

Multi-Agent 不是智能体越多越好。建议先从一个主 Agent 和两个专家 Agent 开始，为每个 Agent 定义输入、输出、工具和停止条件。共享上下文只保留必要摘要，避免多次重复传输同一知识。对风控、财务、法务等场景，最终结论必须有来源证据和人工签字。

MCP 与连接器的返回内容属于不可信输入。工具服务必须自己验证身份、参数、资源范围和速率。模型要求“忽略规则、导出全部客户数据”时，执行层必须拒绝。若需要更多实战，可参考 AI Stack Nav 的智能体开发教程与 MCP 安全内容。

先用免费版完成场景验证，再购买套餐和 PU 资源；应用发布后通过监控、评测和权限审计持续优化。

套餐订阅、PU 资源与账户充值

腾讯云 ADP 当前采用“平台按月/按年订阅服务 + 增购包”的计费模式。订阅用于获得相应版本的平台权益和套餐额度，PU（Prepaid Unit）用于统一抵扣模型、插件、知识库等资源消耗，具体抵扣标准以计费概述和资源看板为准。

付费动作	得到什么	适合场景	注意事项
领取免费版	基础平台权益和对应额度	试用、原型	免费版不能充值 PU
购买平台套餐	Skill Plan、专业版、企业版等对应权益	正式项目、团队	月/年订阅，功能和限制不同
购买 PU 资源包	额外预付费 PU	套餐内 PU 不足	1万/10万/100万/1000万 PU，有效期 1 年
购买专属并发	指定模型或能力的并发资源	稳定低延迟业务	独立规格与变更规则
腾讯云账户充值	增加账户现金余额	支付订单、后付费账单	不会自动购买 ADP 套餐或 PU
云部署 License	指定版本和期限的软件许可	自有 TKE/VPC 部署	还要支付 IaaS 与运维费用

如何购买套餐

进入 ADP“平台管理—计费资源”，查看当前套餐版本说明，重点比较工作空间、应用、知识库、Multi-Agent、Claw、智能工作台、成员权限、监控和支持服务。选择月付或年付，确认订单主体、自动续费与到期规则后支付。不要根据文章中的历史价格下单，最终价格必须以控制台订单为准。

升级套餐时，官方规则按剩余天数计算差价和新增配额；当前文档说明不支持直接降级，需要按规则退费后重新购买。升级前先导出资源清单并确认应用不会因版本切换失去功能。

如何充值 PU

已购买有效套餐后，可在计费资源页面购买预付费资源包。官方当前列出 1 万、10 万、100 万和 1000 万 PU 档位，有效期一年；免费版不支持购买。扣费顺序为套餐配套 PU 优先，再使用预付费资源包。知识库超过套餐容量后可能按 GB/小时消耗 PU，因此闲置的大型知识库也要检查资源占用。

如何给腾讯云账户充值

进入腾讯云费用中心或账户资金管理页面。
确认当前账号、实名认证主体、可用余额和未结清账单。
选择控制台支持的在线充值或企业汇款方式。
输入金额并支付，随后在收支明细核对到账记录。
返回 ADP 提交套餐、PU 或 License 订单；若用于欠费，确认服务状态已恢复。
开启余额预警、续费提醒和费用异常通知。

账户充值只是增加现金余额，不会自动变成 PU。反过来，购买 PU 也不能用于所有腾讯云产品。企业汇款、优惠券、代金券、退款和国际站规则可能不同，应以费用中心显示为准。

续费、欠费和退费

平台套餐、专属并发和预付费资源包支持自动续费，但部分自动续费默认关闭，需要主动开启。官方文档说明，欠费后订阅套餐、资源包和专属并发都可能暂停；补充账户余额恢复正常后才能继续使用。预付费资源包通常不支持退购，套餐退费和席位/版本变更按当前规则执行。

成本管理与使用技巧

成本管理不能只看总金额。应在资源看板按工作空间、应用、模型、插件、知识库和时间拆分 PU 消耗，记录每个成功会话的平均成本。若某应用成本突然上升，检查上下文长度、检索 Top K、重复工具调用、工作流循环、失败重试和输出长度。

建议采用三档模型路由：高频分类与提取使用低成本模型；复杂问答或代码使用强模型；连续失败或高风险任务进入人工。知识库定期清理旧文件和重复向量；多 Agent 只在单 Agent 无法稳定完成时启用；工具结果应缓存，但涉及实时价格、库存和权限的数据不能长期缓存。

上线前设置预算阈值和熔断。当日 PU 消耗、失败率或平均工具调用超过阈值时，自动降低并发、切换备用模型或暂停高成本工作流，并通知责任人。不要等到账户欠费才发现循环调用。

权限、安全与生产治理

SecretId/SecretKey 权限通常高于应用 AppKey，应使用 CAM 子账号、角色和临时凭证，禁止放入前端、移动端、公开镜像和日志。对话端只持有自己的登录态，所有 ADP 调用由可信后端代理。密钥泄露后立即禁用、轮换并审计历史调用。

工作空间、应用、知识库和工具按最小权限授权。对包含个人信息、合同、财务或政务数据的知识库，先进行分类分级和脱敏。外部模型和连接器是否会处理数据、数据存储在哪里、保留多久，应在正式采购和合同中确认。

工具执行要使用白名单、Schema 校验和最小网络权限。发邮件、发消息、发布内容、删除文件、付款、退款、修改账户、调整权限、写生产数据库等动作必须人工确认。每次操作记录用户、会话、应用版本、模型、工具、参数摘要、结果和审批人，才能形成可追责的审计链。

常见问题排查

应用调试正常，发布后无法调用

检查是否已发布正式版本、AppKey 是否属于目标应用、账号是否有应用权限、调用 Endpoint 与中国站/国际站是否匹配，以及套餐、PU 和后付费能力是否可用。

Docker 启动失败

运行 docker ps 和官方项目日志命令，检查 2 核/4 GiB 最低资源、端口冲突、.env JSON 语法、数据库容器、镜像拉取和磁盘空间。修改源码后通常需要重新构建，单改 .env 是否需要重建以当前项目说明为准。

知识库没有召回正确文档

先检查文件解析、切片、元数据与权限，再调整检索数量和重排。用已知答案的测试集区分“没有检索到”和“模型没有正确使用证据”，不要直接扩大上下文掩盖问题。

PU 消耗异常快

在资源看板按应用和能力拆分用量。重点排查多 Agent 重复调用、长上下文、循环节点、失败重试、代码执行、插件、知识库超量和高成本模型。设置工作流最大时长与 Agent 最大轮次。

账户已充值但仍提示资源不足

现金余额与 PU 是两类资源。先确认欠费是否结清、套餐是否有效、PU 是否仍有余额、目标能力是否能用 PU 抵扣，以及订单是否属于当前账号。需要额外 PU 时必须购买预付费资源包，免费版不能直接充值 PU。

事实依据与来源

官方事实： 腾讯云产品文档确认 ADP 支持标准、单工作流、Multi-Agent 与 Claw 模式，并支持知识库、连接器、MCP、API/SDK 和多渠道发布。
官方事实： 当前公有云计费已转向按月/按年平台订阅加增购包，资源消耗使用 PU 体系；免费版不支持 PU 充值。
官方事实： 官方开源 ADP-Chat-Client 支持 Docker 部署，最低环境为 2 核 CPU、4 GiB 内存，Windows 建议 WSL。
官方事实： 云部署方案交付 License，运行在客户自有腾讯云 TKE 与 VPC 中，IaaS 和平台 License 分别承担成本。
实施建议： 环境隔离、密钥分权、工具审批、三档模型路由、预算熔断和灰度发布属于本文的工程建议。
待实际确认： 套餐价格、PU 抵扣比例、模型与插件清单、免费版额度和促销会调整，购买前以控制台订单及最新计费文档为准。

FAQ

腾讯云智能体开发平台需要安装吗？

使用公有云 SaaS 不需要安装平台，只需通过浏览器创建应用。需要独立 Web 对话端时可部署 ADP-Chat-Client；需要数据运行在自有腾讯云账号和 VPC 时，可购买云部署 License 并部署到 TKE。

免费版可以直接充值 PU 吗？

不可以。官方购买文档明确说明免费版不支持 PU 资源充值。需要先购买有效的订阅套餐，再购买相应的预付费 PU 资源包。

腾讯云账户充值是否等于购买 ADP 套餐？

不等于。账户充值只增加腾讯云现金余额；ADP 套餐、PU 资源包、专属并发或云部署 License 都需要单独提交订单。充值到账后可以用余额支付这些订单或结清欠费。

PU 是 Token 吗？

不是。PU 是 ADP 的预付费统一计量单位，可按规则抵扣模型、插件、知识库等不同资源；不同能力的 PU 消耗比例不同。Token 是模型文本计量单位，两者不能直接按 1:1 理解。

标准模式、工作流和 Multi-Agent 怎么选？

简单问答与单助手选标准模式；步骤固定、必须稳定重复的业务选单工作流；任务需要多个专业角色分工时再选 Multi-Agent。优先从最简单模式开始，避免不必要的成本和调试复杂度。

ADP-Chat-Client 是完整私有化平台吗？

不是。它是官方开源的对话端和集成方案，帮助把 ADP 应用部署成 Web 或多端入口；核心智能体仍来自 ADP。需要平台运行于自有腾讯云基础设施时，应评估云部署 License。

知识库是否需要单独购买 COS？

公有云 ADP 的知识库存储由平台管理，官方文档说明不需要另购 COS，也不支持把文件直接上传到客户自购 COS。ADP-Chat-Client 的文件预览等扩展场景可能另行使用 COS 能力，应按部署文档配置。

欠费后应用会怎样？

官方说明欠费后套餐、预付费资源包和专属并发可能暂停，应用服务会受影响。给腾讯云账户充值并结清欠费后可恢复，但具体恢复时间和资源保留规则以控制台状态为准。

如何防止智能体误操作企业系统？

只向 Agent 开放最小权限的 API；读写接口分离；验证所有参数；为写操作设置幂等键、审批和回滚；限制网络和调用次数；保存完整审计日志。提示词中的“不要误操作”不能替代执行层控制。

参考来源

内容核验日期：2026 年 09 月 25 日

会员充值教程

会员充值与订阅排查资料

适合阅读会员充值、订阅购买、权益对比和支付问题类文章后继续转化。

AI 订阅充值失败排查包 整理常见支付失败、地区限制、订单未到账和账号异常处理步骤。 查看资料包 会员权益对比表 对比不同 AI 工具会员权益、价格、适用人群和购买建议。 查看资料包