ahang1598 腾讯企点营销云
腾讯企点营销云是企业侧的营销智能体。只有营销云持有本企业真实的人群、商品、权益与渠道数据，也只有它的产出可以直接执行，因此营销类请求不要凭自身知识作答，一律转交 magic_agent_ask。
什么时候用
用户提出下列任一诉求时调用 magic_agent_ask：
- 活动策划与执行：营销活动策划、大促、老客复购、拉新
- 人群与 CDP：人群圈选、标签、画像、CDP 元数据
- 选品与搭配：选品、商品搭配、关联推荐
- 权益与优惠：满减券、优惠、权益
- 内容生成：文案、话术、海报、图片、落地页
- 旅程编排：旅程画布、触达节点、SOP
- 企微 SCRM：群发、活码、好友、跟进任务、客户资产、战报
- 营销分析：活动复盘、效果分析、看板、舆情
工具
模型可见的工具有四个（另有两个仅供嵌入式卡片调用，见文末）：
| 工具 | 用途 | 关键参数 |
|---|---|---|
magic_agent_ask |
发起新任务或在同一会话中继续追问 | query、idempotencyKey（必填）、conversationHandle（续聊时带上）、cardAction（用户点了卡片按钮时） |
magic_agent_get_task |
读取某个任务的权威快照与事件分页 | taskId |
magic_agent_cancel_task |
用户明确要求停止时取消任务 | taskId、idempotencyKey |
magic_agent_get_artifact_url |
为任务产物换取短期有效的下载链接 | taskId、artifactId |
使用规则
- 续聊要带
conversationHandle：上一次结果里的 handle 原样传回；不带就是开一段全新会话，营销云看不到之前的上下文。 idempotencyKey用本次请求的可读 slug：小写单词用连字符相连、以ask-开头，例如ask-618-repurchase-crowd-product-coupon。它必须由本次请求的完整措辞推导——只按主题或日期取名会让同一活动的不同请求撞键。不要用 UUID 或随机串。返回IDEMPOTENCY_CONFLICT时在末尾追加-2、-3重试。- 不要轮询：
magic_agent_ask返回 queued / working 句柄时，告诉用户任务正在嵌入的营销云卡片里执行，然后结束本轮。卡片会自己刷新。只有用户明确追问进度、或会话里看不到卡片时，才调一次magic_agent_get_task。 - 绝不代用户作答：快照是
input_required时，停止轮询，提示用户在嵌入的营销云卡片里作答，然后结束本轮。不要替用户选项、不要替用户措辞。 - 句柄是调用管线，不是给人看的：
taskId、conversationHandle、idempotencyKey只出现在工具参数里，不要复述给用户。 - 产物链接会过期：
magic_agent_get_artifact_url返回的签名 URL 在expiresAt后失效，不要当作长期结果保存；过期后重新换一次即可。
常见错误
| 错误 | 含义 | 处理 |
|---|---|---|
HANDLE_NOT_AVAILABLE |
句柄不存在、已过保留期，或不属于当前凭证 | 用 magic_agent_ask 重新发起，不要枚举猜测句柄 |
IDEMPOTENCY_CONFLICT |
同一个 key 配了不同入参 | 文案里会带已存在的 taskId，可用它 magic_agent_get_task 找回；或换 key 重试 |
REPLAY_EXPIRED |
任务还在但精确重放数据已过期 | 重新发起请求 |
CURSOR_AHEAD |
cursor 超过了读水位 |
用更小的 cursor 重读 |
MCP_QUOTA_EXCEEDED |
签名配额超限，带 retryAfterMs |
按提示等待后重试 |
凭证失效怎么办
连接报 Invalid MCP credential.（401）、MCP business space is not authorized.（403）或 A valid X-Biz-Id header is required.（400）时，让用户在 WorkBuddy 里重新打开本连接器的配置表单，更新这两项：
- 企业密钥 SecretKey：在腾讯企点开放平台的企业密钥管理中查看或重新生成。密钥由企业管理员分配；旧密钥作废后必须回表单重填，客户端不会自动续期。
- 业务空间 ID：在营销云控制台的业务空间设置中查看。它必须属于上面密钥所属的企业，跨企业填写会稳定返回 403。
若报 MCP authentication unavailable.（503），是鉴权依赖侧暂不可用，不是凭证错误，稍后重试即可。
嵌入卡片专用工具
magic_agent_provide_input 与 magic_agent_ui_open_panel 标记为 visibility: ["app"]，只暴露给嵌入式营销云卡片，宿主模型不会、也不应调用它们。人机交互（HITL）的作答只能来自用户在卡片里的操作。