事件与业务工具

事件是接入方告诉 AI 发生了什么；工具是 AI 向接入方发起查询或执行业务操作的方式。

事件

在控制台先创建、启用事件，设置标识、描述、参数及 respond／record 处理方式，再通过私聊 API推送。一般文本消息使用 type: message，不需要先创建自定义事件。

工具的三种执行方式

在控制台定义工具名称、描述、输入参数、调用条件与执行方式。送礼、查余额等名称只是业务示例，平台不会预置接入方的业务实现。

delivery	行为
["CALLBACK"]	模型调用时同步请求工具地址，拿到结果后再生成回复；查询工具只支持这种方式
["MESSAGE"]	本轮先登记计划；回复成功提交后，文本、素材、动作按顺序经消息回调投递，由接入方执行
["CALLBACK","MESSAGE"]	同步回调执行成功后，再发送展示用的动作消息；展示不能再次执行

同步地址保存在工具配置，共用当前空间 TOOL 用途的签名配置；须与已验证地址同源（协议、域名、端口相同）。仅随消息投递时不需要工具地址，但需要可用的消息回调。

同步工具请求

POST 至已配置的工具地址，事件类型为 tool.execute。OC-Event-Id 和 Idempotency-Key 为 callId。签名方式见消息回调，但使用工具回调密钥。

{
  "type": "action",
  "context": {
    "workspaceId": "1",
    "conversationId": "456",
    "personaId": "11",
    "personaUid": "anchor-001",
    "userId": "u-1001"
  },
  "action": {
    "callId": "stable-call-id",
    "code": "send_gift",
    "name": "送礼",
    "mode": "EXECUTE",
    "arguments": { "giftId": "rose", "count": 1 }
  }
}

动作字段	说明
callId	稳定工具调用 ID；用于执行幂等
code / name	配置的工具标识／名称
mode	EXECUTE 执行，NOTIFY 仅展示
arguments	按工具定义校验的业务参数
result	展示消息附带已完成的同步执行结果

执行结果

在 HTTP 2xx 中返回顶层业务结果：

{ "status": "SUCCEEDED", "data": { "giftId": "rose", "count": 1 } }

{ "status": "FAILED", "message": "余额不足" }

结果不确定时返回 {"status":"UNKNOWN","message":"请核对原交易"}。接入方需自行校验用户权限、余额等约束，并把幂等 ID 与业务结果一起持久化。

同步工具响应须在配置的 1–30 秒内完成，正文不超过 8000 UTF-8 字节。非 2xx、非法状态或超时都按未知处理。同步业务操作不会因未知结果直接自动再次执行；未知动作会限制同一会话继续调用该工具，需核对。查询工具可以重新查询。

随消息投递

使用消息回调、OC-Event-Type: chat.message：

{
  "actionId": "125",
  "conversationId": "456",
  "messageId": "791",
  "type": "action",
  "context": {
    "workspaceId": "1",
    "conversationId": "456",
    "personaId": "11",
    "personaUid": "anchor-001",
    "userId": "u-1001"
  },
  "action": {
    "callId": "stable-call-id",
    "code": "send_gift",
    "name": "送礼",
    "mode": "EXECUTE",
    "arguments": { "giftId": "rose", "count": 1 }
  }
}

EXECUTE 返回上述业务结果；重试规则遵循消息回调。NOTIFY 只用于展示已执行的结果，不能再次执行业务操作；只需可靠接收并返回 2xx，action.result 是先前同步执行结果。

控制台测试收件箱的动作会返回 simulated: true 的模拟结果，并没有真实执行。请用开放 API 与接入方系统验证完整业务流程。