このページは英語版ドキュメントの翻訳です。コマンド、識別子、例はそのままです。ランタイム 7.24.4 · SDK 2.6.7。英語版

HTTP と OpenAPI の互換性

状態: 有効範囲: 現行状態最終確認: 2026-09-02 担当: ax-code sdk

AX Code には 2 つの連携経路があります。

下記の JSR パッケージ名はリリース準備ができていますが、まだ最初の公開バージョンを受け取っていません。

ファーストパーティの TypeScript と JavaScript アプリ連携には、@defai-digital/ax-code-sdk を使います。
ファーストパーティのアプリとデスクトップ GUI の作業には、@defai-digital/ax-code-sdk/headless または @defai-digital/ax-code-sdk/grpc を使います。
別の言語、または互換性のためのプロセス境界が必要なときは、ax-code serve と OpenAPI 契約を使います。
AX Code が転送の両端を所有するファーストパーティのデスクトップ GUI 作業には、ネイティブ SDK トランスポートを使います。

HTTP/OpenAPI 経路は、互換性と生成クライアントの基盤です。Python、Go、Java、Rust、その他のクライアントが、AX Code がすべての言語向けに完全な公式パッケージを保守すると約束しなくても、同じサーバー API を呼べるようにします。gRPC/ネイティブ契約が使えるとき、ファーストパーティのデスクトップ GUI 内部の優先される特権ブリッジとして扱うべきではなく、ファーストパーティの JavaScript SDK サブパスとしても、もはや公開されていません。

経路を選ぶ

必要	推奨経路	理由
同一プロセスの TypeScript または JavaScript	ソースワークスペースの `createAgent()` アダプター	プライベートな AX Code ランタイムのソースパッケージを意図的に解決できる場合にのみ利用できます
ファーストパーティのデスクトップ/ネイティブ GUI	`@defai-digital/ax-code-sdk/grpc`	より狭いヘッドレス契約、サーバーストリーミング、メタデータと期限に親和的で、WebView の露出が少ないです
ローカルバックエンドを伴う TypeScript または JavaScript	`@defai-digital/ax-code-sdk/headless`	完全な HTTP SDK の表面を露出させずに、ライフサイクルとイベント投影を型付きのまま保ちます
Python、Go、Java、Rust、または別のランタイム	`packages/sdk/openapi.json` からクライアントを生成	言語ごとのファーストパーティパッケージ保守を増やさずに、HTTP 契約を再利用します
CI、自動化、または単発スクリプト	`ax-code serve` に対する HTTP 呼び出し	単純な配備モデルと、容易なプロセス分離です

現在公式なもの

@defai-digital/ax-code-sdk はファーストパーティの TypeScript と JavaScript SDK です。その公開アプリ境界は headless と grpc です。
@defai-digital/ax-code-sdk/grpc は、ファーストパーティの任意デスクトップ/ネイティブヘッドレス転送ファサードです。
@defai-digital/ax-code-sdk/headless は、ローカルバックエンドのプロセス境界向けの、ファーストパーティの TypeScript と JavaScript のライフサイクル/イベント SDK です。
packages/sdk/openapi.json は、生成 HTTP クライアントのための OpenAPI スナップショットです。
生成された非 JavaScript クライアントは、HTTP 上の連携として対応されますが、パッケージ所有者、テスト、リリースワークフローが存在しない限り、ファーストパーティの公開パッケージではありません。

基本的な HTTP の流れ

サーバーを起動します。

export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096

@defai-digital/ax-code-sdk/headless ライフサイクルヘルパーは、一度きりの Basic Auth パスワードを生成し、返されたクライアントに一致する Authorization ヘッダーを自動で配線します。手動の ax-code serve 利用者は、AX_CODE_SERVER_PASSWORD を明示的に設定し、対応する Basic Auth ヘッダーを送るべきです。/doc のライブ OpenAPI ドキュメントと、すべてのサーバーエンドポイントは、ループバックのみです。

SDK が管理するバックエンドヘルパーは、0.0.0.0 のようなネットワークホスト名を常に拒否します。従来の allowNetworkBind オプションはソース互換のために残っていますが、ローカルのみのポリシーを迂回しなくなりました。デスクトップ GUI シェルは、@defai-digital/ax-code-sdk/grpc またはプロセス内 SDK 境界を優先すべきです。

HTTP ランタイムヘルパーは、もはや公開 JavaScript SDK のサブパスではありません。パッケージには、@defai-digital/ax-code-sdk/headless、gRPC の HTTP フォールバック、従来の AX Code ランタイムコードが使うため、生成クライアントの内部がまだ含まれます。外部連携は、@defai-digital/ax-code-sdk から HTTP ランタイムの値をインポートするのではなく、ヘッドレス、gRPC、または OpenAPI スナップショットから生成したクライアントを使うべきです。

サーバーの健全性を確認します。

curl http://127.0.0.1:4096/global/health

スナップショットを JSON と OpenAPI として検証したあと、OpenAPI スナップショットから生成クライアントを作ります。

openapi-python-client generate --path packages/sdk/openapi.json

oapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.go

openapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java

生成のガードレール

OpenAPI ドキュメントを、言語中立の契約として扱ってください。小さな使いやすさの層が必要な場合を除き、個々のルートを包む大きなラッパーを手で保守しないでください。

AX Code のバージョンと生成クライアントのバージョンを一緒に固定してください。サーバーのルートスキーマが変わったら、クライアントを再生成し、明確な互換性メモとともにリリースします。

生成コードは手書きヘルパーと分けてください。生成ファイルは置き換えやすく、手書きファイルは認証、既定、再試行、より高水準の便利 API だけを持つべきです。

サービス境界の振る舞いを保ってください。非 JavaScript クライアントは HTTP サーバー経路を使い、プロセス内の createAgent()、JavaScript のカスタムツール実行、@defai-digital/ax-code-sdk/testing ユーティリティは得られません。

生成クライアントをファーストパーティの地位へ上げる前に、難しい部分を覆ってください。

OpenAPI 検証が CI で実行されます。
契約テストが ax-code serve を起動し、代表的なルートを呼びます。
クライアントがイベント API を公開する場合、ストリーミングまたは SSE の振る舞いをテストします。
ディレクトリスコーピングのヘッダーと認証の振る舞いを文書化します。
公開、バージョン管理、所有が明示的です。

SDK パッケージには、現行スナップショット向けの軽いローカルガードが含まれます。

pnpm run check:openapi

SDK パッケージ内で作業しているときは、パッケージレベルのコマンドも使えます。

pnpm --dir packages/sdk/js run validate:openapi

これは、packages/sdk/openapi.json が解析可能な JSON であり、OpenAPI 3.x を宣言し、生成クライアントが必要とする中核ルートを含むことを検証します。