腾讯云智能体开发平台 Claw 模式应用

一、前置条件与调用方式

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

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

# 1) 安装 ADP 专属 SDK：pip install tencentcloud-sdk-python-adp requests sseclient-py certifi# 2) 配置密钥环境变量：TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY# 3) 初始化 AdpClient（自动签名），后面每步都用它调用import osfrom tencentcloud.common import credentialfrom tencentcloud.common.profile.client_profile import ClientProfilefrom tencentcloud.common.profile.http_profile import HttpProfilefrom tencentcloud.adp.v20260520 import adp_client, modelscred = credential.Credential( os.environ["TENCENTCLOUD_SECRET_ID"], os.environ["TENCENTCLOUD_SECRET_KEY"],)# 腾讯云用户使用 adp.tencentcloudapi.com；独立站用户替换为 capi.adp.tencent.comprofile = 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_idreq.ModelScene = 18 # 18 = Claw 模式可用模型req.PageNumber = 0req.PageSize = 20resp = client.DescribeModelList(req)model_id = resp.ModelList[0].ModelBasic.ModelId# 3.2 （可选）拉取可用 Skillreq = models.DescribeSkillSummaryListRequest()req.SpaceId = space_idresp = client.DescribeSkillSummaryList(req)skill_id = resp.SkillSummaryList[0].SkillId# 3.3 创建配置端主 Agent，一次性设定指令 / 模型 / Skillreq = models.CreateAgentRequest()req.AppId = app_idreq.Kind = 0 # 配置端 Agentreq.Agent = models.AgentConfig()req.Agent.Profile = models.AgentProfile()req.Agent.Profile.Name = "数据分析主 Agent" #APP名称在空间内唯一req.Agent.Profile.Role = 0 # Role 0 = 主 Agentreq.Agent.Instructions = "你是一个数据分析助手，擅长生成报表。"req.Agent.Model = models.AgentModelConfig()req.Agent.Model.ModelId = model_idreq.Agent.Model.ContextWordsLimit = 20000req.Agent.Model.InstructionsWordsLimit = 20000skill = models.AgentSkill()skill.SkillId = skill_idreq.Agent.SkillList = [skill]req.Agent.AdvancedConfig = models.AgentAdvancedConfig()req.Agent.AdvancedConfig.MaxReasoningRound = 100resp = client.CreateAgent(req)agent_id = resp.AgentId

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

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

两者都用 UpdateMask.Paths 局部更新，只改指定字段：

# 改 Agent 的指令（Agent 级）req = models.ModifyAgentRequest()req.AppId = app_idreq.AgentId = agent_idreq.Agent = models.AgentConfig()req.Agent.Instructions = "你是一个严谨的数据分析助手。"req.UpdateMask = models.FieldMask()req.UpdateMask.Paths = ["Instructions"]client.ModifyAgent(req)# 改应用开场白（应用级）req = models.ModifyAppRequest()req.AppId = app_idreq.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_idreq.Description = "首次发布"resp = client.CreateRelease(req)release_id = resp.ReleaseIdprint("ReleaseId:", release_id)# 发布是异步任务，轮询直到发布完成import timewhile 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_idreq.FieldMask = models.FieldMask()req.FieldMask.Paths = ["SecretInfo"]resp = client.DescribeApp(req)APP_KEY = resp.App.SecretInfo.AppKeyprint("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_idreq.AppKey = APP_KEYreq.UserId = USER_IDresp = client.CreateConversation(req)conversation_id = resp.ConversationId

九、步骤 7：发起对话（SSE）

对话流接口 与腾讯云接口不同：走独立域名、用 AppKey 鉴权、以 SSE 流式返回（无需 V3 签名）。

import jsonimport requestsimport sseclient # pip install sseclient-py# 对话端点（根据接入方式选择）# 腾讯云：https://wss.lke.cloud.tencent.com/adp/v2/chat# 独立站：https://adp.tencent.com/adp/v2/chatCHAT_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']) 下载

十二、全流程接口一览