セッション

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

Session のライフサイクル

作成 → idle

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

idle → processing

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

processing → idle

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

cancelled / archived（終端状態）

キャンセルとアーカイブはどちらも終端状態で、Session は再開できません。

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

状態	説明	遷移先
`idle`	アイドル、ユーザーメッセージ待ち	`processing`, `cancelled`
`processing`	処理中、Agent 実行中	`idle`, `cancelled`
`cancelled`	キャンセル済み、実行終了	— (終端状態)

フィールド説明

フィールド	型	説明
`id`	string	システム生成、`ses_` プレフィックス
`agent_id`	string	バインドした Agent ID
`environment_id`	string	バインドした Environment ID
`status`	string	現在の状態: `idle` / `processing` / `cancelled`
`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://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "ag_r4nD0mId123",
    "environment_id": "env_default"
  }' | jq .

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

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

# Agent バージョンを指定して Session を作成
curl -s -X POST https://openapi.qoder.sh/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "id": "ag_r4nD0mId123",
      "version": 2
    },
    "environment_id": "env_default"
  }' | jq .

成功時は 201 Created:

{
  "id": "ses_newSession456",
  "agent_id": "ag_r4nD0mId123",
  "environment_id": "env_default",
  "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 フィールドの形式

形式	例	挙動
文字列	`"ag_r4nD0mId123"`	その Agent の最新バージョンを使用
オブジェクト	`{"id": "ag_r4nD0mId123", "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://openapi.qoder.sh/api/v1/cloud/sessions/ses_newSession456/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://openapi.qoder.sh/api/v1/cloud/sessions/ses_newSession456/cancel" \
  -H "Authorization: Bearer $QODER_PAT"

キャンセルは終端操作です。キャンセルされた Session は復帰できず、新しい Session を作成する必要があります。

Session を取得する

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

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

ページングレスポンス:

{
  "data": [
    {
      "id": "ses_newSession456",
      "agent_id": "ag_r4nD0mId123",
      "environment_id": "env_default",
      "status": "idle",
      "usage": {
        "input_tokens": 1520,
        "output_tokens": 834
      }
    }
  ],
  "first_id": "ses_newSession456",
  "last_id": "ses_newSession456",
  "has_more": false
}

Usage 統計

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

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

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

{
  "input_tokens": 3840,
  "output_tokens": 2156
}

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

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

文字列形式 "agent": "ag_xxx" は作成時点の最新バージョンにバインド
オブジェクト形式 "agent": {"id": "ag_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://openapi.qoder.sh/api/v1/cloud"
SESSION_ID="ses_newSession456"
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 構成を追加してください。"}]}]}'

ベストプラクティス

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

よくある質問

Q: Session にタイムアウトはありますか? A: idle 状態で一定時間保持されます。長時間アクティブでない Session はシステムによって自動でアーカイブされる可能性があります。必要時に作成し、タスク完了後は自発的に cancel することを推奨します。 Q: processing 状態の Session にメッセージを送るとどうなりますか? A: エラーが返ります。Session が idle に戻ってからでないと、新しいメッセージを送信できません。 Q: 1 つの Session で何ターン対話できますか? A: ハードなターン上限はありませんが、モデルのコンテキストウィンドウサイズに制約されます。対話が長くなると、初期の内容が切り捨てられる場合があります。 Q: Session の完全な対話履歴を取得するには? A: GET /sessions/{id}/events でその Session のすべてのイベント (ユーザーメッセージと Agent 応答を含む) を取得できます。 Q: cancelled 状態から復帰できますか? A: できません。cancelled は終端状態のため、新しい Session を作成して継続する必要があります。コンテキストを保持したい場合は、新しい Session の最初のメッセージに必要な背景情報を含めてください。

次のステップ

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

クイックスタート

ユーザーガイド

SDK

Cloud Agents

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 にバインド

マルチターン対話

ベストプラクティス

よくある質問

次のステップ

クイックスタート

ユーザーガイド

SDK

Cloud Agents

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 バージョンのバインド

マルチターン対話

ベストプラクティス

よくある質問

次のステップ