Esta página es una traducción de la documentación en inglés. Los comandos, identificadores y ejemplos no cambian. Runtime 7.24.4 · SDK 2.6.7. Original en inglés

SDK @defai-digital/ax-code-sdk

SDK de TypeScript para integrar el entorno de ejecución del agente de programación de AX Code en tus propias aplicaciones.

Úsalo para supervisar un entorno de ejecución firmado y compatible de AX Code a través de límites tipados headless o gRPC, consumir eventos en flujo, proyectar el estado de la sesión y probar integraciones de aplicación. Los hosts de código fuente que proporcionan de forma deliberada el paquete privado del entorno de ejecución también pueden usar el adaptador en proceso createAgent().

Instalación

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

Exige Node.js 26+ (o Deno con compatibilidad de Node). Las versiones anteriores de Node.js no se admiten. Las ayudas de ciclo de vida headless y gRPC esperan un ejecutable firmado ax-code en PATH, o una ruta absoluta pasada como binary. Las versiones del SDK y del entorno de ejecución son independientes. Comprueba el protocolo de capacidad del entorno de ejecución antes de activar funciones de la aplicación; una comprobación de versión del SDK por sí sola no establece compatibilidad del entorno de ejecución.

El nombre de paquete del espacio de trabajo @ax-code/sdk es privado de este monorepo. Los consumidores públicos instalan siempre @defai-digital/ax-code-sdk desde JSR.

Migración de la API de informes

AX Code 7.24.1 sustituye el informe de grafo DRE por Run Report. Las integraciones de informes deben usar ax-code run-report y las rutas HTTP /run-report; el comando antiguo dre-graph y las rutas /dre-graph se eliminan. Las operaciones generadas del SDK son ahora getRunReportSessionSessionId y getRunReportSessionSessionIdFingerprint, y sustituyen a las operaciones getDreGraph correspondientes.

Actualiza juntas la integración de informes y el entorno de ejecución. Las demás superficies de integración siguen exigiendo sus propias comprobaciones de capacidad del entorno de ejecución.

Elegir una superficie de integración

Las aplicaciones públicas deben usar headless o grpc con un entorno de ejecución firmado y compatible de AX Code. HTTP/OpenAPI permanece detrás de esos SDK como capa de respaldo y de diagnóstico. Los subcaminos heredados @defai-digital/ax-code-sdk/v2 siguen existiendo por compatibilidad del entorno de ejecución; las integraciones nuevas no deben empezar ahí.

createAgent() carga el paquete privado de código fuente ax-code en el momento de la llamada. El entorno de ejecución no se publica en JSR.

Inicio rápido (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()
}

Los hosts de escritorio pueden pasar una ruta absoluta verificada como binary. Consulta example/headless-app.ts para un bucle de aplicación basado en proyección.

Backend headless

startHeadlessBackend lanza ax-code serve en un puerto loopback aleatorio, genera una credencial de un solo uso, espera a /global/health y devuelve un manejador. close() envía SIGTERM y luego 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 y applyHeadlessProjectionEvent son TypeScript puro. Las interfaces de aplicación deben tratar permission, question, session_diff, todo, session_status y session_error como estado principal. Las respuestas autónomas son optativas; las aplicaciones supervisadas deben representar las solicitudes pendientes de permiso y de pregunta.

La proyección autónoma mantiene pendientes los permisos isolation_escalation, bash_destructive, ops_approve, webmcp, hook y computer, así como cualquier solicitud cuyos metadatos establezcan requireInteractive: true. Los consumidores deben obtener una respuesta humana explícita para estas solicitudes.

gRPC y escritorio nativo

Usa @defai-digital/ax-code-sdk/grpc cuando un host nativo ya es dueño del transporte (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 de structured-clone (preload / Tauri).
• createAxCodeGrpcClientFromNativeBridge() — el mismo ámbito de JavaScript, con AbortSignal e iterables asíncronos.
• createAxCodeGrpcClientFromNativeHandlers() — vincula nombres de método a manejadores tipados; requireHandlers falla de inmediato ante huecos.
• startAxCodeGrpcNodeHttp2Server() desde @defai-digital/ax-code-sdk/grpc/node — expone el mismo puente como endpoint gRPC HTTP/2 local.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — catálogo canónico de métodos para listas de permitidos y nombres proto.

createAxCodeGrpcClientFromHttp() es solo loopback. El activo proto es packages/sdk/proto/ax_code/v1/headless.proto y se resuelve en tiempo de ejecución con resolveAxCodeGrpcProtoUrl().

Agente en proceso (solo hosts de código fuente)

Esta vía exige el paquete privado del entorno de ejecución ax-code. No es el límite público de integración de aplicaciones.

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

La autenticación se detecta de forma automática a partir de variables de entorno, se inyecta mediante auth: { provider, apiKey } o se toma de 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`)
}

Más ejemplos: example/programmatic.ts.

Pruebas

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

Compatibilidad de versiones

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

Controles de solicitud y dirección

El SDK 2.6 añade controles opcionales a las solicitudes headless. Las llamadas existentes conservan su comportamiento; no se impone un plazo predeterminado.

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) expone el endpoint atómico de seguimiento en cola. Su resultado generation_not_active deja la fila sin cambios. El SDK devuelve recibos y motivos de rechazo tal cual. accepted significa admitido para un límite de bucle posterior; applied significa admitido de forma durable en ese límite, con la finalización del proveedor todavía aparte. Los recibos son locales al proceso y están acotados, así que su ausencia después de un reinicio no prueba que una corrección no se aplicara nunca.

requestOptions aporta valores predeterminados para todas las solicitudes y comandos de conveniencia headless, incluidas las operaciones de flujo de trabajo y de cola de tareas. Los métodos centrales de sesión y comando, y la dirección, aceptan anulaciones por llamada; timeoutMs: 0 desactiva un plazo predeterminado. Las suscripciones usan su propio signal, y client.client conserva los controles del cliente generado. Un HeadlessTransport personalizado recibe la señal y debe liberar sus recursos pendientes cuando se aborta.

La cancelación HTTP e IPC detiene la espera local. Una mutación ya despachada aún puede ejecutarse; reconcilia el estado de la sesión y de la cola antes de actuar más. Ninguno de los dos transportes reintenta mutaciones. Los plazos elevan TimeoutError; los abortos del llamador conservan el motivo de la señal. Las respuestas HTTP e IPC que no son de éxito elevan HeadlessRequestError con status, body, method y path; los marcos de error de protocolo IPC conservan IpcTransportError.

Compatibilidad del entorno de ejecución y actualización desde el SDK 2.5

La línea base actual del contrato generado es el código fuente de AX Code v7.23.0. El SDK 2.6 no infiere funciones no anunciadas a partir de la versión del entorno de ejecución. El catálogo de capacidad actual no anuncia la dirección por separado; comprueba el endpoint de lectura antes de ofrecer la dirección y trata los errores de ruta no admitida. El SDK 2.6 conserva los puntos de entrada generados y headless existentes. Los metadatos nuevos de error de respuesta y los controles de solicitud son aditivos; el código que captura Error sigue funcionando.

Las aplicaciones que actualizan fijaciones más antiguas deben verificar primero su entorno de ejecución firmado y luego probar la negociación de capacidad, la proyección de eventos, los permisos y preguntas pendientes, la cancelación y el apagado del backend. Los cambios de fijación del consumidor pertenecen al repositorio consumidor después de que se publique el SDK de destino. Valida el paquete compilado en local con pnpm --dir packages/sdk/js run test:consumer; esto comprueba las importaciones públicas, las declaraciones y los activos proto en un fixture aislado, sin el paquete privado de código fuente del entorno de ejecución.

Integraciones entre lenguajes

Este paquete es el SDK de primera parte de TypeScript y JavaScript. Para Python, Go, Java, Rust u otros entornos de ejecución, genera a partir del proto gRPC del repositorio o usa el límite de CLI y entorno de ejecución del que sea dueña esa integración.

Migración desde @ax-code/sdk 1.4.0

El subcamino ./programmatic sigue reexportando la entrada predeterminada; trátalo como obsoleto.

Licencia

Apache-2.0