Copilot ランタイムを実行中に実行する

インプロセス ホスティングを使用する場合

インプロセス ホスティングは、次の場合に適しています。

• アプリケーションは、別のランタイム プロセスなしで実行する必要があります。
• SDK でランタイム ライフサイクルを所有する必要があります。
• デプロイ プラットフォームごとにネイティブ ライブラリを配布できます。
• プロセス全体の環境と作業ディレクトリの設定を使用できます。

プロセスの分離と最も確立されたデプロイ パスの方が重要な場合は 、AUTOTITLE を 使用します。 複数のアプリケーション インスタンスが TCP 経由で共有ランタイムに接続する必要がある場合は、 AUTOTITLE を 使用します。

どのように機能するのか

SDK は、Copilot ランタイム ネイティブ ライブラリを読み込み、その固定 C ABI をバインドします。 すべての SDK メソッドは、メモリ内接続経由で既存の Content-Lengthフレーム JSON-RPC プロトコルを引き続き使用します。

ランタイム:

• Node.js、子プロセス、TCP ポート、または接続トークンを使用せずに、アプリケーション プロセスで実行されます。
• 他のトランスポートと同じセッション、ストリーミング イベント、ツール、フック、アクセス許可、およびサーバーからクライアントへの要求をサポートします。
• ネイティブ ワーカー スレッドから SDK コールバックを呼び出すことができます。 SDK はスレッド マーシャリングとコールバックの有効期間を処理します。
• 読み込まれたネイティブ ライブラリとそのワーカー プールを、アプリケーション プロセスの有効期間中使用可能な状態に保ちます。

SDK の要件

すべての SDK は、明示的なインプロセス接続オプションを公開します。 一部の言語では、追加のビルドまたはパッケージ構成が必要です。

ネイティブ ランタイム バンドルは、ホスト オペレーティング システム、CPU アーキテクチャ、Linux 上の C ライブラリと一致する必要があります。 サポートされていないホストは、子プロセスにフォールバックするのではなく、ランタイムの解決または起動中に失敗します。

インプロセス接続を構成する

クライアントを作成するときに、言語固有の接続オプションを渡します。

import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk";

const client = new CopilotClient({
  connection: RuntimeConnection.forInProcess(),
});

await client.start();

from copilot import CopilotClient, RuntimeConnection

client = CopilotClient(
    connection=RuntimeConnection.for_inprocess(),
)

await client.start()

client := copilot.NewClient(&copilot.ClientOptions{
    Connection: copilot.InProcessConnection{},
})

if err := client.Start(context.Background()); err != nil {
    log.Fatal(err)
}
defer client.Stop()

#pragma warning disable GHCP001

var client = new CopilotClient(new CopilotClientOptions
{
    Connection = RuntimeConnection.ForInProcess(),
});

await client.StartAsync();

let options = ClientOptions::default()
    .with_transport(Transport::InProcess);

let client = Client::start(options).await?;

import com.github.copilot.AllowCopilotExperimental;

@AllowCopilotExperimental
public class Example {
    public void run() throws Exception {
        CopilotClientOptions options = new CopilotClientOptions()
            .setConnection(RuntimeConnection.forInProcess());

        CopilotClient client = new CopilotClient(options);
        client.start().join();
    }
}

アプリケーションを開始する前に、 COPILOT_SDK_DEFAULT_CONNECTION=inprocess を設定することもできます。 SDK では、クライアントが明示的に接続を指定していない場合にのみ、この値が使用されます。 無効な値を指定すると、スタートアップが失敗します。

アプリケーション コードで明示的なクライアント構成を優先します。 デプロイ構成でアプリケーションを変更せずにトランスポートを選択する必要がある場合は、環境変数を使用します。

ランタイムを構成する

SDK は、サポートされている型指定されたクライアント オプションをネイティブ ランタイム引数とホスト スコープの環境値に変換します。 SDK に応じて、次のオプションがあります。

• 認証トークンとログイン中のユーザーへのフォールバック。
• Copilot のベース ディレクトリ。
• ログレベル。
• セッションのタイムアウト。
• リモート セッション モード。

インプロセス ランタイムは、ホスト環境のスナップショットと、サポートされている SDK によって管理されるオーバーライドを受け取ります。 ホスト環境は変更されません。

最初のインプロセス クライアントを作成する前に、プロセス全体の値を設定します。 これには、型指定されたクライアント オプションとアプリケーションの現在の作業ディレクトリで表されない環境変数が含まれます。

ランタイムライブラリの解決

各 SDK は、まず、互換性のあるバンドルされたランタイム ライブラリまたはキャッシュされたランタイム ライブラリを探します。 ランタイムを個別に指定する必要がある場合は、互換性のあるCopilotランタイム パッケージを指すCOPILOT_CLI_PATHを設定できます。

通常、プロセスに読み込むことができるネイティブ ランタイム ライブラリのパスとバージョンは 1 つだけです。 同じ読み込まれたライブラリを使用して別のクライアントを起動することはサポートされていますが、別のランタイム ライブラリを読み込もうとすると失敗します。

運用環境のデプロイの場合:

1. ターゲット プラットフォームごとにアプリケーションをビルドしてテストします。
2. 一致するネイティブ ランタイム成果物がデプロイされたパッケージに含まれているか、SDK のランタイム ダウンロード メカニズムを通じて使用できることを確認します。
3. 少なくとも 1 つのセッションを開始し、デプロイ スモーク テストでモデル ターンを完了します。
4. アプリケーションが終了する前にクライアントを正常に停止します。

ライフサイクルの動作

インプロセス クライアントを起動すると、ネイティブ ライブラリが読み込まれ、ランタイム ホストが作成され、メモリ内接続が開き、通常の SDK プロトコル バージョンハンドシェイクが実行されます。

グレースフル シャットダウン中、SDK は次の処理を行います。

1. アクティブなセッションを閉じます。
2. JSON-RPC 経由での通常のランタイム シャットダウンを要求します。
3. JSON-RPC 接続とネイティブ接続を閉じます。
4. ランタイム ホストを解放します。

ネイティブ ライブラリは、アプリケーション プロセスが終了するまで読み込まれたままになります。 最初の使用後にランタイム ライブラリをアンロードして置き換えることに依存しないでください。

Limitations

インプロセス ホスティングには、次の現在の制約があります。

• 試験段階の API: 動作とパッケージ化の要件は、リリース間で変更される可能性があります。
• 共有プロセスの状態: すべてのクライアントは、ホスト プロセス環境、現在の作業ディレクトリ、ネイティブ ライブラリ、ランタイム ワーカー プールを共有します。
• 制限付きプロセス オプション: 任意の環境、作業ディレクトリ、テレメトリ構成、実行可能パス、または CLI 引数の SDK オプションは、該当する場合は拒否されます。 ホスト プロセスでプロセス グローバル値を構成し、ランタイム設定でサポートされている型指定されたオプションを使用します。
• クライアントごとの作業ディレクトリなし: ランタイムはホスティング プロセスの作業ディレクトリを使用します。
• プロセスごとに 1 つのランタイム バージョン: 別のネイティブ ライブラリ パスまたはバージョンの読み込みはサポートされていません。
• プラットフォームの成熟度は異なります。一部の SDK とプラットフォームの組み合わせにより、モデルターンまたはシャットダウンの対象範囲が減少しています。 デプロイする正確な組み合わせを検証します。

詳細については、次を参照してください。

• セットアップ ガイド: インプロセス ホスティングを他のデプロイ モデルと比較する
• 既定のセットアップ (バンドルされた CLI): マネージド子プロセスでバンドルされたランタイムを実行する
• バックエンド サービスのセットアップ: TCP 経由でアプリケーションを共有ランタイムに接続する
• セッションライフサイクルフック: セッションの開始イベントと終了イベントを処理する