跳转到主要内容

​
基于已发布 Mosoo Agent 开发

Mosoo API 用于在你的应用中调用已发布的 Mosoo Agent。你的应用提供调用方 token 和已发布 Agent 的 agentId；Mosoo 会创建 Thread、启动 Agent，并向 API 调用方开放这个 Thread 的公开事件和文件。 这就是 Agent 发布菜单里 API 接入（API Access） 入口对应的集成能力。
API 只适用于已发布的 Agent。Agent 配置、模型服务商连接和渠道绑定都需要先在 Mosoo 中完成。

发布 Agent

在 Mosoo 中配置 Agent，连接模型服务商，并发布它以获得 agentId。

创建调用方 token

个人调用时使用 Human PAT；
团队服务端任务可使用 Organization Service token。

创建 Thread

使用 API 创建 Thread，然后继续发送事件、附加文件并读取结果。

​
第一个请求

把 access token 和 Agent ID 组合起来，就可以创建 Thread。 
curl -X POST "https://mosoo.ai/api/v1/agents/$MOSOO_AGENT_ID/threads" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-182-create-thread" \
  -d '{
    "client_external_ref": "ticket-182",
    "input": {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Triage this customer escalation and suggest next steps."
        }
      ]
    }
  }'
响应里会包含 thread.id 和第一个 run。后续发送消息、读取事件、附加文件和管理生命周期都使用这个 Thread ID。

查看完整快速开始

设置环境变量，创建 Thread，发送下一条用户消息，并读取事件日志。

​
核心概念

已发布 Agent

可以被 API 调用的 Agent。在 Agent 发布后的 API 接入面板中获取它的 agentId。

调用方 token

Human PAT 或 Organization Service token。token 标识调用方身份。

Thread

API 创建的对话容器。Thread 记录消息、文件、运行状态、归因和生命周期状态。

事件

面向 API 调用者的稳定公开日志。你可以发送用户消息或权限决策，再从 Thread 事件列表读取 Agent 可见结果。

​
可以用来做什么

当你希望把已发布的 Agent 接入自己的产品或工作流时：
  • 当工单、订单、告警或任务出现时，从你的后端启动 Agent。
  • 在 Service token 被允许时，通过 attributed_user_id 把工作归因到某个用户。
  • 在运行前或运行过程中给 Thread 附加文件。
  • 轮询公开事件日志，读取 Agent 消息、工具状态、文件变化、用量更新和运行完成状态。
  • 使用 client_external_ref 和 Idempotency-Key 让外部系统与 Mosoo 保持一致。

​
API 能力范围

创建和列出 Threads

POST /agents/{agentId}/threads 创建 Thread 和初始运行。GET /agents/{agentId}/threads 列出调用方可见的 Threads。

发送和读取事件

POST /threads/{threadId}/events 发送用户消息、权限决策或中断。GET /threads/{threadId}/events 读取公开事件日志。

附加文件

添加、列出和移除 Thread 文件。API 添加的文件是附件；Agent 生成的文件会作为产物文件返回。

管理生命周期

当集成不再需要 Thread 保持活跃时，可以读取、归档、恢复或删除 Thread。

​
访问模型

每个请求都会同时校验已发布 Agent 和调用方 token：
  • Agent 必须存在、已发布，并启用 API 接入。
  • 调用方 token 必须有效且未被撤销。
  • 使用 Human PAT 的调用方仍需通过组织成员和 Agent 访问检查。
  • Organization Service token 必须被显式允许调用指定的已发布 Agent。
  • 运行时会使用已发布 Agent 所有者配置的能力边界。

理解 token 和访问控制

了解 Human PAT、Organization Service token、Agent 访问路径、归因和所有者配置如何配合。