セッション - Qoder

Session は Qoder Cloud Agents で実際にタスクを実行する単位です。Agent (構成) と Environment (インフラ) を組み合わせ、ステートフルなワークセッションを形成します。Session にメッセージを送ると、処理結果がイベントストリームとして返されます。

Session のライフサイクル

作成 → idle

新しい Session は idle で開始し、入力を待ちます。

idle → processing

user.message イベントを送信すると、状態が processing に遷移します。

processing → idle

現在のターンが完了すると idle に戻り、次のターンへ進めます。

processing → canceling → idle

実行中の Session をキャンセルすると、状態は canceling を経由してから idle に戻り、Session は引き続き再利用できます。

archived（終端状態）

アーカイブは終端状態で、Session は再開できません。

Session はステートマシンで、コアな状態は次のとおりです。

状態	説明	遷移先
`idle`	アイドル、ユーザーメッセージ待ち	`processing`
`processing`	処理中、Agent 実行中	`canceling`, `idle`
`canceling`	キャンセル指令を発行済み、中断完了待ち	`idle`
`archived`	アーカイブ済み	— (終端状態)

フィールド説明

フィールド	型	説明
`id`	string	システム生成、`sess_` プレフィックス
`agent`	string/object	Session 作成時に渡した Agent 参照（文字列またはバージョン指定オブジェクト）
`agent_id`	string	レスポンス専用の互換フィールド。バインドした Agent ID
`environment_id`	string	バインドした Environment ID
`status`	string	現在の状態: `idle` / `processing` / `canceling`
`title`	string/null	セッションタイトル。空でも可
`metadata`	object	カスタム key-value
`usage`	object	トークン使用量の累計
`usage.input_tokens`	integer	累計入力トークン数
`usage.output_tokens`	integer	累計出力トークン数
`created_at`	string	作成時刻
`updated_at`	string	最終更新時刻

Session を作成する

Session 作成時は agent と environment_id を指定する必要があります。

方式 1: Agent ID (文字列) を使用

その Agent の最新バージョンにバインドします。

# Agent ID で Session を作成
curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
    "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428"
  }' | jq .

方式 2: Agent オブジェクト (バージョン指定) を使用

Agent の特定バージョンにバインドし、挙動の一貫性を保証します。

# Agent バージョンを指定して Session を作成
curl -s -X POST https://api.qoder.com/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_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
  "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "status": "idle",
  "title": null,
  "metadata": {},
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  },
  "created_at": "2026-05-18T12:00:00Z",
  "updated_at": "2026-05-18T12:00:00Z"
}

本番環境では方式 2 (バージョン指定) を推奨します。Agent の更新による挙動変化を回避できます。

agent フィールドの形式

形式	例	挙動
文字列	`"agent_019e5ce0bf307a1a8f952eb814aea3d5"`	その Agent の最新バージョンを使用
オブジェクト	`{"id": "agent_019e5ce0bf307a1a8f952eb814aea3d5", "version": 2}`	指定バージョンに固定

状態遷移

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

POST /sessions/{id}/events のリクエストボディは events 配列でラップする必要があり、content はコンテンツブロックの配列です。

フィールド	型	必須	説明
`events`	array	はい	イベント配列。1 リクエストで 1 件以上のイベントを送信可能
`events[].type`	string	はい	イベントタイプ（例: `user.message`）
`events[].content`	array	はい	コンテンツブロック配列
`events[].content[].type`	string	はい	コンテンツブロックタイプ（例: `text`）
`events[].content[].text`	string	はい	テキスト内容

idle → processing

Session に user.message イベントを送信すると、状態が idle から processing に変わります。

# メッセージ送信で処理を開始
curl -s -X POST "https://api.qoder.com/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": "現在のディレクトリ配下のすべての Python ファイルのコード複雑度を分析してください。"}]
    }]
  }' | jq .

processing → idle

Agent が処理を完了すると自動で idle に戻り、イベントストリームに session.status_idle イベントが配信されます。

Session をキャンセル

実行中の Session を中断します。

# Session をキャンセル
curl -s -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522/cancel" \
  -H "Authorization: Bearer $QODER_PAT"

processing 状態のときに cancel を呼び出した場合のみ実際に中断されます：状態はまず canceling になり、中断完了後に idle に戻ります。Session は引き続き再利用可能です——次の user.message をそのまま送信できます。すでに idle の Session に対する cancel は no-op で、同じく 200 を返し、エラーにはならず、状態は idle のまま維持されます。

Session を取得する

# 単一 Session の詳細を取得
curl -s "https://api.qoder.com/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522" \
  -H "Authorization: Bearer $QODER_PAT"

# すべての Session を一覧表示 (ページング対応)
curl -s "https://api.qoder.com/api/v1/cloud/sessions?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

ページングレスポンス:

{
  "data": [
    {
      "id": "sess_019e5ce0bf9074b69c3481e93771a522",
      "agent_id": "agent_019e5ce0bf307a1a8f952eb814aea3d5",
      "environment_id": "env_019e44eb66bb748cabcd1489f6fa4428",
      "status": "idle",
      "usage": {
        "input_tokens": 1520,
        "output_tokens": 834
      }
    }
  ],
  "first_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "last_id": "sess_019e5ce0bf9074b69c3481e93771a522",
  "has_more": false
}

Usage 統計

各 Session は累計のトークン使用量を保持します。

フィールド	説明
`usage.input_tokens`	すべてのリクエストの入力トークン総数
`usage.output_tokens`	すべてのレスポンスの出力トークン総数

# Session の使用量を確認
curl -s "https://api.qoder.com/api/v1/cloud/sessions/sess_019e5ce0bf9074b69c3481e93771a522" \
  -H "Authorization: Bearer $QODER_PAT"

{
  "usage": {
    "input_tokens": 3840,
    "output_tokens": 2156,
    "cache_read_input_tokens": 1200,
    "cache_creation_input_tokens": 0
  }
}

Session と Agent バージョンのバインド

Session は作成時に Agent 構成のスナップショットを保持します。

文字列形式 "agent": "agent_xxx" は作成時点の最新バージョンにバインド
オブジェクト形式 "agent": {"id": "agent_xxx", "version": N} は精密にバージョン指定
Session 作成後、Agent を変更しても既存の Session には影響しません
新バージョンの Agent を使うには、新しい Session を作成する必要があります

Session A — Agent v1 にバインド

更新前に作成された Session。Agent が後で v2 に更新されても、Session A は引き続き v1 構成を使用します。

Session B — Agent v2 にバインド

更新後に作成された Session。新しい v2 構成を使用します。

マルチターン対話

Session はマルチターン対話をサポートします。各メッセージ送信後に session.status_idle を待ち、続けて次を送信します。

#!/bin/bash
# マルチターン対話の例
BASE_URL="https://api.qoder.com/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": "Python Flask プロジェクトのスキャフォールドを作成してください。"}]}]}'

# 処理完了を待つ... (ポーリングまたは 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": "プロジェクトに単体テストと CI 構成を追加してください。"}]}]}'

状態関連のエラーコード

Session にイベントを送信する際の、状態関連の代表的なエラー：

HTTP	type	発生条件
409	`conflict_error`	`processing` 状態の Session にメッセージを送信した場合（先に現在のターンを cancel するか、`idle` に戻るのを待つ必要があります）
404	`not_found_error`	Session が存在しないか、削除済み

409 エラーレスポンス例：

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

ベストプラクティス

バージョン固定 — 本番環境では常に {"id": ..., "version": ...} 形式で Session を作成
早めにキャンセル — 不要になった Session はすぐ cancel し、リソースを解放
使用量を監視 — usage フィールドを定期確認し、想定外の消費を防ぐ
メタデータでタグ付け — metadata で業務コンテキスト (タスク ID、トリガー元など) を記録

よくある質問

Q: Session にタイムアウトはありますか? A: idle 状態で一定時間保持されます。長時間アクティブでない Session はシステムによって自動でアーカイブされる可能性があります。必要時に作成し、タスク完了後は自発的に cancel することを推奨します。 Q: processing 状態の Session にメッセージを送るとどうなりますか? A: HTTP 409 conflict_error が返り、エラーメッセージは Session is currently processing a turn. Cancel the current turn or wait for completion. です。先に現在のターンを cancel するか、Session が idle に戻るのを待ってから新しいメッセージを送信してください。 Q: 1 つの Session で何ターン対話できますか? A: ハードなターン上限はありませんが、モデルのコンテキストウィンドウサイズに制約されます。対話が長くなると、初期の内容が切り捨てられる場合があります。 Q: Session の完全な対話履歴を取得するには? A: GET /sessions/{id}/events でその Session のすべてのイベント (ユーザーメッセージと Agent 応答を含む) を取得できます。 Q: キャンセルした Session を引き続き使えますか? A: 使えます。cancel 後、状態は canceling から自動的に idle に戻り、Session はそのまま利用可能です——次の user.message を送信して対話を継続できます。終端状態は archived のみで、アーカイブされた Session は復帰できません。

次のステップ

概要 — Cloud Agents 全体アーキテクチャを再確認
クイックスタート — エンドツーエンドの完全な例
Agent の定義 — Agent 構成を深掘り
クラウド環境 — 実行環境のカスタマイズ

Documentation Index

​Session のライフサイクル

​フィールド説明

​Session を作成する

​方式 1: Agent ID (文字列) を使用

​方式 2: Agent オブジェクト (バージョン指定) を使用

​agent フィールドの形式

​状態遷移

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

​idle → processing

​processing → idle

​Session をキャンセル

​Session を取得する

​Usage 統計

​Session と Agent バージョンのバインド

Session A — Agent v1 にバインド

Session B — Agent v2 にバインド

​マルチターン対話

​状態関連のエラーコード

​ベストプラクティス

​よくある質問

​次のステップ

Session のライフサイクル

フィールド説明

Session を作成する

方式 1: Agent ID (文字列) を使用

方式 2: Agent オブジェクト (バージョン指定) を使用

agent フィールドの形式

状態遷移

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

idle → processing

processing → idle

Session をキャンセル

Session を取得する

Usage 統計

Session と Agent バージョンのバインド

マルチターン対話

状態関連のエラーコード

ベストプラクティス

よくある質問

次のステップ