AI Coding Assistant Lingma:セッションの開始

セッションのライフサイクル

1. Create → idle

   新しいセッションは idle 状態に入り、入力を待機します。

2. idle → processing

   user.message イベントを送信すると、ステータスは processing に変わります。

3. processing → idle

   現在のターンが完了すると、セッションは idle 状態に戻り、次のターンに備えます。

4. processing → canceling → idle

   実行中のセッションをキャンセルすると、ステータスは canceling に遷移し、その後 idle に戻ります。セッションは引き続き利用可能です。

5. archived (終端状態)

   archived ステータスは終端状態です。アーカイブ済みのセッションは復元できません。

セッションは、次のコアステータスを持つステートマシンです。

フィールドの説明

セッションの作成

セッションを作成する際は、agent と environment_id を指定する必要があります。

エージェントID (文字列) の使用

この方法では、セッションをエージェントの最新バージョンにバインドします。

# エージェントIDを使用してセッションを作成します
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

エージェントオブジェクト (バージョン指定) の使用

この方法では、セッションをエージェントの特定バージョンにバインドし、動作の一貫性を確保します。

# エージェントのバージョンを指定してセッションを作成します
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "version": 2
    },
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

リクエストが成功すると、201 Created レスポンスが返されます。

{
  "id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "agent": {
    "created_at": "2026-05-18T10:00:00Z",
    "default_environment": "",
    "description": "",
    "id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "instructions": "You are a code review expert.",
    "mcp_servers": [],
    "model": "ultimate",
    "name": "code-reviewer",
    "system": "You are a code review expert.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "type": "agent",
    "updated_at": "2026-05-18T10:00:00Z",
    "version": 2
  },
  "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": "",
  "turn_status": "idle",
  "memory_store_ids": [],
  "resources": [],
  "vault_ids": [],
  "type": "session",
  "created_at": "2026-05-18T12:00:00Z",
  "updated_at": "2026-05-18T12:00:00Z"
}

本番環境では、エージェントの更新による予期しない動作変更を防ぐため、2 つ目の方法 (バージョン指定) の利用を推奨します。

agent フィールドの形式

状態遷移

イベントリクエストのボディ形式

POST /sessions/{id}/events のリクエストボディは、events 配列を含むオブジェクトである必要があります。配列内の各イベントには content フィールドがあり、これはコンテンツブロックの配列です。

idle → processing

セッションに user.message イベントを送信すると、ステータスは idle から processing に変わります。

# メッセージを送信して処理を開始します
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [{
      "type": "user.message",
      "content": [{"type": "text", "text": "Analyze the code complexity of all Python files in the current directory."}]
    }]
  }' | jq .

processing → idle

エージェントが処理を完了すると、セッションは自動的に idle 状態に戻ります。イベントストリームを通じて session.status_idle イベントを受信します。

セッションのキャンセル

実行中のセッションを中断できます。

# セッションをキャンセルします
curl -s -X POST "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/cancel" \
  -H "Authorization: Bearer $QODER_PAT"

セッションの取得

# 単一のセッションを取得します
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522" \
  -H "Authorization: Bearer $QODER_PAT"

# すべてのセッションを一覧表示します (ページネーションあり)
curl -s "https://api.qoder.com.cn/api/v1/cloud/sessions?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

以下は、ページネーションされたレスポンスの例です。

{
  "data": [
    {
      "id": "sess_019e5ce0bf9074b69c3481e93771a522",
      "type": "session",
      "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "status": "idle",
      "turn_status": "idle",
      "title": "",
      "memory_store_ids": [],
      "vault_ids": [],
      "resources": [],
      "created_at": "2026-05-18T12:00:00Z",
      "updated_at": "2026-05-18T12:30:00Z"
    }
  ],
  "first_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "last_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "has_more": false
}

トークン使用量

各ターンのトークン使用量は、REST API では返されません。使用量を確認するには、各ターンの末尾で送信される session.status_idle SSE イベントをリッスンしてください。このイベントの usage フィールドに、そのターン固有のトークン数が含まれます。

以下は、SSE イベントのペイロード例です。

{
  "type": "session.status_idle",
  "usage": {
    "input_tokens": 3840,
    "output_tokens": 2156,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0
  }
}

セッションとエージェントバージョンのバインド

セッションを作成すると、エージェント設定のスナップショットが取得されます。

• 文字列形式 "agent": "agent_xxx" を使用すると、作成時点でのエージェントの最新バージョンにバインドされます。

• オブジェクト形式 "agent": {"id": "agent_xxx", "version": N} を使用すると、特定バージョンにバインドされます。

• セッション作成後にエージェントを変更しても、そのセッションには影響しません。

• エージェントの新しいバージョンを使用するには、新しいセッションを作成する必要があります。

マルチターン会話

セッションはマルチターン会話をサポートします。メッセージ送信後、session.status_idle イベントを待ってから、次のメッセージを送信できます。

#!/bin/bash
# マルチターン会話の例
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
SESSION_ID="sess_019e5ce0bf9074b69c3481e93771a522"
HEADERS=(
  -H "Authorization: Bearer $QODER_PAT"
)

# ターン 1：初回リクエストを実行
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Create a Python Flask project scaffold."}]}]}'

# 処理の完了を待機... (ポーリングまたは SSE をリッスン)
sleep 30

# ターン 2：追加要件を送信
curl -s -X POST "$BASE_URL/sessions/$SESSION_ID/events" \
  "${HEADERS[@]}" \
  -H "Content-Type: application/json" \
  -d '{"events": [{"type": "user.message", "content": [{"type": "text", "text": "Add unit tests and a CI configuration to the project."}]}]}'

ステータス関連のエラーコード

以下は、セッションにイベントを送信する際に発生しやすいステータス関連のエラーです。

以下は、409 エラーレスポンスの例です。

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Session is currently processing a turn. Cancel the current turn or wait for completion."
  }
}

ベストプラクティス

1. バージョン固定：本番環境では常に {"id": ..., "version": ...} 形式を使用してセッションを作成してください。

2. 適時のキャンセル：不要なセッションはキャンセルしてリソースを解放してください。

3. 使用量の監視：想定外のコストを避けるため、usage フィールドを定期的に確認してください。

4. メタデータによるタグ付け — metadata フィールドを使用して、タスク ID やトリガーソースなどの業務コンテキストを記録します。

よくある質問

Q：セッションにタイムアウト機構はありますか？

A：idle 状態のセッションは一定期間保持されます。長時間操作がないセッションは、システムにより自動的にアーカイブされる場合があります。必要に応じてセッションを作成し、タスク完了後はキャンセルすることを推奨します。

Q：processing 状態のセッションにメッセージを送信するとどうなりますか？

A：API は Session is currently processing a turn. Cancel the current turn or wait for completion. というメッセージと共に HTTP 409 conflict_error を返します。新しいメッセージを送信する前に、現在のターンをキャンセルするか、セッションが idle 状態に戻るまで待つ必要があります。

Q：セッションがサポートする最大ターン数はいくつですか？

A：ターン数にハードリミットはありません。ただし、モデルのコンテキストウィンドウのサイズが実用上の上限になります。会話が長くなると、以前の内容が切り捨てられる場合があります。

Q：セッションの完全な会話履歴を取得するにはどうすればよいですか？

A: GET /sessions/{id}/events 操作を呼び出して、ユーザーメッセージやエージェントの応答など、セッションのすべてのイベントを取得します。

Q：キャンセルしたセッションは再利用できますか？

A：はい。セッションをキャンセルすると、ステータスは canceling から idle に自動的に遷移し、セッションは引き続き利用可能です。次の user.message を送信して会話を続行できます。終端状態は archived のみです。アーカイブ済みのセッションは復元できません。