Quickstart

创建一个已发布 Agent 的 Thread，发送一条后续消息，读取公开事件日志，并附加一个文件。

开始前

你需要：

Mosoo 中一个已发布并启用 API access 的 Agent。
Agent API Access 面板中的 agentId。
一个有权限调用该 Agent 的 Mosoo API token。

export MOSOO_API_BASE="https://try.mosoo.ai/api/v1"
export MOSOO_API_TOKEN="mst_..."
export MOSOO_AGENT_ID="01J00000000000000000000001"

v1 资源 ID 是不带前缀的 ULID，不是 agent_... 或 thread_... 这类前缀 ID。

1. 创建 Thread

Thread 是已发布 Agent 的 API 对话容器。创建时带上 input 会同时排队第一个 Run。

curl -X POST "$MOSOO_API_BASE/agents/$MOSOO_AGENT_ID/threads" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-create-thread" \
  -d '{
    "client_external_ref": "quickstart-001",
    "input": {
      "type": "user.message",
      "content": [
        {
          "type": "text",
          "text": "Say hello and explain what you can help with."
        }
      ]
    }
  }'

从响应中复制 thread.id：

export MOSOO_THREAD_ID="01J00000000000000000000009"

2. 发送另一条消息

使用 thread.id 继续同一个 Agent 交互。

curl -X POST "$MOSOO_API_BASE/threads/$MOSOO_THREAD_ID/events" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-send-message-1" \
  -d '{
    "events": [
      {
        "type": "user_message",
        "clientRequestId": "quickstart-message-1",
        "text": "Give me the three most important next steps."
      }
    ]
  }'

当当前 Run 正在等待输入或仍在执行时，也可以发送 permission_decision 或 user_interrupt。

3. 读取事件日志

按时间顺序读取公开事件：

curl "$MOSOO_API_BASE/threads/$MOSOO_THREAD_ID/events?limit=100" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN"

事件日志是读取结果的稳定位置。它可能包含用户消息、Agent message delta、thinking delta、工具状态、文件变化、用量更新和 Run 状态。

4. 附加文件

先把文件上传到 Agent：

printf 'Customer asks for an implementation plan.' > brief.txt

curl -X POST "$MOSOO_API_BASE/agents/$MOSOO_AGENT_ID/files" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -F "file=@brief.txt;type=text/plain"

从响应中复制 file.id：

export MOSOO_FILE_ID="01J0000000000000000000000J"

在后续用户消息中带上这个文件：

curl -X POST "$MOSOO_API_BASE/threads/$MOSOO_THREAD_ID/events" \
  -H "Authorization: Bearer $MOSOO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: quickstart-file-message-1" \
  -d '{
    "events": [
      {
        "type": "user_message",
        "clientRequestId": "quickstart-file-message-1",
        "resources": [
          {
            "type": "file",
            "file_id": "01J0000000000000000000000J"
          }
        ],
        "text": "Summarize the attached file."
      }
    ]
  }'