腾讯云智能体开发平台从零搭建一个 Claw 模式应用

本文用 ADP API 从零跑通一个 Claw 模式应用的完整生命周期：
创建空间 → 创建应用 → 创建 Agent → 配置 → 发布 → 创建会话 → 发起对话 → 获取产出
前置条件与调用方式
1. 准备密钥 SecretId / SecretKey（用于接口的 V3 签名）：
接入方式
密钥获取
请求地址
腾讯云
﻿腾讯云 CAM 控制台﻿
adp.tencentcloudapi.com
独立站
﻿ADP 控制台 > 密钥管理﻿
capi.adp.tencent.com
2. 安装依赖并初始化客户端：
# 1) 安装 ADP 专属 SDK：pip install tencentcloud-sdk-python-adp requests sseclient-py certifi
# 2) 配置密钥环境变量：TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY
# 3) 初始化 AdpClient（自动签名），后面每步都用它调用
import os
from tencentcloud.common import credential
from tencentcloud.common.profile.client_profile import ClientProfile
from tencentcloud.common.profile.http_profile import HttpProfile
from tencentcloud.adp.v20260520 import adp_client, models
﻿
cred = credential.Credential(
    os.environ["TENCENTCLOUD_SECRET_ID"],
    os.environ["TENCENTCLOUD_SECRET_KEY"],
)
# 腾讯云用户使用 adp.tencentcloudapi.com；独立站用户替换为 capi.adp.tencent.com
profile = ClientProfile(httpProfile=HttpProfile(endpoint="adp.tencentcloudapi.com"))
﻿
client = adp_client.AdpClient(cred, "ap-guangzhou", profile)
步骤 1：创建空间
调用 CreateSpace。
说明：
也可以直接使用系统内置的 default_space，跳过本步。
req = models.CreateSpaceRequest()
req.Name = "我的空间"
req.Description = "空间描述"
resp = client.CreateSpace(req)
space_id = resp.SpaceId
print(space_id)   # 例：UYiGYydT
如果没有创建空间的权限，可以先调用 DescribeSpaceList 查询已有空间列表，选择一个已有空间：
req = models.DescribeSpaceListRequest()
req.Query = ""
resp = client.DescribeSpaceList(req)
space_list = resp.SpaceList
print(space_list)   # 例：[{'SpaceId': 'UYiGYydT', 'Name': '我的空间', 'Description': '空间描述'}]
space_id = space_list[0].SpaceId
步骤 2：创建应用
调用 CreateApp，AppMode 传 4（Claw 模式）。
AppMode 枚举值：
值
模式
说明
1
标准模式
知识问答、RAG 场景
2
Agent 模式
自定义工具调用
3
单工作流模式
固定流程驱动
4
Claw 模式
带沙箱工作空间的自主 Agent
req = models.CreateAppRequest()
req.SpaceId = space_id
req.AppMode = 4               # 4 = Claw 模式
req.Name = "数据分析助手"
req.Description = "我的 Claw 应用"
resp = client.CreateApp(req)
app_id = resp.AppId
print(app_id)
步骤 3：创建 Agent
应用和 Agent 是两种不同的资源——应用是对外服务的载体，Agent 是承载具体能力的单元。用 CreateAgent 创建 Agent，可一次性设定指令、模型、Skill：
Kind 枚举值：
值
含义
0
配置端 Agent（创建应用时使用）
1
用户级 Agent（由 CopyAgentFromApp 复制生成，用于动态配置场景）
相关查询接口：
﻿DescribeModelList（获取可用模型列表，ModelScene=18 为 Claw 模式可用模型）。
﻿DescribeSkillSummaryList（获取可用 Skill 列表）。
# 3.1 拉取 Claw 场景可用模型
req = models.DescribeModelListRequest()
req.SpaceId = space_id
req.ModelScene = 18           # 18 = Claw 模式可用模型
req.PageNumber = 0
req.PageSize = 20
resp = client.DescribeModelList(req)
model_id = resp.ModelList[0].ModelBasic.ModelId
﻿
# 3.2 （可选）拉取可用 Skill
req = models.DescribeSkillSummaryListRequest()
req.SpaceId = space_id
resp = client.DescribeSkillSummaryList(req)
skill_id = resp.SkillSummaryList[0].SkillId
﻿
# 3.3 创建配置端主 Agent，一次性设定指令 / 模型 / Skill
req = models.CreateAgentRequest()
req.AppId = app_id
req.Kind = 0                          # 配置端 Agent
req.Agent = models.AgentConfig()
req.Agent.Profile = models.AgentProfile()
req.Agent.Profile.Name = "数据分析主 Agent" #APP名称在空间内唯一
req.Agent.Profile.Role = 0           # Role 0 = 主 Agent
req.Agent.Instructions = "你是一个数据分析助手，擅长生成报表。"
req.Agent.Model = models.AgentModelConfig()
req.Agent.Model.ModelId = model_id
req.Agent.Model.ContextWordsLimit = 20000
req.Agent.Model.InstructionsWordsLimit = 20000
req.Agent.SkillList = [skill=models.AgentSkill()skill.SkillId=skill_id]
req.Agent.AdvancedConfig = models.AgentAdvancedConfig()
req.Agent.AdvancedConfig.MaxReasoningRound = 100
resp = client.CreateAgent(req)
agent_id = resp.AgentId
步骤 4：修改配置（可选）
配置分为应用级和 Agent 级两个层级。应用级配置是所有 Agent 共享的通用设置，Agent 级配置是单个 Agent 独有的能力设置：
层级
包含内容
接口
应用级
开场白、记忆、联网搜索、数智人、体验设置等（所有 Agent 共享）
﻿ModifyApp﻿
Agent 级
指令、推理模型、Skill、工具、插件（单个 Agent 独有）
﻿ModifyAgent﻿
两者都用 UpdateMask.Paths 局部更新，只改指定字段：
# 改 Agent 的指令（Agent 级）
req = models.ModifyAgentRequest()
req.AppId = app_id
req.AgentId = agent_id
req.Agent = models.AgentConfig()
req.Agent.Instructions = "你是一个严谨的数据分析助手。"
req.UpdateMask = models.FieldMask()
req.UpdateMask.Paths = ["Instructions"]
client.ModifyAgent(req)
﻿
# 改应用开场白（应用级）
req = models.ModifyAppRequest()
req.AppId = app_id
req.Config = models.AppConfig()
req.Config.Greeting = models.AppGreetingConfig()
req.Config.Greeting.Greeting = "你好，我是数据分析助手～"
req.UpdateMask = models.FieldMask()
req.UpdateMask.Paths = ["Config.Greeting.Greeting"]
client.ModifyApp(req)
UpdateMask 支持的字段：
接口
支持的字段
ModifyAgent
Profile.Name、Instructions、Model、ToolList、PluginList、SkillList、AdvancedConfig 等
ModifyApp
Name、Config.Greeting、Config.Model、Config.Memory、Config.Experience 等应用级字段
注意：
修改配置后不会立即生效，必须执行 步骤 5：发布应用 后，改动才对外服务可见。
打开「允许在对话中动态修改配置」开关
运行时动态配置：如果你希望每个用户/每次对话都能动态换模型、装卸 Skill、透传自定义变量（而不是所有人共用发布时的固定配置），需要在应用的高级设置里打开「允许在对话中动态修改配置」开关。
打开后才能在 CreateConversation 里传用户级 AgentId、在对话请求里注入运行时配置。完整用法见 动态修改 Agent 配置。
步骤 5：发布应用
配置只有发布后才对外生效。调用 CreateRelease 触发发布，再用 DescribeReleaseSummary 轮询发布状态直到完成，最后通过 DescribeApp 获取对话所需的 AppKey。
发布状态枚举：
枚举值
状态
1
发布中
2
排队中
3
发布成功
4
发布失败
req = models.CreateReleaseRequest()
req.AppId = app_id
req.Description = "首次发布"
resp = client.CreateRelease(req)
release_id = resp.ReleaseId
print("ReleaseId:", release_id)
﻿
# 发布是异步任务，轮询直到发布完成
import time
while True:
    req = models.DescribeReleaseSummaryRequest()
    req.AppId = app_id
    req.ReleaseId = release_id
    resp = client.DescribeReleaseSummary(req)
    status = resp.ReleaseSummary.Status
    if status == 3:
        print("发布成功")
        break
    elif status == 4:
        print("发布失败")
        break
    time.sleep(2)
﻿
# 获取 AppKey（对话时需要）—— 通过 FieldMask 指定只返回 SecretInfo 字段
req = models.DescribeAppRequest()
req.AppId = app_id
req.FieldMask = models.FieldMask()
req.FieldMask.Paths = ["SecretInfo"]
resp = client.DescribeApp(req)
APP_KEY = resp.App.SecretInfo.AppKey
print("AppKey:", APP_KEY)
步骤 6：创建会话
调用 CreateConversation 创建一个会话，拿到 ConversationId：
AgentId（可选）：打开「允许在对话中动态修改配置」开关后可传，用于绑定一个用户级 Agent。详情请参见 动态修改 Agent 配置。
会话是后续所有动作的引用句柄；同一 ConversationId 内多轮对话共享上下文与工作空间。
Type 枚举值：
枚举值
含义
5
API 接入
# APP_KEY 已在 步骤 5 通过 DescribeApp 获取
USER_ID = "user-001"          # 你系统里的用户唯一标识
﻿
req = models.CreateConversationRequest()
req.Type = 5                  # API 接入
req.AppId = app_id
req.AppKey = APP_KEY
req.UserId = USER_ID
resp = client.CreateConversation(req)
conversation_id = resp.ConversationId
步骤 7：发起对话（SSE）
﻿对话流接口 与腾讯云接口不同：走独立域名、用 AppKey 鉴权、以 SSE 流式返回（无需 V3 签名）。
接入方式
对话端点
腾讯云
https://wss.lke.cloud.tencent.com/adp/v2/chat
独立站
https://adp.tencent.com/adp/v2/chat
import json
import requests
import sseclient   # pip install sseclient-py
﻿
# 对话端点（根据接入方式选择）
# 腾讯云：https://wss.lke.cloud.tencent.com/adp/v2/chat
# 独立站：https://adp.tencent.com/adp/v2/chat
CHAT_ENDPOINT = "https://wss.lke.cloud.tencent.com/adp/v2/chat"
﻿
body = {
    "RequestId": uuid.uuid4().hex
    "ConversationId": conversation_id,   # 必填，缺了直接被拒（400）
    "AppKey": APP_KEY,
    "VisitorId": USER_ID,
    "Contents": [{"Type": "text", "Text": "请生成这个季度的 mock 销售数据，然后分析销售数据并生成 Excel 报告"}],
    "Incremental": True,
    "EnableMultiIntent": True,
    "Stream": "enable",
}
﻿
with requests.post(CHAT_ENDPOINT, json=body,
                   headers={"Accept": "text/event-stream"}, stream=True) as r:
    for sse_event in sseclient.SSEClient(r).events():
        event = json.loads(sse_event.data)
        if event["Type"] == "text.delta":
            print(event["Text"], end="", flush=True)
        elif event["Type"] == "response.completed":
            break
响应（SSE 流）
data: {"Type":"request_ack","RequestId":"..."}
data: {"Type":"response.created","RecordId":"r1"}
data: {"Type":"message.added","MessageId":"m1","MessageType":"thought"}
data: {"Type":"text.delta","MessageId":"m1","Text":"先读取数据..."}
data: {"Type":"message.done","MessageId":"m1"}
data: {"Type":"message.added","MessageId":"m2","MessageType":"reply"}
data: {"Type":"text.delta","MessageId":"m2","Text":"分析完成。"}
data: {"Type":"response.completed"}
拉取历史消息
用 DescribeConversationMessageList 获取完整历史：
req = models.DescribeConversationMessageListRequest()
req.ConversationId = conversation_id
req.UserId = USER_ID
req.AppKey = APP_KEY
req.Type = 5
req.Limit = 10
resp = client.DescribeConversationMessageList(req)
history = resp.MessageList
步骤 8：获取产出文件
Claw 模式下，Agent 生成的文件（Excel、图片、代码等）会以 COS 文件地址的形式包含在对话消息的 Contents 中。当 Content.Type = "file" 时，通过 Content.File.FileUrl 即可获取文件的 COS 下载地址。
FileInfo 数据结构：
字段
类型
说明
FileName
String
文件名称
FileUrl
String
文件 COS 下载地址
FileSize
String
文件大小
FileType
String
文件类型
在 步骤 7 的 SSE 流中，当 Agent 产出文件时，message.done 事件的 Contents 里会包含 Type = "file" 的内容项，从中即可提取 COS 下载地址：
# 在 SSE 流处理中，当收到 message.done 事件时提取文件
if event["Type"] == "message.done":
    message = event["Message"]
    for content in message.get("Contents", []):
        if content["Type"] == "file":
            file_info = content["File"]
            print(f"文件: {file_info['FileName']}")
            print(f"下载地址: {file_info['FileUrl']}")
            # 可直接用 requests.get(file_info['FileUrl']) 下载
全流程接口一览
步骤
接口
创建空间
﻿CreateSpace / DescribeSpaceList（查询已有空间）
创建应用
﻿CreateApp（AppMode=4）
创建 Agent
﻿CreateAgent + DescribeModelList（获取可用模型） + DescribeSkillSummaryList（获取可用 Skill）
修改配置
﻿ModifyApp（应用级） + ModifyAgent（Agent 级）
发布应用
﻿CreateRelease + DescribeReleaseSummary（轮询状态） + DescribeApp（获取 AppKey）
创建会话
﻿CreateConversation﻿
发起对话
﻿POST /adp/v2/chat（SSE 流式对话）
获取产出文件
从 SSE 流的 message.done 事件中提取文件 COS 地址，直接下载

接口	支持的字段
`ModifyAgent`	`Profile.Name`、`Instructions`、`Model`、`ToolList`、`PluginList`、`SkillList`、`AdvancedConfig` 等
`ModifyApp`	`Name`、`Config.Greeting`、`Config.Model`、`Config.Memory`、`Config.Experience` 等应用级字段

接入方式	密钥获取	请求地址
腾讯云	腾讯云 CAM 控制台	`adp.tencentcloudapi.com`
独立站	ADP 控制台 > 密钥管理	`capi.adp.tencent.com`

值	模式	说明
1	标准模式	知识问答、RAG 场景
2	Agent 模式	自定义工具调用
3	单工作流模式	固定流程驱动
4	Claw 模式	带沙箱工作空间的自主 Agent

值	含义
0	配置端 Agent（创建应用时使用）
1	用户级 Agent（由 `CopyAgentFromApp` 复制生成，用于动态配置场景）

层级	包含内容	接口
应用级	开场白、记忆、联网搜索、数智人、体验设置等（所有 Agent 共享）	ModifyApp
Agent 级	指令、推理模型、Skill、工具、插件（单个 Agent 独有）	ModifyAgent

枚举值	状态
1	发布中
2	排队中
3	发布成功
4	发布失败

接入方式	对话端点
腾讯云	`https://wss.lke.cloud.tencent.com/adp/v2/chat`
独立站	`https://adp.tencent.com/adp/v2/chat`

字段	类型	说明
`FileName`	String	文件名称
`FileUrl`	String	文件 COS 下载地址
`FileSize`	String	文件大小
`FileType`	String	文件类型

步骤	接口
创建空间	CreateSpace / DescribeSpaceList（查询已有空间）
创建应用	CreateApp（`AppMode=4`）
创建 Agent	CreateAgent + DescribeModelList（获取可用模型） + DescribeSkillSummaryList（获取可用 Skill）
修改配置	ModifyApp（应用级） + ModifyAgent（Agent 级）
发布应用	CreateRelease + DescribeReleaseSummary（轮询状态） + DescribeApp（获取 AppKey）
创建会话	CreateConversation
发起对话	POST /adp/v2/chat（SSE 流式对话）
获取产出文件	从 SSE 流的 `message.done` 事件中提取文件 COS 地址，直接下载

从零搭建一个 Claw 模式应用

本页目录：

前置条件与调用方式

步骤 1：创建空间

步骤 2：创建应用

步骤 3：创建 Agent

步骤 4：修改配置（可选）

打开「允许在对话中动态修改配置」开关

步骤 5：发布应用

步骤 6：创建会话

步骤 7：发起对话（SSE）

拉取历史消息

步骤 8：获取产出文件

全流程接口一览