Skip to main content
クイックスタート

一般的な統合シナリオ

バッチ処理、対話型ツール、バックエンドサービス、承認フロー、ドメイン拡張に適した統合方式を説明します。

統合方式は主に、タスク開始後も入力を続けるか、ツール操作に外部判断が必要か、セッションをプロセスやホストをまたいで復元するかで決まります。このページでは、一般的な製品形態ごとに TypeScript と Python の推奨エントリポイント、機能の組み合わせ、実行時の境界を示します。

方式を選ぶ

タスク
 |
 +-- 1 回の入力で完了 -----------> 単発の query()
 +-- 追加の入力が必要 -----------> TypeScript 非同期メッセージストリーム
 |                                  Python QoderSDKClient
 +-- 操作に承認が必要 -----------> canUseTool / can_use_tool + Hooks
 +-- ホストをまたいで復元 -------> sessionStore / session_store + resume
 `-- 業務システムへ接続 ---------> MCP ツール、Skills、カスタム Agents
製品形態推奨エントリポイント主要機能
バッチスクリプト、CI ジョブ文字列タスクを渡す query()cwd、ツール範囲、非対話権限、Result
対話型開発ツールTypeScript 非同期メッセージストリーム、Python QoderSDKClientストリーミング出力、追加入力、中断、セッション ID
バックエンド API、ジョブサービスタスクごとにセッションを作成または復元サービス認証、同時実行制御、外部セッションストレージ
人による承認を含む自動化canUseTool / can_use_toolallow/deny ルール、承認 UI、Hooks
ドメインワークフローMCP、Skills、Agents、Plugins業務ツール、ドメイン指示、再利用可能な拡張パッケージ

バッチスクリプトと CI

コード検査、テスト生成、移行レポート、ドキュメント生成などは、明確な入力と最終結果が 1 つずつあれば実行できます。文字列で query() を呼び出し、タスク完了時にセッションを終了します。 
CI ジョブまたは定期タスク
            |
            v
     query("指定タスク")
            |
            +-- 構造化メッセージとツール活動
            `-- Result: 成功、失敗、中断
推奨設定：
  • 開発端末のログイン状態ではなく、PAT や Service Account など自動化向けの認証方式を使用します。
  • cwd を明示し、ファイル操作とコマンド実行をジョブのワークスペース内に限定します。
  • レポート作成では Read、Glob、Grep などの読み取りツールだけを公開します。変更が必要な場合だけ Edit、Write、Bash を追加します。
  • バックグラウンドジョブには確認 UI がありません。明示的な allow/deny ルールと dontAsk を組み合わせ、未承認操作を拒否します。管理されたワークスペースの変更には acceptEdits が適しています。
  • Result までストリームを消費し、subtype、errors、利用可能な場合は error_code で結果を分類します。
すべての権限チェックを省略できるのは、コンテナや使い捨てワークスペースなどでタスクが隔離済みの場合だけです。権限制御とエラー処理とエラーコードを参照してください。

対話型開発ツール

チャット形式のコーディングアシスタント、IDE 機能、社内開発ポータルでは、タスク開始後も入力を受け取り、Agent のテキスト、ツール活動、状態をリアルタイムに表示します。
  • TypeScript：AsyncIterable<SDKUserMessage> を query() に渡します。
  • Python：QoderSDKClient でセッションを作成し、query() でメッセージを送り、receive_response() で各ターンの出力を受け取ります。
  • ストリーミングイベントで画面を更新し、interrupt() で現在のターンを停止します。
  • 製品内の各会話に対応する session_id を保存します。継続には resume、元の分岐を残す場合は fork を使用します。
  • 追加入力には、即時、次の処理機会、現在のターン終了後のいずれかを明示します。
チャットまたは IDE
   |  入力、追質問、中断
   v
長期セッション ----------> ストリーミングメッセージ ----------> 画面
   |
   `---------------------> session_id
入力モード、ストリーミング出力、セッション制御を参照してください。

バックエンド API とジョブサービス

バックエンドサービスは、HTTP リクエスト、キューメッセージ、定期ジョブを Agent セッションに変換できます。各ローカルアクティブセッションは 1 つの qodercli プロセスを使用するため、同時実行数の設計ではプロセス数、モデルリクエスト、ファイルシステム、コマンド実行リソースを考慮します。 
HTTP API / Queue
       |
       v
アプリケーションサービス -----> Agent SDK -----> qodercli
       |                                             |
       +-- セッション索引または外部ストレージ       +-- ワークスペースとコマンド
       `-- ログ、タイムアウト、キャンセル           `-- Qoder モデルサービス
サービス統合では次の境界を設定します。
  • 実行環境で qodercli 子プロセスを起動でき、タスク用ワークスペース、コマンド、依存関係が利用できる必要があります。
  • 自動化サービスでは明示的な認証情報を使用します。ローカルログインは開発端末向けです。
  • リクエストを安定した session_id に対応付けます。単一ホストではローカルセッションを利用でき、複数ホスト、コンテナ、一時ディスクでは sessionStore / session_store でセッションをミラーします。
  • ホストをまたいで復元する場合、対象ホスト間でプロジェクトディレクトリの意味とプロジェクト内容を一致させます。
  • ストリーミング API は Agent イベントを呼び出し元へ転送できます。非同期ジョブは進捗と最終 Result を保存できます。
  • タイムアウト時は interrupt() を呼び出すかセッションを閉じ、必要なエラーとプロセス診断を残します。
SDK 認証と外部セッションストレージを参照してください。

人による承認を含むワークフロー

コード変更、コマンド実行、リリース操作、業務システムへの書き込みでは、製品 UI、承認システム、ポリシーサービスによる判断が必要になる場合があります。権限制御は静的境界と実行時判断に分かれます。
  1. tools でセッションに表示するツールを決めます。
  2. allowedTools / allowed_tools と disallowedTools / disallowed_tools で事前許可と禁止を定義します。
  3. canUseTool / can_use_tool で未承認のツール要求を受け取り、allow または deny を返します。
  4. Hooks でツール実行の前後に検証、監査、通知を行います。
Agent がツールを要求
          |
          v
静的ルール ----deny----> 拒否結果
          |
         承認
          v
製品 UI / ポリシーサービス
    | allow          | deny
    v                v
ツール実行         拒否結果
承認画面にはツール名、重要な引数、影響範囲、セッションの文脈を表示します。無人ジョブには明確な拒否ルールとタイムアウトを設定し、セッションの待機継続を防ぎます。承認コールバックと Hooks は、ワークスペースの隔離や最小権限の認証情報を置き換えるものではありません。 権限制御と Hooksを参照してください。

業務ツールとドメイン機能

拡張機能により、Agent は業務データの読み取り、社内システムの呼び出し、ドメイン固有の作業方法の再利用ができます。目的に応じて拡張種別を選びます。
目的推奨機能適した内容
ホストプロセス内の関数を呼び出すプロセス内 MCP ツールデータ検索、チケット操作、社内 API ラッパー
既存のツールサービスへ接続する外部 MCP Server独立配備された標準ツールセット
操作手順を再利用するSkillsチーム規約、診断手順、成果物テンプレート
専門ロールを定義するAgentsコードレビュー、テスト分析、移行計画
複数の拡張を配布するPluginsSkills、Agents、MCP、コマンドの組み合わせ
ツール入力には明示的な構造化フィールドを使い、応答にはタスクに必要なデータだけを含めます。業務認証情報はタスク本文に追加せず、ツール実装またはホストサービスに保持します。書き込み操作には引き続き権限ルールまたは承認コールバックを適用します。 ツール、MCP、Agents、Skills、Pluginsを参照してください。

本番導入チェック

  • 実行環境：qodercli が起動し、cwd が適切に隔離されたワークスペースを指し、必要なコマンドと依存関係が利用できます。
  • 認証：認証情報を環境変数またはシークレット管理から注入し、ログとタスク本文にシークレットを含めません。
  • 権限：ツールセットを最小権限にし、バックグラウンドジョブが利用できない確認 UI に依存しないようにします。
  • ライフサイクル：Result までメッセージストリームを消費し、タイムアウト、中断、プロセス終了、アプリケーション終了を処理します。
  • セッション：復元が必要な場合は session_id を保存し、複数ホストでは共有セッションストレージを設定します。
  • 同時実行：アクティブな qodercli プロセス、ワークスペース、モデルリクエスト、ツールリソースを含めて容量を設計します。
  • 可観測性：Result、ツール活動、必要な診断を記録し、認証情報と機密業務データを除外します。
  • バージョン：SDK 同梱ランタイムを使用するか、別途指定する qodercli 実行ファイルと SDK の互換性を維持します。

関連ドキュメント

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