Skip to main content
基本概念

動作の仕組み

どちらの SDK も、ローカルの qodercli プロセスで Agent を実行します。SDK と qodercli は JSONL でメッセージと制御リクエストを交換し、qodercli がモデルサービスの呼び出しと承認済みツールの実行を担当します。

アーキテクチャ

+---------------------- アプリケーション ---------------------------+
|  TypeScript query()                 Python query() / SDK Client   |
|                  メッセージ解析、コールバック、セッション制御       |
+-------------------------------+-----------------------------------+
                                |
                  ローカル stdin/stdout JSONL
                                |
+-------------------------------v-----------------------------------+
|                        qodercli SDK モード                         |
|  プロトコル + セッション -> Agent ループ -> 権限 + ツール実行       |
+--------------------------+----------------------+------------------+
                           |                      |
                       モデルリクエスト          ローカル実行
                           |                ファイル / コマンド / MCP
                           v                      |
                   Qoder モデルサービス           |
                           |                      |
                           +------ 実行結果 -------+
1 つのローカルランタイムセッションは、1 つの qodercli プロセスが保持します。文字列を渡す query() は通常、最終結果の後にセッションを閉じます。複数ターン API は、アプリケーションが追加入力を送る間、セッションを維持します。

起動とハンドシェイク

デフォルトのローカルセッションは、次の順序で起動します。
  1. ランタイムを選択する。 qodercli のパスが明示されている場合はそのパスを使用します。それ以外の場合は、パッケージに同梱された互換ランタイムまたは環境内のランタイムを探します。
  2. SDK モードで起動する。 SDK は構造化ストリーミング入出力を有効にして qodercli を起動します。プロセスには設定された作業ディレクトリと環境が適用されます。
  3. 認証情報を渡す。 SDK は選択された認証方式を解決し、メッセージストリームへ認証情報を書き込まず、一時的な 1 回限りの認証ペイロードで qodercli へ渡します。
  4. 機能を初期化する。 最初のタスクを送る前に、SDK と qodercli は initialize 制御リクエストを交換します。この段階で SDK 側の Hooks、Agent、Skills、プロセス内 MCP サーバーを登録し、qodercli はランタイム機能と利用可能なリソースを返します。
  5. タスクを送信する。 初期化が成功すると、SDK は最初のユーザーメッセージを送信し、qodercli のメッセージをアプリケーションへ返し始めます。
初期化エラーはタスクの実行前に報告されるため、設定や認証の問題と Agent 実行の失敗を区別できます。

SDK と qodercli の通信

デフォルトのプロセス Transport では、1 行につき 1 つの JSON プロトコルオブジェクトを送ります。SDK が JSON Lines（JSONL）ストリームを読み書きするため、アプリケーションはプロセス出力を直接解析せず、型付き SDK メッセージを使用してください。 
アプリケーション
    |
    | SDK が qodercli stdin へ書き込む
    |   ユーザーメッセージ
    |   制御リクエストと対応する制御レスポンス
    v
 qodercli
    |
    | qodercli が stdout へ書き込む
    |   system、assistant、task、hook、result メッセージ
    |   有効な場合は増分 stream event
    |   制御リクエストと対応する制御レスポンス
    v
 SDK メッセージイテレーター

 qodercli stderr --------------------> 診断情報（プロトコルデータではない）
プロトコルの通信には 2 つの種類があります。
  • Agent メッセージは、ユーザー入力、Agent の内容、ツールの動作、進捗、最終結果を運びます。
  • 制御メッセージは、初期化、中断、セッション操作、権限判断、Hooks、プロセス内 MCP 呼び出しを処理します。request_id が各レスポンスをリクエストに対応付けるため、複数の処理が進行中でも結果を区別できます。
制御リクエストはどちら側からも開始できます。SDK は qodercli に現在のターンの中断を要求し、qodercli はアプリケーションにツールの承認や SDK 側 Hook の実行を要求します。SDK は受信したリクエストを設定済みコールバックへ送り、その結果を qodercli へ返します。

qodercli の Agent ループ

qodercli は、タスクが完了するか設定された上限に達するまでモデルを繰り返し呼び出します。前の反復で得たツール結果は、次のモデルリクエストのコンテキストになります。 
ユーザータスク + 会話履歴 + 指示 + ツール定義
                    |
                    v
          次のモデルリクエストを構築
                    |
                    v
             モデル出力をストリーム
                    |
             +------+-------+
             |              |
          テキスト         ツール呼び出し
             |              |
      Agent イベントを出力  ポリシーと Hooks を確認
                            |
                       ツールを実行
                            |
                  ツール結果を履歴へ追加
                            |
                            +------> 次のループ

             ツール呼び出しがなくなる
                    |
                完了 Hooks を実行
                    |
                最終結果を出力
  1. コンテキストを構築する。 qodercli は、タスク、会話履歴、システム指示、ワークスペース設定、利用可能なツール、関連する Hook コンテキストを組み合わせます。
  2. モデルへ問い合わせる。 モデル出力はストリームされます。テキストはすぐに表示でき、完成したツールリクエストは実行パイプラインへ送られます。
  3. 操作を許可する。 qodercli は、ツールの利用可否、許可・確認・拒否ルール、権限コールバック、ツール実行前 Hooks を適用します。拒否されたツールは実行されず、理由を示すツール結果が生成されます。
  4. ツールを実行する。 承認された組み込みツール、MCP ツール、サブ Agent をランタイムが実行し、結果を収集します。安全な場合、互いに独立したツール呼び出しは並行して実行できます。
  5. 得られた情報を使って続行する。 ツール結果を会話へ追加し、モデルは次の反復で結果を確認して次の操作を決めます。
  6. 完了または停止する。 ツール呼び出しがなくなり、完了 Hook が結果を受け入れると終了します。設定された制限、中断、キャンセル、エラーでも停止します。
モデル自体がファイルを開いたりプロセスを開始したりすることはありません。モデルはツール呼び出しを提案し、qodercli が実行の可否と方法を決定します。

ツール、MCP、サブ Agent

qodercli は、そのセッションで利用できるツールだけをモデルに提示します。
  • 組み込みツールは、ファイルの読み取りと編集、プロジェクトの検索、コマンドの実行などのローカル操作を行います。
  • MCP ツールは、外部 MCP サーバーまたは SDK アプリケーション内で動く MCP サーバーから提供できます。プロセス内サーバーの場合、qodercli は MCP 制御リクエストを SDK へ送り、SDK が登録済みサーバーを呼び出し、同じ制御チャネルでレスポンスを返します。
  • サブ Agentは、独自のプロンプトとコンテキストで委任されたタスクを実行し、通常はより限定されたツールセットを使用します。最終出力はツール結果として親 Agent へ返ります。
ツール結果は、後続のモデルコンテキストと SDK イベントになります。結果が大きい場合、Agent が安全に処理を続けられる情報を残しながら、会話内の内容が短縮されることがあります。

コンテキストとセッション状態

qodercli が実行中の会話状態を保持します。SDK はアプリケーションのコールバックを保持し、プロトコルオブジェクトを TypeScript または Python のメッセージ型へ変換します。 セッションが長くなると、qodercli はモデルのコンテキスト使用量を監視します。必要に応じて次のモデルリクエストの前に古い履歴を圧縮し、アプリケーションがプロンプトを再構築しなくても長いタスクを続けられるようにします。ただし、重要な情報は無制限の会話メモリに頼らず、ファイルまたは明示的なセッション状態へ保存してください。 セッションの永続化を有効にすると、qodercli は Transcript を保存し、後から再開できます。再開と Checkpoint の動作は、セッションストレージと Checkpointを参照してください。

完了、エラー、キャンセル

アプリケーションは result を受信するか、イテレーターでエラーが発生するまで、メッセージを処理し続けてください。
  • Agent ターンの成功または失敗は、最後の result メッセージにまとめられます。利用可能なステータスと使用量情報も含まれます。
  • interrupt は、qodercli に実行中のターンの停止を要求します。サポートされる長時間セッションでは、停止後もセッションを利用できます。
  • SDK ストリームを閉じるか中止すると、Transport も閉じられます。プロセス Transport は最初に正常終了を試み、qodercli が終了しない場合は終了方法を段階的に強めます。
  • プロセスの起動失敗、無効なプロトコルメッセージ、ランタイムの切断、初期化タイムアウトは、Agent の結果ではなく SDK エラーとして通知されます。
公開制御 API はセッション制御、使用量フィールドはコストと使用量を参照してください。

セキュリティとデータフロー

SDK と qodercli が同じマシン上にあることは、タスク全体がローカルだけで処理されることを意味しません。 
ローカルアプリ <---- ローカルプロトコル ----> qodercli
                                               |
                                               +----> Qoder モデルサービス
                                               |      タスク情報と実行結果
                                               |
                                               +----> ローカルまたは設定済みツール
                                                      実際の副作用
  • 認証情報は JSONL メッセージストリームとは別に、一時ペイロードで qodercli へ渡され、SDK によって削除されます。
  • qodercli は推論に必要なタスクコンテキストをモデルサービスへ送ります。これにはプロンプト、ファイルの抜粋、ツール結果が含まれる場合があります。
  • ツールは qodercli の環境で実行され、設定に応じて他のシステムの読み取り、書き込み、呼び出しを行う場合があります。
  • cwd、ツールの許可リスト、権限ルール、Hooks、サンドボックス、インフラストラクチャ分離は相互に補完する制御です。タスクの影響に合わせて設定してください。
承認方式と権限モードは権限、ライフサイクルイベントの処理は Hooksを参照してください。

TypeScript と Python のセッション API

ランタイムプロトコルは共通ですが、各 SDK は言語に適したセッション API を提供します。
シナリオTypeScriptPython
1 つのプロンプトと結果query({ prompt: string, ... })query(prompt=..., options=...)
複数のユーザーメッセージ非同期メッセージイテラブルを query() へ渡すQoderSDKClient に接続し、query() を再度呼ぶ
出力の読み取り判別可能なメッセージ Union を for await で処理型付きメッセージオブジェクトを async for で処理
ランタイム制御返された query ストリームのメソッドQoderSDKClient のメソッド

次のステップ

クイックスタート
基本概念
会話とセッション
拡張機能
制御と可観測性
リファレンス