Skip to main content
Sessions

Session の更新

Session の属性または既存 Session のランタイム設定を更新します。

POST /api/v1/cloud/sessions/{session_id} このエンドポイントは、作成済みの Session を更新します。title、metadata、environment_variables などの Session 最上位属性に加え、agent オブジェクトを通じてモデル、システムプロンプト、ツール、MCP server、Skill バインディングなどのランタイム設定を動的に変更できます。省略したフィールドは保持されます。
Agent の更新や新しい Agent バージョンの公開では、既存の Session は自動的に変更されません。Session は作成時にランタイム設定のスナップショットを固定します。数値バージョンに固定された Skill バインディングも、新しい Skill バージョンの公開後もそのバージョンを使い続けます。これらの変更を既存の Session に適用するには、対象の Session に対してこのエンドポイントを明示的に呼び出し、対応する agent フィールドを送信します。

パスパラメータ

パラメータ型説明
session_idstringsess_ プレフィックスを持つ Session ID

ヘッダー

ヘッダー必須説明
AuthorizationはいBearer $QODER_ACCESS_TOKEN
Content-Typeはいapplication/json
x-qoder-betaBeta Agent フィールドの更新時agent.model、agent.system、agent.skills、agent.name、agent.description を更新する場合は session-agent-patch-2026-07-21 を含めます
x-qoder-betaBrowser Use 使用時agent.tools に browser_toolset_20260714 が含まれる場合は browser-use-2026-07-14 を含めます。Browser Use（Beta） を参照
両方の Beta ID が必要な場合は、カンマ区切りで 1 つのヘッダーとして送信します。 
x-qoder-beta: session-agent-patch-2026-07-21, browser-use-2026-07-14

リクエストボディ

通常の Session 属性と agent ランタイム設定は同じリクエストで送信できます。結合更新は、行ロックを使用する 1 つのトランザクション内でまとめて成功または失敗します。
フィールド型必須説明
budgetobject | nullいいえSession の合計予算（モデルとサンドボックスの credits を含む）。例：{"type":"limit","max_credit_cost":"100.00"}。省略すると現在の設定が維持され、null を指定すると上限が解除されます。Session budget を参照。
titlestring | nullいいえ新しい Session タイトル。クリアするには null を送信します
metadataobject | nullいいえMetadata パッチ。値が null のキーは削除され、最上位の null は no-op です
environment_variablesobject | nullいいえSession から明示的に指定した環境変数マップを置き換えます。省略したキーは削除され、{} または null で Session 固有の値をクリアします。既存の Vault の環境変数認証情報は再度マージされ、Session で明示的に指定した値が優先されます。作成時の検証ルール を使用します
agentobjectいいえこの Session に埋め込まれたランタイムスナップショットを動的に更新します。オブジェクトには以下のサポート対象フィールドを 1 つ以上含める必要があります

通常の Session 属性の更新

Session 更新では version フィールドを使用しません。並行する Metadata パッチは、ロック後の最新値に対してマージされます。title または environment_variables の並行更新は last-write-wins です。 
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New title",
    "metadata": {
      "priority": "high",
      "old_key": null
    },
    "environment_variables": {
      "LOG_LEVEL": "debug"
    }
  }'

ランタイム設定の動的更新

リクエストでは agent オブジェクトを使用しますが、操作対象には skills を含むスナップショット内のすべてのサポート対象 Session ランタイム設定が含まれます。これは現在の Session の具体的な設定フィールドをパッチする操作であり、Session を別の Agent ID またはバージョンに切り替える操作ではありません。agent.id や agent.version は送信しないでください。 
Agent/設定の更新 ──> Agent バージョン N+1 ──╳──> 既存 Session スナップショット N
Skill S+1 の公開 ─────────────────────────╳──> Skill S に固定されたバインディング
                                                                │
agent フィールドを含む POST /sessions/{session_id} ────────┘
        │
        └──> 後続ターン用の更新済みランタイムスナップショット

新しく公開した Agent 設定の適用

  1. ソース Agent を更新し、新しい Agent バージョンを公開します。
  2. 必要な Agent バージョンを取得し、その設定を読み取ります。
  3. その Agent からサポート対象フィールドだけを agent パッチオブジェクトにコピーします。id、type、version、metadata、multiagent などのフィールドはここでは受け付けられないため、Agent レスポンス全体をコピーしないでください。
  4. 新しい設定を使用する各既存 Session に対して、このエンドポイントを 1 回ずつ呼び出します。
  5. 返された Session に想定した埋め込み agent が含まれることを確認し、次のターンを開始します。
更新済み Agent から新規作成された Session は、通常どおり新しい Agent バージョンを固定します。この明示的な動的更新が必要なのは、すでに存在する Session だけです。

Skill バージョンの動作

  • skills[].version が数値の場合、その Skill バージョンを固定します。新しい Skill バージョンを公開しても既存の Session には影響しません。Session を進めるには、新しい数値バージョンを指定した agent.skills を送信します。
  • version の省略、または文字列 "latest" は、sandbox 準備時に最新の Skill バージョンに動的に追従します。この場合、Skill コンテンツを進めるためだけに Session を更新する必要はありません。
  • Skill バインディングリスト自体を変更する場合、例えば Skill の追加、削除、置き換えは、既存の Session に対して常に明示的な agent.skills 更新が必要です。
動的更新により、公開済みの Agent や Skill バージョンと異なる Session 固有のランタイムスナップショットが作成されます。この操作で埋め込み agent.version は進みません。更新が反映されたかを判定するには、この値ではなく Session レスポンス内の具体的な設定フィールドを確認します。

agent 内で更新可能なフィールド

フィールド型Beta ヘッダーセマンティクス
modelstring | Agent modelsession-agent-patch-2026-07-21呼び出し元のモデルカタログで検証した後、モデル選択を置き換えます
systemstringsession-agent-patch-2026-07-21システムプロンプトを置き換えます
toolsAgent tool の配列Browser Use 以外は不要ツール設定全体を置き換えます。最大 128 件
mcp_serversMCP server の配列不要MCP server リスト全体を置き換えます。最大 20 件
skillsSkill binding の配列session-agent-patch-2026-07-21Skill バインディングリスト全体を置き換えます。最大 20 件
namestringsession-agent-patch-2026-07-21埋め込み Agent スナップショット内の名前を置き換えます
descriptionstringsession-agent-patch-2026-07-21埋め込み Agent スナップショット内の説明を置き換えます
次の Agent フィールドは、このエンドポイントから更新できません。
フィールド動作
id、version、type未知のフィールドとして拒否されます。このエンドポイントは Agent 参照によって Session を再固定しません
multiagent拒否されます。Coordinator ロスターは動的に書き込めません
Agent metadata拒否されます。Session レベルの metadata を更新するには、リクエストボディ最上位の metadata フィールドを使用します
その他の Agent フィールド無視されるのではなく拒否されます

ランタイム設定更新のセマンティクス

  • 省略した agent フィールドは現在の値を保持します。
  • tools、mcp_servers、skills は完全置換です。保持するすべてのエントリを含めるか、フィールドをクリアする場合は [] を送信します。
  • tools と mcp_servers の両方を変更する場合は、両方の完全な配列を同じリクエストで送信します。各 mcp_toolset エントリは、有効な mcp_servers リスト内の名前を参照する必要があります。
  • mcp_servers の変更、または Session に MCP server がある状態での tools 変更は、MCP discovery を再実行し、Session スナップショットに固定されたツールを更新します。
  • 単一の MCP server の discovery に失敗しても更新は拒否されません。API は引き続き 200 を返し、session.error イベントを発行します。無効なリクエスト設定や内部のスナップショット/固定失敗の場合はリクエストが拒否されます。
  • 動的ランタイム更新では楽観的並行制御を使用しません。並行する成功更新は last-write-wins です。
  • アーカイブまたは終了済みの Session は、動的ランタイム更新を受け付けません。

変更が有効になるタイミング

更新された Agent スナップショットは Session とその Coordinator thread に保存され、後続ターンで使用されます。更新前にすでにディスパッチされたターンは、従来の設定を使い続ける場合があります。明確なターン境界が必要な場合は、Session が idle になるのを待ってから更新します。

例：新しいモデル、プロンプト、Skill 設定の適用

skills は完全置換のため、Session が保持するすべての Skill バインディングを含めます。 
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-qoder-beta: session-agent-patch-2026-07-21" \
  -d '{
    "agent": {
      "model": {
        "id": "ultimate",
        "effort": "high",
        "context_window": 200000
      },
      "system": "Use the latest review policy and cite evidence for every conclusion.",
      "skills": [
        {
          "type": "custom",
          "skill_id": "skill_019e3bba474b73cfaf19eae9b5f5e66d",
          "version": "1759264410332875"
        }
      ]
    }
  }'

例：ツールと MCP server の置き換え

tools と mcp_servers に Session Agent Patch Beta ID は必要ありません。どちらの配列も完全置換です。 
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_019e3bb1e8c171fd9abbb1477ffb84cc" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "tools": [
        {
          "type": "mcp_toolset",
          "mcp_server_name": "docs"
        }
      ],
      "mcp_servers": [
        {
          "name": "docs",
          "type": "url",
          "url": "https://mcp.example.com/mcp"
        }
      ]
    }
  }'

レスポンスとイベント

HTTP 200 OK 更新後の Session オブジェクト を返します。動的なランタイム更新では、ソース Agent の version と Session スナップショットに埋め込まれた agent.version のどちらも進みません。 更新が成功すると session.updated が発行されます。イベントには常に id、type、processed_at が含まれ、更新内容に応じて title、metadata、または更新済みの完全な agent スナップショットも含まれます。環境変数の値は含まれません。environment_variables だけを変更した場合、イベントには固定フィールドだけが含まれます。完全なイベント形式は Session スキーマ を参照してください。 個別の MCP server で discovery が失敗した場合、サービスは成功した更新を保持したまま、追加で session.error を発行します。

エラー

HTTPType発生条件
400invalid_request_error不正なリクエストボディ、未知のフィールド、または無効な属性値
400invalid_request_erroragent オブジェクトにサポート対象外のフィールドが含まれる、またはモデル、ツール、MCP server、Skill、フィールド間の設定が無効
400invalid_request_errorsession-agent-patch-2026-07-21 なしで Beta Agent フィールドが送信された
400invalid_request_errorBrowser Use Beta ID なしで agent.tools に browser_toolset_20260714 が含まれた
400invalid_request_errorSession がアーカイブまたは終了済みで、リクエストがランタイム設定を更新している
401authentication_errorPAT または SAT が無効か期限切れ
404not_found_errorSession が存在しない、または通常属性の更新対象 Session がアーカイブ済み
409invalid_request_error更新のコミット中に Session が並行してアーカイブされた
500api_error既存の Vault 環境変数認証情報を安全に解決できなかった
503feature_not_availableBrowser Use が一時的に利用できない
503api_errorモデルカタログまたはその他の必須依存先が一時的に利用できない
完全なエラーエンベロープについては Errors を参照してください。

関連項目

Session の起動

Agent を環境で実行し、ステートフルな対話を行う。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス