跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

本文演示如何通过 curl 完成 Qoder Cloud Agents 的完整工作流：创建 Agent → 启动 Session → 发消息 → 接收事件流。

​
环境准备

# 设置个人访问令牌
export QODER_PAT="pt-your-token-here"

# API 基础地址
export BASE_URL="https://openapi.qoder.sh/api/v1/cloud"
PAT 在 Qoder 控制台 → 个人设置 → 访问令牌 中生成。详见 认证。

​
公共 Header 模板

所有请求均需携带以下头部： 
-H "Authorization: Bearer $QODER_PAT"
-H "Content-Type: application/json"

​
第 1 步：创建 Agent

AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-assistant",
    "model": "ultimate",
    "system": "你是一个高效的编程助手，回复简洁清晰。"
  }' | jq -r '.id')

echo "Agent ID: $AGENT_ID"

​
第 2 步：获取 Environment

# 列出可用环境，取第一个
ENV_ID=$(curl -s "$BASE_URL/environments?limit=1" \
  -H "Authorization: Bearer $QODER_PAT" | jq -r '.data[0].id')

echo "Environment ID: $ENV_ID"

​
第 3 步：启动 Session

SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent\": \"$AGENT_ID\",
    \"environment_id\": \"$ENV_ID\",
    \"title\": \"curl 测试会话\"
  }" | jq -r '.id')

echo "Session ID: $SESSION_ID"

​
第 4 步：发送消息

curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": "用 Python 写一个快速排序函数"
      }
    ]
  }' | jq .

​
第 5 步：接收 SSE 事件流

curl -N "$BASE_URL/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"
输出格式（每个事件以空行分隔）： 
id: evt_019e392c0d787cfaa21bda98e06cd913
event: user.message
data: {"id":"evt_019e392c...","type":"user.message","content":"用 Python 写一个快速排序函数",...}

id: evt_771c1195bcbd4a07834d4ed4dd6450ca
event: session.status_rescheduled
data: {"id":"evt_771c1195...","type":"session.status_rescheduled",...}

id: evt_f8599c68e7784f2d8c490af1b3056716
event: agent.message
data: {"id":"evt_f8599c68...","type":"agent.message","content":[{"type":"text","text":"..."}],...}

id: evt_a289470296c94e7ba8d7ea562efe5925
event: session.status_idle
data: {"id":"evt_a28947...","type":"session.status_idle","stop_reason":{"type":"end_turn"},...}
-N 参数禁用 curl 的输出缓冲，确保 SSE 数据实时显示。

​
断点续传

如果连接中断，使用 after_id 参数从上次收到的事件之后继续： 
LAST_EVT_ID="evt_a289470296c94e7ba8d7ea562efe5925"

curl -N "$BASE_URL/sessions/$SESSION_ID/events/stream?after_id=$LAST_EVT_ID" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"

​
轮询事件列表（替代 SSE）

如果环境不支持长连接，可使用列表接口轮询： 
curl -s "$BASE_URL/sessions/$SESSION_ID/events?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

​
完整一键脚本

将以上步骤合并为可直接执行的脚本： 
#!/usr/bin/env bash
set -euo pipefail

BASE_URL="https://openapi.qoder.sh/api/v1/cloud"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
  -H "Content-Type: application/json"
)

# 创建 Agent
AGENT_ID=$(curl -s -X POST "$BASE_URL/agents" "${HEADERS[@]}" \
  -d '{"name":"quick-test","model":"ultimate","system":"你是助手"}' | jq -r '.id')
echo "Agent: $AGENT_ID"

# 获取环境
ENV_ID=$(curl -s "$BASE_URL/environments?limit=1" "${HEADERS[@]}" | jq -r '.data[0].id')
echo "Environment: $ENV_ID"

# 创建 Session
SESSION_ID=$(curl -s -X POST "$BASE_URL/sessions" "${HEADERS[@]}" \
  -d "{\"agent\":\"$AGENT_ID\",\"environment_id\":\"$ENV_ID\"}" | jq -r '.id')
echo "Session: $SESSION_ID"

# 发送消息
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" "${HEADERS[@]}" \
  -d '{"events":[{"type":"user.message","content":"Hello!"}]}' > /dev/null
echo "消息已发送"

# 接收事件流
echo "--- 事件流 ---"
curl -N "$BASE_URL/sessions/$SESSION_ID/events/stream" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Accept: text/event-stream"