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

@defai-digital/ax-code-sdk 連携

AX Code のコーディングエージェントランタイムを、自分のアプリケーションへ組み込むための TypeScript SDK です。

互換性のある署名済み AX Code ランタイムを、型付きの ヘッドレス または gRPC 境界を通して監督し、ストリーミングイベントを消費し、セッション状態を投影し、アプリケーション連携をテストするために使います。プライベートなランタイムパッケージを意図的に提供するソースホストは、プロセス内の createAgent() アダプターも使えます。

インストール

pnpm add jsr:@defai-digital/ax-code-sdk@2.6.7

deno add jsr:@defai-digital/ax-code-sdk@2.6.7

npx jsr add @defai-digital/ax-code-sdk@2.6.7

Node.js 26+ が必要です（または Node 互換の Deno）。より古い Node.js は非対応です。ヘッドレスと gRPC のライフサイクルヘルパーは、署名済みの ax-code 実行ファイルが PATH にあること、または絶対パスが binary として渡されることを期待します。SDK とランタイムのバージョンは独立です。アプリ機能を有効にする前に、ランタイム能力プロトコルを確認してください。SDK のバージョン確認だけでは、ランタイム互換は確立されません。

ワークスペースパッケージ名 @ax-code/sdk は、このモノレポにプライベートです。公開の利用者は常に JSR から @defai-digital/ax-code-sdk をインストールします。

レポート API の移行

AX Code 7.24.1 は、DRE グラフレポートを Run Report に置き換えます。レポート連携は ax-code run-report と /run-report HTTP ルートを使わなければなりません。古い dre-graph コマンドと /dre-graph ルートは削除されました。生成 SDK 操作は現在 getRunReportSessionSessionId と getRunReportSessionSessionIdFingerprint であり、対応する getDreGraph 操作を置き換えます。

レポート連携とランタイムは一緒にアップグレードしてください。他の連携表面は、依然として独自のランタイム能力確認を必要とします。

連携表面を選ぶ

公開アプリケーションは、互換性のある署名済み AX Code ランタイムとともに headless または grpc を使うべきです。HTTP/OpenAPI は、それらの SDK の背後にフォールバックと診断レイヤーとして残ります。レガシーの @defai-digital/ax-code-sdk/v2 サブパスはランタイム互換のために残ります。新しい連携はそこから始めるべきではありません。

createAgent() は、呼び出し時にプライベートな ax-code ソースパッケージを読み込みます。ランタイムは JSR には公開されていません。

クイックスタート（ヘッドレス）

import { createHeadlessClient, startHeadlessBackend } from "@defai-digital/ax-code-sdk/headless"

const directory = process.cwd()
const backend = await startHeadlessBackend({ directory })
try {
  const client = createHeadlessClient({
    baseUrl: backend.url,
    directory,
    headers: backend.headers,
  })
  const session = await client.createSession({ title: "SDK example" })
  await client.sendPrompt(session.id, {
    parts: [{ type: "text", text: "Summarize this project." }],
  })
} finally {
  await backend.close()
}

デスクトップホストは、検証済みの絶対パスを binary として渡せます。投影ベースのアプリループについては example/headless-app.ts を参照してください。

ヘッドレスバックエンド

startHeadlessBackend は、ランダムなループバックポートで ax-code serve を起動し、一度きりの資格情報を生成し、/global/health を待ち、ハンドルを返します。close() は SIGTERM を送り、そのあと SIGKILL を送ります。

import {
  startHeadlessBackend,
  createHeadlessClient,
  createHeadlessProjectionState,
  applyHeadlessProjectionEvent,
} from "@defai-digital/ax-code-sdk/headless"

const backend = await startHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = createHeadlessClient({ baseUrl: backend.url, headers: backend.headers })
  const state = createHeadlessProjectionState()
  const session = await client.createSession({ title: "My session" })

  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  for await (const event of client.subscribe()) {
    applyHeadlessProjectionEvent(state, event)
    if (state.session_status[session.id]?.type === "idle") break
  }
} finally {
  await backend.close()
}

createHeadlessProjectionState と applyHeadlessProjectionEvent は純粋な TypeScript です。アプリ UI は、permission、question、session_diff、todo、session_status、session_error を主要な状態として扱うべきです。自律の返信はオプトインです。監督付きアプリは、保留中の権限と質問のリクエストを描画すべきです。

自律の投影は、isolation_escalation、bash_destructive、ops_approve、webmcp、hook、computer の権限を保留のままにし、メタデータが requireInteractive: true を設定するリクエストも同様です。消費者は、これらのリクエストについて明示的な人間の返信を得なければなりません。

gRPC とネイティブデスクトップ

ネイティブホストがすでに転送を所有しているとき（Electron プリロード、Tauri、Rust、HTTP/2）は、@defai-digital/ax-code-sdk/grpc を使います。

import {
  createAxCodeGrpcClientFromNativeIpc,
  resolveAxCodeGrpcProtoUrl,
  startAxCodeGrpcHeadlessBackend,
} from "@defai-digital/ax-code-sdk/grpc"

const backend = await startAxCodeGrpcHeadlessBackend({ directory: "/path/to/workspace" })
try {
  const client = backend.client
  await client.bootstrap.load({
    include: { sessions: true, providers: true, path: true, vcs: true },
  })
  const session = (await client.createSession({ title: "Desktop session" })) as { id: string }
  await client.sendPrompt(session.id, { parts: [{ type: "text", text: "Review this project" }] })
  const protoUrl = resolveAxCodeGrpcProtoUrl()
} finally {
  await backend.close()
}

• createAxCodeGrpcClientFromNativeIpc() — 構造化クローン IPC（プリロード / Tauri）。
• createAxCodeGrpcClientFromNativeBridge() — 同じ JavaScript レルム。AbortSignal と async iterable を伴います。
• createAxCodeGrpcClientFromNativeHandlers() — メソッド名を型付きハンドラーへバインドします。requireHandlers は隙間があるとすぐに失敗します。
• startAxCodeGrpcNodeHttp2Server() を @defai-digital/ax-code-sdk/grpc/node から — 同じブリッジをローカル HTTP/2 gRPC エンドポイントとして公開します。
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — 許可リストと proto 名のための正規メソッドカタログ。

createAxCodeGrpcClientFromHttp() はループバックのみです。proto アセットは packages/sdk/proto/ax_code/v1/headless.proto であり、実行時に resolveAxCodeGrpcProtoUrl() で解決されます。

プロセス内エージェント（ソースホストのみ）

この経路はプライベートな ax-code ランタイムパッケージを必要とします。公開アプリ連携の境界ではありません。

import { createAgent, tool } from "@defai-digital/ax-code-sdk"
import { z } from "zod"

const deploy = tool({
  name: "deploy_staging",
  description: "Deploy the current branch to staging",
  parameters: z.object({
    service: z.enum(["api", "web", "worker"]),
    skipTests: z.boolean().default(false),
  }),
  execute: async ({ service }) => ({ url: `https://staging.example.com/${service}` }),
})

const agent = await createAgent({ directory: "/repo", tools: [deploy] })

const result = await agent.run("Fix the login bug")
for await (const event of agent.stream("Explain this codebase")) {
  if (event.type === "text") process.stdout.write(event.text)
}
const session = await agent.session()
await session.run("Read src/auth/index.ts")
await agent.dispose()

認証は、環境変数から自動検出されるか、auth: { provider, apiKey } を通して注入されるか、ax-code providers login から取られます。

import { ProviderError, ToolError, TimeoutError } from "@defai-digital/ax-code-sdk"

try {
  await agent.run("Deploy to prod")
} catch (e) {
  if (e instanceof ProviderError && e.isRetryable) console.log("Rate limited, retry later")
  else if (e instanceof ToolError) console.log(`Tool "${e.tool}" failed: ${e.message}`)
  else if (e instanceof TimeoutError) console.log(`Timed out after ${e.timeout}ms`)
}

さらなる例: example/programmatic.ts。

テスト

import { createMockAgent, assertToolSuccess } from "@defai-digital/ax-code-sdk/testing"

test("CI bot scans for CVEs", async () => {
  const agent = createMockAgent({
    replies: ["Found 2 CVEs. Opening PR to bump versions."],
    toolCalls: [{ tool: "grep", input: { pattern: "CVE-" }, output: "CVE-2025-1234" }],
  })
  const result = await agent.run("scan for CVEs")
  expect(result.text).toContain("2 CVEs")
  assertToolSuccess(result, "grep")
})

バージョン互換

import { SDK_VERSION, isSDKVersionCompatible } from "@defai-digital/ax-code-sdk"

console.log(SDK_VERSION)
if (!isSDKVersionCompatible("^2.0.0")) {
  throw new Error("Incompatible SDK version")
}

リクエスト制御とステアリング

SDK 2.6 は、ヘッドレスリクエストに任意の制御を追加します。既存の呼び出しは振る舞いを保ちます。既定の期限は課されません。

import { createHeadlessClient, HeadlessRequestError } from "@defai-digital/ax-code-sdk/headless"

const client = createHeadlessClient({
  baseUrl: backend.url,
  headers: backend.headers,
  directory,
  requestOptions: { timeoutMs: 30_000 },
})
const compatibility = await client.checkCompatibility({ requiredFeatures: ["sessions", "asyncPrompt"] })
if (!compatibility.compatible) throw new Error(compatibility.issues.join("; "))

const controller = new AbortController()
const state = await client.steering(sessionID, { signal: controller.signal, timeoutMs: 5_000 })
if (state.generation) {
  try {
    const receipt = await client.steer(
      sessionID,
      {
        expectedGeneration: state.generation,
        clientID, // Keep this id with the correction so uncertain outcomes can be reconciled.
        text: "Use the existing session contract.",
      },
      { signal: controller.signal },
    )
    console.log(receipt.status)
  } catch (error) {
    if (error instanceof HeadlessRequestError && error.status === 409) {
      console.log("Correction conflicts with a prior request; reconcile the steering state.")
    } else {
      throw error
    }
  }
}

client.taskQueue.steer(taskID) は、原子的な待ち行列フォローアップのエンドポイントを公開します。その generation_not_active 結果は行を変えません。SDK は受領と拒否理由を原文のまま返します。accepted は、後のループ境界への受け入れを意味します。applied は、その境界での耐久的な受け入れを意味し、プロバイダーの完了は依然として別です。受領はプロセスローカルで上限があるため、再起動後にないことは、修正が一度も適用されなかった証明にはなりません。

requestOptions は、ワークフローとタスクキュー操作を含む、すべてのヘッドレスの便利リクエストとコマンドに既定を供給します。中核のセッションとコマンドのメソッド、およびステアリングは、呼び出しごとの上書きを受け付けます。timeoutMs: 0 は既定の期限を無効にします。購読は独自の signal を使い、client.client は生成クライアントの制御を保持します。カスタムの HeadlessTransport は信号を受け取り、中止したときに保留リソースを解放すべきです。

HTTP と IPC の取り消しは、ローカルの待機を止めます。送出済みの変更はそれでも実行されることがあります。さらなる行動の前に、セッションとキューの状態を照合してください。どちらの転送も変更を再試行しません。期限は TimeoutError を送出します。呼び出し側の中止は、信号の理由を保ちます。成功でない HTTP と IPC の応答は、HeadlessRequestError を、status、body、method、path とともに送出します。IPC プロトコルエラーフレームは IpcTransportError を保持します。

ランタイム互換と SDK 2.5 からのアップグレード

現在の生成契約の基準は AX Code ソース v7.23.0 です。SDK 2.6 は、ランタイムバージョンから広報されていない機能を推論しません。現在の能力カタログはステアリングを別に広報しません。ステアリングを提示する前に読み取りエンドポイントを確認し、非対応ルートのエラーを扱ってください。SDK 2.6 は、既存の生成エントリポイントとヘッドレスエントリポイントを保ちます。新しい応答エラーのメタデータとリクエスト制御は追加的です。Error を捕捉するコードは引き続き動きます。

より古いピンをアップグレードするアプリケーションは、まず署名済みランタイムを検証し、そのあと能力交渉、イベント投影、保留中の権限と質問、取り消し、バックエンド停止をテストすべきです。消費者のピン変更は、対象 SDK が公開されたあと、消費するリポジトリに属します。コンパイル済みパッケージは pnpm --dir packages/sdk/js run test:consumer でローカルに検証します。これは、プライベートランタイムソースパッケージなしの隔離フィクスチャで、公開インポート、宣言、proto アセットを確認します。

言語をまたぐ連携

このパッケージはファーストパーティの TypeScript/JavaScript SDK です。Python、Go、Java、Rust、またはその他のランタイムでは、リポジトリの gRPC proto から生成するか、その連携が所有する CLI/ランタイム境界を使ってください。

@ax-code/sdk 1.4.0 からの移行

./programmatic サブパスは、依然として既定エントリを再エクスポートします。非推奨として扱ってください。

ライセンス

Apache-2.0