AgentKit Studio文档

个人助理预发控制面缺口(2026-10-28 更新)

Studio 侧已实现「零配置」:Host 用云账号凭据发现个人助理实例、复用已有 AK、失效时自动重新获取, 插件页面不再需要填网关/实例/AK。真实链路已验证:发现实例 → 网关签发 43 字符短时票据 → wss 握手成功。

下面两个缺口都在平台控制面,不是 Studio/插件代码问题;线上接口正常时 Studio 代码路径无需改动。

1. CreateAgentApiKey 经 AICP 一律 500(平台 manager 本身是好的)

结论:AICP 前置 action API 的 key 通道坏了,请求没有转发到 agentengine manager。

证据:

  1. 同一 action、同一 body 直接打预发平台 manager:

    # 在 agentengine pod 内
    POST http://agentengine:8081/agentengine/api/v1/CreateAgentApiKey
    # -> {"Code":0,...,"Data":{"api_key":"ak-...","key_id":"key-..."}}
    POST http://agentengine-dev:8081/agentengine/api/v1/CreateAgentApiKey
    # -> 同样 Code:0,并真实落库
    

    agentengine 与 agentengine-dev 两个部署都成功,任意 Agent、带不带 X-Ksc-Account-Id 都成功。

  2. 经 http://aicp.inner.api.ksyun.com/?Action=CreateAgentApiKey 调用时,在 agentengine 全部 20 个 Pod 上按 request id/Action 抓日志,没有任何对应请求; 而同一时段 ListAgents 等 action 正常返回。说明失败发生在 AICP 内部,未到达 manager。

  3. AICP 侧 ListAgentApiKeys 对同一实例返回 Keys: [],而数据库/网关里实际存在有效 key, 说明 AICP 这组 key 接口连到的后端或存储与平台 manager 不是同一份数据。

  4. 预发部署镜像本身存在 key 模块版本错位:直接调用 manager 的 DeleteAgentApiKey 会得到

    AttributeError: 'KeyService' object has no attribute 'delete_key'
    

    并被统一翻译成 {"Code":500,...}。AICP 后面那份部署很可能有同类问题 (例如 api_keys 表 schema 漂移导致插入异常),需要 AICP 侧日志确认。

复现请求 id:24649aa3-08a5-40fc-956b-5a7a13746728(CreateAgentApiKey 500)。

2. CreateAgent 对个人助理 Framework 返回 422,但仍会异步落一个 FAILED 实例

  • Framework=personal-assistant → 422 Framework 格式不正确;
  • Framework=harness(对照)→ 400 ManagedRuntimeConfig.RuntimeName 必须与 Framework 一致;
  • 更糟的是:被 422 拒绝的请求仍会创建一个 FAILED 状态的 Agent(实测两个探针实例), 需要在控制面清理(本次已删除)。

影响:没有实例的子账号在插件里点「创建个人助理」会得到明确提示,而不是静默失败; 线上 Framework/运行时注册正常时该路径可用。

复现

node /tmp/aicp-compare.mjs          # AICP: ListAgentApiKeys=[] / CreateAgentApiKey=500
node /tmp/forward-proof.sh          # manager pod 上抓不到 AICP 的 key 请求
node /tmp/live-ticket-ws.mjs        # 用已恢复 AK 出票并 wss 握手:{"open":true}