Halaman ini diterjemahkan dari dokumentasi bahasa Inggris. Perintah, pengenal, dan contoh tidak diubah. Runtime 7.24.4 · SDK 2.6.7. Sumber bahasa Inggris

SDK @defai-digital/ax-code-sdk

SDK TypeScript untuk mengintegrasikan runtime agen pengodean AX Code ke dalam aplikasi Anda sendiri.

Pakai untuk mengawasi runtime AX Code bertanda tangan yang kompatibel melalui batas tanpa interaksi atau gRPC yang bertipe, memakai peristiwa aliran, memproyeksikan keadaan sesi, dan menguji integrasi aplikasi. Host sumber yang sengaja menyediakan paket runtime privat juga dapat memakai adaptor dalam proses createAgent().

Pemasangan

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

Membutuhkan Node.js 26+ (atau Deno dengan kompatibilitas Node). Versi Node.js yang lebih lama tidak didukung. Pembantu siklus hidup tanpa interaksi dan gRPC mengharapkan executable ax-code yang ditandatangani pada PATH, atau jalur absolut yang diteruskan sebagai binary. Versi SDK dan runtime berdiri sendiri. Periksa protokol kemampuan runtime sebelum mengaktifkan fitur aplikasi; pemeriksaan versi SDK saja tidak menetapkan kompatibilitas runtime.

Nama paket ruang kerja @ax-code/sdk bersifat privat untuk monorepo ini. Konsumen publik selalu memasang @defai-digital/ax-code-sdk dari JSR.

Migrasi API laporan

AX Code 7.24.1 mengganti laporan graf DRE dengan Run Report. Integrasi laporan harus memakai ax-code run-report dan rute HTTP /run-report; perintah lama dre-graph dan rute /dre-graph dihapus. Operasi SDK yang dihasilkan sekarang adalah getRunReportSessionSessionId dan getRunReportSessionSessionIdFingerprint, menggantikan operasi getDreGraph yang sesuai.

Tingkatkan integrasi laporan dan runtime bersama-sama. Permukaan integrasi lain tetap membutuhkan pemeriksaan kemampuan runtime sendiri.

Pilih permukaan integrasi

Aplikasi publik harus memakai headless atau grpc dengan runtime AX Code bertanda tangan yang kompatibel. HTTP/OpenAPI tetap di belakang SDK itu sebagai lapisan cadangan dan diagnostik. Subjalur lama @defai-digital/ax-code-sdk/v2 tetap ada untuk kompatibilitas runtime; integrasi baru tidak boleh mulai dari sana.

createAgent() memuat paket sumber privat ax-code pada saat panggilan. Runtime tidak diterbitkan di JSR.

Mulai cepat (tanpa interaksi)

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()
}

Host desktop dapat meneruskan jalur absolut yang terverifikasi sebagai binary. Lihat example/headless-app.ts untuk putaran aplikasi berbasis proyeksi.

Backend tanpa interaksi

startHeadlessBackend menelurkan ax-code serve pada port loopback acak, menghasilkan kredensial sekali pakai, menunggu /global/health, dan mengembalikan sebuah handle. close() mengirim SIGTERM, lalu 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 dan applyHeadlessProjectionEvent adalah TypeScript murni. UI aplikasi harus memperlakukan permission, question, session_diff, todo, session_status, dan session_error sebagai keadaan utama. Balasan otonom bersifat ikut serta; aplikasi yang diawasi harus merender permintaan izin dan pertanyaan yang tertunda.

Proyeksi otonom menjaga izin isolation_escalation, bash_destructive, ops_approve, webmcp, hook, dan computer tetap tertunda, serta permintaan apa pun yang metadatanya menyetel requireInteractive: true. Konsumen harus memperoleh balasan manusia yang eksplisit untuk permintaan ini.

gRPC / desktop bawaan

Pakai @defai-digital/ax-code-sdk/grpc bila host bawaan sudah memiliki transport (preload Electron, Tauri, Rust, HTTP/2).

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 structured-clone (preload / Tauri).
• createAxCodeGrpcClientFromNativeBridge() — realm JavaScript yang sama, dengan AbortSignal dan iterable asinkron.
• createAxCodeGrpcClientFromNativeHandlers() — ikat nama metode ke penangan bertipe; requireHandlers gagal cepat bila ada celah.
• startAxCodeGrpcNodeHttp2Server() dari @defai-digital/ax-code-sdk/grpc/node — ekspos jembatan yang sama sebagai titik akhir gRPC HTTP/2 lokal.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — katalog metode kanonis untuk daftar izin dan nama proto.

createAxCodeGrpcClientFromHttp() hanya loopback. Aset proto adalah packages/sdk/proto/ax_code/v1/headless.proto dan diselesaikan saat runtime dengan resolveAxCodeGrpcProtoUrl().

Agen dalam proses (hanya host sumber)

Jalur ini membutuhkan paket runtime privat ax-code. Ini bukan batas integrasi aplikasi publik.

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()

Autentikasi terdeteksi otomatis dari variabel lingkungan, disuntikkan melalui auth: { provider, apiKey }, atau diambil dari 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`)
}

Contoh lain: example/programmatic.ts.

Pengujian

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")
})

Kompatibilitas versi

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")
}

Kendali permintaan dan pengarahan

SDK 2.6 menambahkan kendali opsional pada permintaan tanpa interaksi. Panggilan yang sudah ada mempertahankan perilakunya; tidak ada batas waktu bawaan yang diberlakukan.

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) mengekspos titik akhir tindak lanjut antrean yang atomik. Hasil generation_not_active-nya membiarkan baris tidak berubah. SDK mengembalikan tanda terima dan alasan penolakan apa adanya. accepted berarti diterima untuk batas putaran berikutnya; applied berarti diterima secara tahan lama pada batas itu, dengan penyelesaian penyedia tetap terpisah. Tanda terima bersifat lokal proses dan dibatasi, jadi ketidakhadirannya setelah mulai ulang tidak membuktikan bahwa koreksi tidak pernah diterapkan.

requestOptions memasok bawaan untuk semua permintaan dan perintah kenyamanan tanpa interaksi, termasuk operasi alur kerja dan antrean tugas. Metode sesi/perintah inti dan pengarahan menerima penimpaan per panggilan; timeoutMs: 0 menonaktifkan batas waktu bawaan. Langganan memakai signal sendiri, dan client.client mempertahankan kendali klien yang dihasilkan. HeadlessTransport kustom menerima sinyal dan harus melepaskan sumber daya tertundanya saat dibatalkan.

Pembatalan HTTP dan IPC menghentikan tunggu lokal. Mutasi yang sudah dikirim tetap dapat dieksekusi; rekonsiliasi keadaan sesi/antrean sebelum mengambil tindakan lebih lanjut. Tidak satu pun transport mencoba ulang mutasi. Batas waktu memunculkan TimeoutError; pembatalan pemanggil mempertahankan alasan sinyal. Respons HTTP dan IPC yang tidak berhasil memunculkan HeadlessRequestError dengan status, body, method, dan path; bingkai kesalahan protokol IPC mempertahankan IpcTransportError.

Kompatibilitas runtime dan peningkatan dari SDK 2.5

Garis dasar kontrak yang dihasilkan saat ini adalah sumber AX Code v7.23.0. SDK 2.6 tidak menyimpulkan fitur yang tidak diiklankan dari versi runtime. Katalog kemampuan saat ini tidak mengiklankan pengarahan secara terpisah; periksa titik akhir baca sebelum menawarkan pengarahan, dan tangani kesalahan rute yang tidak didukung. SDK 2.6 mempertahankan titik masuk yang dihasilkan dan tanpa interaksi yang sudah ada. Metadata kesalahan respons dan kendali permintaan yang baru bersifat tambahan; kode yang menangkap Error tetap berfungsi.

Aplikasi yang meningkatkan pin yang lebih lama harus mula-mula memverifikasi runtime bertanda tangan mereka, lalu menguji negosiasi kemampuan, proyeksi peristiwa, izin/pertanyaan tertunda, pembatalan, dan penghentian backend. Perubahan pin konsumen berada di repositori pemakai setelah SDK target diterbitkan. Validasi paket terkompilasi secara lokal dengan pnpm --dir packages/sdk/js run test:consumer; ini memeriksa impor publik, deklarasi, dan aset proto dalam fixture terisolasi tanpa paket sumber runtime privat.

Integrasi lintas bahasa

Paket ini adalah SDK TypeScript/JavaScript pihak pertama. Untuk Python, Go, Java, Rust, atau runtime lain, hasilkan dari proto gRPC repositori atau pakai batas CLI/runtime yang dimiliki integrasi itu.

Migrasi dari @ax-code/sdk 1.4.0

Subjalur ./programmatic masih mengekspor ulang entri bawaan; perlakukan sebagai usang.

Lisensi

Apache-2.0