从零搭建一个 Claw 模式应用

本文用 ADP API 从零跑通一个 Claw 模式应用的完整生命周期：

创建空间 → 创建应用 → 创建 Agent → 配置 → 发布 → 创建会话 → 发起对话 → 获取产出

前置条件与调用方式

准备密钥 SecretId / SecretKey（用于接口的 V3 签名）：

安装依赖并初始化客户端：

# 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.SpaceIdprint(space_id)   # 例：UYiGYydT

如果没有创建空间的权限，可以先调用 DescribeSpaceList 查询已有空间列表，选择一个已有空间：

req = models.DescribeSpaceListRequest()req.Query = ""resp = client.DescribeSpaceList(req)space_list = resp.SpaceListprint(space_list)   # 例：[{'SpaceId': 'UYiGYydT', 'Name': '我的空间', 'Description': '空间描述'}]space_id = space_list[0].SpaceId

步骤 2：创建应用

调用 CreateApp，AppMode 传 4（Claw 模式）。

AppMode 枚举值：

req = models.CreateAppRequest()req.SpaceId = space_idreq.AppMode = 4               # 4 = Claw 模式req.Name = "数据分析助手"req.Description = "我的 Claw 应用"resp = client.CreateApp(req)app_id = resp.AppIdprint(app_id)

步骤 3：创建 Agent

应用和 Agent 是两种不同的资源——应用是对外服务的载体，Agent 是承载具体能力的单元。用 CreateAgent 创建 Agent，可一次性设定指令、模型、Skill：

Kind 枚举值：

相关查询接口：

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

skill = models.AgentSkill()
skill.SkillId = skill_id
req.Agent.SkillList = [skill]

req.Agent.AdvancedConfig = models.AgentAdvancedConfig()
req.Agent.AdvancedConfig.MaxReasoningRound = 100
resp = client.CreateAgent(req)
agent_id = resp.AgentId

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

配置分为应用级和 Agent 级两个层级。应用级配置是所有 Agent 共享的通用设置，Agent 级配置是单个 Agent 独有的能力设置：

两者都用 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 支持的字段：

注意：

修改配置后不会立即生效，必须执行 步骤 5：发布应用 后，改动才对外服务可见。

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

运行时动态配置：如果你希望每个用户/每次对话都能动态换模型、装卸 Skill、透传自定义变量（而不是所有人共用发布时的固定配置），需要在应用的高级设置里打开「允许在对话中动态修改配置」开关。

打开后才能在 CreateConversation 里传用户级 AgentId、在对话请求里注入运行时配置。完整用法见 动态修改 Agent 配置。

步骤 5：发布应用

配置只有发布后才对外生效。调用 CreateRelease 触发发布，再用 DescribeReleaseSummary 轮询发布状态直到完成，最后通过 DescribeApp 获取对话所需的 AppKey。

发布状态枚举：

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 枚举值：

# 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 签名）。

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_idreq.UserId = USER_IDreq.AppKey = APP_KEYreq.Type = 5req.Limit = 10resp = client.DescribeConversationMessageList(req)history = resp.MessageList

步骤 8：获取产出文件

Claw 模式下，Agent 生成的文件（Excel、图片、代码等）会以 COS 文件地址的形式包含在对话消息的 Contents 中。当 Content.Type = "file" 时，通过 Content.File.FileUrl 即可获取文件的 COS 下载地址。

FileInfo 数据结构：

在 步骤 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']) 下载

全流程接口一览