从零用腾讯云ADP OpenAPI构建云端龙虾

很多企业已经配置了 Agent，但使用方式还停留在独立聊天窗口里：员工需要另开入口提问，知识内容依赖人工导入，业务系统想要调用 Agent 能力时，也缺少稳定的接入方式。

要把 Agent 接到工作台、CRM、ERP 或交易链路中，通常需要两类能力：一类是云端运行环境，让 Agent 能读取企业知识、调用内部接口、执行多步任务，并与员工本地电脑解耦；另一类是开放接口，让业务系统可以提交任务、获取结果，并按企业流程更新知识与应用配置。

腾讯云ADP 通过 Claw 模式提供 Agent 的云端运行环境，并通过 OpenAPI 将 Agent 接入企业系统。本文以“云端龙虾”为企业自定义 Agent 示例，拆解从业务任务定义、Claw 应用配置、OpenAPI 接入到测试发布的完整路径。

核心要点

• “云端龙虾”可以理解为运行在腾讯云 ADP Claw 模式中的企业自定义 Agent。
• Claw 为 Agent 提供独立沙箱工作空间，可执行代码、生成文件、调用 Skills、连接器和工具。
• 知识库管理 OpenAPI 用于把企业知识更新接入业务流程。
• 配置端 OpenAPI 用于程序化管理应用、Agent、工具、知识库关联与发布版本。
• 对话端 OpenAPI 用于让工作台、CRM、ERP、自有 App 等业务入口调用已发布应用。
• 开发者 Secret 应在服务端管理；使用者侧通过 AppKey 调用已发布应用，前端不应直接接触开发者 Secret。
• 应用配置调整后需要显式发布，发布后业务系统继续按同一套调用协议和 AppKey 使用新的已发布版本。

1. 先理解“云端龙虾”：Claw 应用承担什么角色

Claw 是腾讯云 ADP 提供的应用模式之一。它为 Agent 提供独立的沙箱工作空间，适合处理需要多步判断和持续执行的任务。会话之间使用独立沙箱，运行环境与员工电脑分开。

在 Claw 中，企业可以配置以下内容：

配置完成后，Claw 应用可以通过网页或发布渠道供员工使用，也可以通过 OpenAPI 接入企业自己的工作台、中台、CRM 或 App。

这种方式的关键在于：Agent 的能力集中在 ADP 中维护，业务系统侧负责调用和展示。企业无需为每个业务系统分别维护一套 Agent 运行环境。

在 B2B 贸易等复杂业务中，企业通常需要让 Agent 处理询价识别、商机沉淀、查货配单、报价生成、采购寻源和比价等任务。上海找钢网与腾讯云 ADP 联合建设的钢贸方案“找钢 Claw”，就是企业自定义云端龙虾的应用示例。对其他企业来说，可以将其中的商品、规则和流程替换为自己的知识库、内部工具和业务系统，沿用类似的构建方式。面向贸易场景的能力介绍，也可以参考 ADP 贸易解决方案。

2. 从一个业务任务开始，而不是一次性搭完整系统

构建企业级 Agent 时，建议先选择一个需要多步处理、边界相对清晰的业务任务。

例如，员工在业务工作台中提交一段客户询价信息，希望 Agent 完成以下动作：

1. 识别客户询价中的商品、规格、数量等关键信息；
2. 结合企业知识库理解商品规则和报价规则；
3. 调用内部工具或系统查询库存、客户或订单数据；
4. 按企业规则生成报价或跟进建议；
5. 将结果返回业务工作台，由员工确认或继续处理。

这个任务通常会同时用到三类能力：

• 知识库中的商品知识、业务规则、报价策略；
• 企业内部系统中的库存、客户或订单数据；
• 对话端 OpenAPI，用于接收任务并返回结果。

整体链路可以概括为：

业务工作台提交任务
        ↓
对话端 OpenAPI 调用已发布应用
        ↓
Claw 应用理解任务、检索知识、调用工具
        ↓
处理结果返回工作台或业务流程

在这条链路中，员工仍然使用原来的业务入口。Agent 的运行、知识检索和工具调用由腾讯云 ADP 承担，业务系统负责提交任务、展示结果和承接后续流程。

3. 在 ADP 中创建 Claw 应用并配置 Agent

进入实施阶段后，可以先在 ADP 控制台完成基础配置，再考虑通过 OpenAPI 接入业务系统。

一个常见的配置顺序如下：

1. 在 ADP 中选择 Claw 模式，创建应用和 Agent；
2. 配置提示词、模型和任务规则；
3. 关联企业知识库；
4. 配置 Skills、连接器、插件和工具；
5. 设置空间、成员、用户级 Agent 和权限边界；
6. 在对话窗口中验证任务执行效果；
7. 完成应用发布，形成可被业务系统调用的版本。

这里需要把业务规则尽量拆成可验证的指令。例如，询价识别场景中，可以先让 Agent 稳定输出商品、规格、数量、客户诉求等结构化信息；再逐步加入查货、比价、报价生成等能力。

开发团队可以使用以下检查点控制质量：

• Agent 是否能稳定理解同一类任务；
• 知识库检索结果是否与业务问题相关；
• 工具调用是否在预期边界内发生；
• 生成结果是否符合企业规则；
• 异常输入是否有清晰的兜底回复；
• 权限、空间和成员配置是否符合企业管理要求。

创建、配置和发布都可以在控制台完成。OpenAPI 的价值在于把这些能力接入企业自己的系统和流程中，例如程序化创建应用、批量管理 Agent、接入发版流水线，或让现有产品调用已发布应用。

4. 用知识库管理 OpenAPI 维护企业知识

企业知识会持续变化。商品资料会增加，业务规则会调整，报价策略和客户偏好也可能更新。如果知识库只在项目上线时导入一次，Agent 后续很容易使用过期内容。

腾讯云 ADP 提供知识库管理 OpenAPI，可以把文档录入、知识更新等动作接入企业自己的管理流程。业务系统或内部任务可以按实际需要，将商品知识、业务规则、报价策略和客户偏好写入或更新到知识库。

建议将知识更新流程拆成三层：

知识库管理 OpenAPI 解决的是企业内容如何进入和更新知识库。对话端 OpenAPI 解决的是业务任务如何交给 Agent 处理。两类接口配合后，知识变化和业务调用可以接入同一套企业系统流程。

5. 用配置端 OpenAPI 管理应用、Agent 与发布版本

企业的 Agent 通常需要持续迭代：提示词要调整，模型可能要切换，工具需要增加，知识库也可能需要重新关联。当应用数量增加后，单靠控制台逐个操作会变得繁琐。

配置端 OpenAPI 可以用于将应用和 Agent 的管理接入企业自己的开通、配置和发布流程。它适合处理以下任务：

• 创建和管理应用、Agent；
• 配置应用级和 Agent 级能力；
• 管理工具、Skills 和知识库关联；
• 创建发布版本；
• 进行版本发布和回滚。

可以把配置端 OpenAPI 理解为管理“怎么搭”和“怎么发”的接口体系；对话端 OpenAPI 则负责“怎么用”。

应用配置修改后不会自动对外生效，需要显式发布。发布后，业务系统可以继续使用同一套调用协议和 AppKey，访问新的已发布版本。对于需要多环境管理的团队，建议将开发、测试、发布、回滚等动作纳入现有研发流程，避免未验证的配置直接影响生产入口。

如果企业正在评估智能体开发平台，也可以结合功能需求、调用规模和上线节奏查看 ADP定价，提前规划试点与扩展阶段的资源投入。

6. 用对话端 OpenAPI 接入工作台、CRM、ERP 或自有 App

对话端 OpenAPI 面向已经发布的应用。业务系统可以把员工输入、表单内容或流程节点结果传给 Agent。Agent 完成知识检索、工具调用和任务处理后，将结果通过流式或非流式方式返回。

在接入设计中，需要清晰区分开发者侧和使用者侧的密钥边界：

• 开发者侧使用 Secret 管理配置端调用；
• 使用者侧通过 AppKey 调用已发布应用；
• 前端不应直接接触开发者 Secret；
• 密钥和权限边界应留在服务端与平台侧管理。

同一套对话端能力，可以接入不同入口。控制台里的 ADP 问答助手，就是对话端 OpenAPI 接入 Web 侧栏的效果。员工可以在智能工作台里直接问产品、排错和案例，无需另开一套对话产品。

对于需要更接近官方智能工作台完整 Web 体验的团队，可以参考 ADP-Chat-Client。它提供前端界面和后端转发，后端负责签名和流式对话，前端不接触开发者密钥。平台侧修改模型、知识库、Skills 和工具并发布后，各入口可以一起生效，Agent 能力仍在 ADP 中统一维护。

7. 用 ADP-Chat-Client 快速验证 Web 接入

如果希望把智能体应用的对话能力快速嵌入业务系统，可以参考腾讯云官方开源项目 ADP-Chat-Client。它是一个开源的 AI 智能体应用对话端解决方案，提供可定制的前端界面和后端服务。基于腾讯云 ADP 开发的智能体应用，可通过该项目部署为 Web 应用，也可嵌入小程序、Android、iOS 等多端场景。

根据官方文档，ADP-Chat-Client 支持实时对话、对话历史管理、语音输入、图片理解、第三方账户体系对接等功能，目前支持通过 Docker 快速部署。

部署前，机器需满足以下最低要求：

• CPU >= 2 Core；
• RAM >= 4 GiB；
• 操作系统：Linux/macOS；如需在 Windows 系统运行，需要通过 WSL，或使用 Linux 系统的云服务器。

基础部署流程如下：

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

如果系统尚未安装 Docker，可根据操作系统执行初始化脚本：

# TencentOS Server 4.4
bash script/init_env_tencentos.sh

# Ubuntu Server 24.04
bash script/init_env_ubuntu.sh

复制环境变量示例文件：

cp server/.env.example deploy/default/.env

随后修改 deploy/default/.env 中的配置项，包括腾讯云账户密钥、ADP 平台获取的智能体应用 AppKey，以及 JWT 密钥等信息。示例配置结构如下：

# 腾讯云账户密钥：https://console.cloud.tencent.com/cam/capi
TC_SECRET_APPID = ""
TC_SECRET_ID = ""
TC_SECRET_KEY = ""

# ADP平台获取的智能体应用key：https://adp.cloud.tencent.com/
APP_CONFIGS = '[
  {
    "Vendor": "Tencent",
    "ApplicationId": "对话应用唯一Id",
    "Comment": "用户自定义备注",
    "AppKey": "",
    "International": false
  }
]'

# JWT密钥，一个随机字符串，可以使用uuidgen命令生成
SECRET_KEY = ""

配置时需要遵循 JSON 规范，例如 APP_CONFIGS 最后一项末尾不能有逗号，也不支持 // 注释。ApplicationId 可以进入任意 ADP 应用，在应用网址内查看 appid。

制作镜像并启动容器：

sudo make pack
sudo make deploy

生产系统建议通过自有域名申请 SSL 证书，并使用 Nginx 反向代理等方式部署到 HTTPS 协议。如果仅基于 HTTP 协议部署，语音识别、消息复制等功能可能无法正常工作。

问题排查可以先检查容器：

sudo docker ps

正常情况下应看到两个容器：adp-chat-client-default 和 adp-chat-client-db-default。如果未看到容器，可以查看日志：

sudo make logs

账户体系方面，ADP-Chat-Client 支持 GitHub OAuth、Microsoft Entra ID OAuth，也可以根据业务需求定制其他 OAuth。对于已经有自有账户体系但没有标准 OAuth 的企业，可以采用 URL 跳转方式：现有账户服务生成携带 CustomerId、Name、ExtraInfo、Timestamp 和签名的 URL，系统校验签名后创建或绑定账户，并跳转到对话页面。

8. 上线前的测试、发布与持续优化

一只企业自定义云端龙虾通常按以下顺序从配置走向上线：

1. 在 ADP 中选择 Claw 模式，创建应用和 Agent；
2. 配置提示词、模型、知识库、Skills、连接器和工具；
3. 导入企业知识，需要时用知识库管理 OpenAPI 接入导入和更新流程；
4. 在对话窗口测试任务执行、知识检索和工具调用效果；
5. 在控制台完成应用发布；需要程序化管理时，再使用配置端 OpenAPI；
6. 使用对话端 OpenAPI 将已发布应用接入工作台或自有系统；
7. 根据对话记录、评测结果和业务反馈继续调整，再发布新版本。

上线前建议至少检查以下项目：

这套方式适合已有业务系统，同时希望加入自然语言理解和多步任务处理的企业。例如：

• 在 CRM 中识别客户需求，生成商机和跟进建议；
• 在 ERP 或采购系统中查询库存、整理供应商报价；
• 在客服工作台中检索企业知识，生成符合业务规则的答复；
• 在 OA 流程中读取材料、调用知识库并回写处理结果；
• 在自有 App 中提供面向员工或客户的业务智能助手。

不同行业可以结合自己的知识、工具和流程进行配置。面向内容生产、审核和分发场景，可参考 ADP 媒体解决方案；面向智能法务、合同与法规知识场景，可参考 ADP 法律解决方案；面向教育行业的知识问答和教学辅助场景，可参考 ADP 教育解决方案。

FAQ

1. 云端龙虾和普通聊天机器人有什么区别？

“云端龙虾”是对 ADP Claw 模式企业自定义 Agent 的形象化说法。它运行在云端沙箱工作空间中，可以结合企业知识、Skills、连接器和工具处理多步任务，并通过 OpenAPI 接入业务系统。

2. 知识库管理 OpenAPI、配置端 OpenAPI、对话端 OpenAPI 分别适合做什么？

知识库管理 OpenAPI 适合处理文档录入和知识更新；配置端 OpenAPI 适合管理应用、Agent、工具、知识库关联和发布版本；对话端 OpenAPI 适合让工作台、CRM、ERP、自有 App 等入口调用已发布应用。

3. 是否必须一开始就使用 OpenAPI？

不一定。业务人员可以先在 ADP 控制台配置提示词、知识库和工具，并在对话窗口中验证效果。待任务效果稳定后，开发者再通过 OpenAPI 接入企业系统。

4. 应用配置修改后会立即影响业务系统吗？

应用配置修改后需要显式发布。发布后，业务系统继续使用同一套调用协议和 AppKey，访问新的已发布版本。

5. 前端可以直接调用配置端接口吗？

不建议。开发者 Secret 应保留在服务端和平台侧管理。使用者侧通过 AppKey 调用已发布应用，前端不应直接接触开发者 Secret。

6. ADP-Chat-Client 适合什么场景？

ADP-Chat-Client 适合希望快速验证 Web 对话入口、复用前端界面和后端转发能力的团队。它可以帮助开发者快速部署对话端体验，并支持与第三方账户体系对接。

总结：从一个任务开始，把 Agent 接进企业流程

用腾讯云 ADP OpenAPI 构建企业自定义云端龙虾，可以从一个清晰的业务任务切入：先在 Claw 模式中配置 Agent 的业务行为、企业知识、执行能力和运行边界，再通过知识库管理 OpenAPI 保持知识更新，通过配置端 OpenAPI 管理应用和发布，通过对话端 OpenAPI 接入工作台、CRM、ERP 或自有 App。

这条路径的优势在于可逐步推进：先验证单个任务，再接入业务入口；先用控制台完成配置，再把高频管理动作纳入 OpenAPI；先服务一个团队，再扩展到更多流程和系统。

了解 腾讯云ADP，获取企业级 Agent 构建能力与 OpenAPI 接入指引。