Diese Seite ist eine Übersetzung der englischen Dokumentation. Befehle, Bezeichner und Beispiele bleiben unverändert. Runtime 7.24.4 · SDK 2.6.7. Englische Fassung

@defai-digital/ax-code-sdk Paket

TypeScript-SDK, um die Coding-Agent-Laufzeit von AX Code in eigene Anwendungen einzubinden.

Verwenden Sie es, um eine kompatible signierte AX-Code-Laufzeit über typisierte Grenzen headless oder gRPC zu beaufsichtigen, Streaming-Ereignisse zu verbrauchen, den Sitzungszustand zu projizieren und Anwendungsintegrationen zu testen. Quellhosts, die das private Laufzeitpaket absichtlich bereitstellen, können auch den prozessinternen Adapter createAgent() verwenden.

Installation

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

Erfordert Node.js 26+ (oder Deno mit Node-Kompatibilität). Ältere Node.js-Versionen werden nicht unterstützt. Hilfen für den Lebenszyklus von Headless und gRPC erwarten eine signierte ausführbare Datei ax-code auf PATH oder einen absoluten Pfad, der als binary übergeben wird. SDK- und Laufzeitversionen sind unabhängig. Prüfen Sie das Fähigkeitsprotokoll der Laufzeit, bevor Sie App-Funktionen aktivieren. Eine Prüfung nur der SDK-Version belegt keine Laufzeitkompatibilität.

Der Paketname des Workspace @ax-code/sdk ist privat für dieses Monorepo. Öffentliche Nutzer installieren immer @defai-digital/ax-code-sdk von JSR.

Migration der Report-API

AX Code 7.24.1 ersetzt den DRE-Graphbericht durch Run Report. Berichtsintegrationen müssen ax-code run-report und die HTTP-Routen /run-report verwenden. Der alte Befehl dre-graph und die Routen /dre-graph sind entfernt. Erzeugte SDK-Operationen sind jetzt getRunReportSessionSessionId und getRunReportSessionSessionIdFingerprint und ersetzen die entsprechenden Operationen getDreGraph.

Aktualisieren Sie Berichtsintegration und Laufzeit gemeinsam. Andere Integrationsoberflächen verlangen weiterhin eigene Prüfungen der Laufzeitfähigkeiten.

Eine Integrationsoberfläche wählen

Öffentliche Anwendungen sollten headless oder grpc mit einer kompatiblen signierten AX-Code-Laufzeit verwenden. HTTP/OpenAPI bleibt hinter diesen SDKs als Rückfall und Diagnoseschicht. Ältere Teilpfade @defai-digital/ax-code-sdk/v2 bleiben aus Kompatibilität zur Laufzeit. Neue Integrationen sollten dort nicht beginnen.

createAgent() lädt das private Quellpaket ax-code zum Aufrufzeitpunkt. Die Laufzeit wird auf JSR nicht veröffentlicht.

Schnellstart (headless)

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

Desktop-Hosts dürfen einen geprüften absoluten Pfad als binary übergeben. Siehe example/headless-app.ts für eine App-Schleife auf Basis der Projektion.

Headless-Backend

startHeadlessBackend startet ax-code serve auf einem zufälligen Loopback-Port, erzeugt ein einmaliges Zugangsdatum, wartet auf /global/health und liefert ein Handle. close() sendet SIGTERM, danach 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 und applyHeadlessProjectionEvent sind reines TypeScript. App-Oberflächen sollten permission, question, session_diff, todo, session_status und session_error als primären Zustand behandeln. Autonome Antworten sind optional. Beaufsichtigte Apps sollten ausstehende Berechtigungs- und Frageanfragen darstellen.

Die autonome Projektion hält Berechtigungen isolation_escalation, bash_destructive, ops_approve, webmcp, hook und computer ausstehend, ebenso jede Anfrage, deren Metadaten requireInteractive: true setzen. Verbraucher müssen für diese Anfragen eine ausdrückliche menschliche Antwort einholen.

gRPC / nativer Desktop

Verwenden Sie @defai-digital/ax-code-sdk/grpc, wenn ein nativer Host den Transport bereits besitzt (Electron-Preload, 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 mit strukturiertem Klonen (Preload / Tauri).
• createAxCodeGrpcClientFromNativeBridge() — dieselbe JavaScript-Umgebung, mit AbortSignal und asynchronen Iterierbaren.
• createAxCodeGrpcClientFromNativeHandlers() — Methodennamen an typisierte Handler binden; requireHandlers schlägt bei Lücken sofort fehl.
• startAxCodeGrpcNodeHttp2Server() aus @defai-digital/ax-code-sdk/grpc/node — dieselbe Brücke als lokalen HTTP/2-gRPC-Endpunkt bereitstellen.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — kanonischer Methodenkatalog für Zulassungslisten und Proto-Namen.

createAxCodeGrpcClientFromHttp() ist nur Loopback. Das Proto-Asset ist packages/sdk/proto/ax_code/v1/headless.proto und wird zur Laufzeit mit resolveAxCodeGrpcProtoUrl() aufgelöst.

Agent im Prozess (nur Quellhosts)

Dieser Pfad verlangt das private Laufzeitpaket ax-code. Er ist nicht die öffentliche Grenze für App-Integration.

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

Die Authentifizierung wird aus Umgebungsvariablen erkannt, über auth: { provider, apiKey } eingespeist oder aus ax-code providers login genommen.

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

Weitere Beispiele: example/programmatic.ts.

Tests

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

Versionskompatibilität

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

Anfragesteuerung und Lenkung

SDK 2.6 fügt Headless-Anfragen optionale Steuerungen hinzu. Vorhandene Aufrufe behalten ihr Verhalten. Es wird keine Standardfrist gesetzt.

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) stellt den atomaren Endpunkt für eingereihte Folgen bereit. Sein Ergebnis generation_not_active lässt die Zeile unverändert. Das SDK gibt Belege und Ablehnungsgründe wortgetreu zurück. accepted bedeutet Zulassung für eine spätere Schleifengrenze. applied bedeutet dauerhafte Zulassung an dieser Grenze, wobei der Abschluss beim Anbieter getrennt bleibt. Belege sind prozesslokal und begrenzt, daher beweist ihr Fehlen nach einem Neustart nicht, dass eine Korrektur nie angewendet wurde.

requestOptions liefert Vorgaben für alle bequemen Headless-Anfragen und Befehle, einschließlich Ablauf- und Aufgabenwarteschlangen. Kernmethoden für Sitzung und Befehl sowie die Lenkung akzeptieren Überschreibungen je Aufruf. timeoutMs: 0 schaltet eine Standardfrist ab. Abonnements verwenden ein eigenes signal, und client.client behält die Steuerungen des erzeugten Clients. Ein eigenes HeadlessTransport erhält das Signal und soll ausstehende Ressourcen freigeben, wenn es abbricht.

Abbruch über HTTP und IPC beendet das lokale Warten. Eine bereits versendete Mutation kann weiterhin ausgeführt werden. Gleichen Sie Sitzungs- und Warteschlangenzustand ab, bevor Sie weiter handeln. Keiner der beiden Transporte wiederholt Mutationen. Fristen lösen TimeoutError aus. Abbrüche des Aufrufers bewahren den Grund des Signals. Nicht erfolgreiche Antworten von HTTP und IPC lösen HeadlessRequestError mit status, body, method und path aus. Fehlerrahmen des IPC-Protokolls behalten IpcTransportError.

Laufzeitkompatibilität und Upgrade von SDK 2.5

Die aktuelle Basis des erzeugten Vertrags ist der AX-Code-Quellstand v7.23.0. SDK 2.6 leitet nicht angekündigte Funktionen nicht aus der Laufzeitversion ab. Der aktuelle Fähigkeitskatalog kündigt die Lenkung nicht getrennt an. Prüfen Sie den Leseendpunkt, bevor Sie Lenkung anbieten, und behandeln Sie Fehler nicht unterstützter Routen. SDK 2.6 bewahrt die vorhandenen Einstiegspunkte für erzeugte Clients und Headless. Neue Metadaten für Antwortfehler und Anfragesteuerungen sind ergänzend. Code, der Error abfängt, funktioniert weiterhin.

Anwendungen, die ältere Pins aktualisieren, sollten zuerst ihre signierte Laufzeit prüfen und dann Fähigkeitsaushandlung, Ereignisprojektion, ausstehende Berechtigungen und Fragen, Abbruch sowie das Herunterfahren des Backends testen. Änderungen an Verbraucher-Pins gehören in das verbrauchende Repository, nachdem das Ziel-SDK veröffentlicht wurde. Validieren Sie das kompilierte Paket lokal mit pnpm --dir packages/sdk/js run test:consumer. Das prüft öffentliche Importe, Deklarationen und Proto-Assets in einem isolierten Fixture ohne das private Laufzeitquellpaket.

Integrationen in anderen Sprachen

Dieses Paket ist das eigene SDK für TypeScript und JavaScript. Erzeugen Sie für Python, Go, Java, Rust oder andere Laufzeiten aus dem gRPC-Proto des Repositorys oder verwenden Sie die CLI- und Laufzeitgrenze, die diese Integration besitzt.

Migration von @ax-code/sdk 1.4.0

Der Teilpfad ./programmatic exportiert den Standardeinstieg weiterhin. Behandeln Sie ihn als veraltet.

Lizenz

Apache-2.0