Esta página é uma tradução da documentação em inglês. Comandos, identificadores e exemplos permanecem iguais. Runtime 7.24.4 · SDK 2.6.7. Original em inglês

Pacote @defai-digital/ax-code-sdk

SDK em TypeScript para integrar o runtime de agente de programação do AX Code aos seus próprios aplicativos.

Use-o para supervisionar um runtime assinado e compatível do AX Code por fronteiras tipadas sem interface ou gRPC, consumir eventos em fluxo, projetar o estado da sessão e testar integrações de aplicativo. Hosts de código-fonte que fornecem de propósito o pacote privado do runtime também podem usar o adaptador no processo createAgent().

Instalação

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+ (ou Deno com compatibilidade de Node). Versões mais antigas do Node.js não são suportadas. Os auxiliares de ciclo de vida sem interface e gRPC esperam um executável assinado ax-code em PATH, ou um caminho absoluto passado como binary. As versões do SDK e do runtime são independentes. Confira o protocolo de capacidade do runtime antes de ativar recursos do aplicativo; conferir apenas a versão do SDK não estabelece compatibilidade do runtime.

O nome de pacote do workspace, @ax-code/sdk, é privado deste monorepositório. Quem consome de forma pública sempre instala @defai-digital/ax-code-sdk a partir do JSR.

Migração da API de relatório

O AX Code 7.24.1 substitui o relatório de grafo DRE pelo Run Report. As integrações de relatório precisam usar ax-code run-report e as rotas HTTP /run-report; o comando antigo dre-graph e as rotas /dre-graph foram removidos. As operações geradas do SDK agora são getRunReportSessionSessionId e getRunReportSessionSessionIdFingerprint, no lugar das operações getDreGraph correspondentes.

Atualize juntos a integração de relatório e o runtime. As outras superfícies de integração ainda exigem as próprias verificações de capacidade do runtime.

Escolher uma superfície de integração

Aplicativos públicos devem usar headless ou grpc com um runtime assinado e compatível do AX Code. HTTP e OpenAPI ficam por trás desses SDKs, como camada de reserva e de diagnóstico. Os subcaminhos legados @defai-digital/ax-code-sdk/v2 permanecem para compatibilidade do runtime; integrações novas não devem começar por eles.

createAgent() carrega o pacote privado de código-fonte ax-code no momento da chamada. O runtime não é publicado no JSR.

Início rápido (sem interface)

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

Hosts de desktop podem passar um caminho absoluto verificado como binary. Veja example/headless-app.ts para um laço de aplicativo baseado em projeção.

Backend sem interface

startHeadlessBackend inicia ax-code serve em uma porta loopback aleatória, gera uma credencial de uso único, espera /global/health e devolve um handle. close() envia SIGTERM e, em seguida, 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 e applyHeadlessProjectionEvent são TypeScript puro. As interfaces de aplicativo devem tratar permission, question, session_diff, todo, session_status e session_error como estado principal. Respostas autônomas são uma opção explícita; aplicativos supervisionados devem exibir pedidos pendentes de permissão e de pergunta.

A projeção autônoma mantém pendentes as permissões isolation_escalation, bash_destructive, ops_approve, webmcp, hook e computer, além de qualquer pedido cujo metadado defina requireInteractive: true. Quem consome precisa obter uma resposta humana explícita para esses pedidos.

gRPC e desktop nativo

Use @defai-digital/ax-code-sdk/grpc quando um host nativo já controla o transporte (preload do 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 por structured clone (preload ou Tauri).
• createAxCodeGrpcClientFromNativeBridge() — o mesmo realm JavaScript, com AbortSignal e iteráveis assíncronos.
• createAxCodeGrpcClientFromNativeHandlers() — vincula nomes de método a tratadores tipados; requireHandlers falha de imediato se houver lacunas.
• startAxCodeGrpcNodeHttp2Server() de @defai-digital/ax-code-sdk/grpc/node — expõe a mesma ponte como um endpoint gRPC HTTP/2 local.
• AX_CODE_GRPC_METHOD_DESCRIPTORS / listAxCodeGrpcMethods() — catálogo canônico de métodos para listas de permissão e nomes de proto.

createAxCodeGrpcClientFromHttp() aceita apenas loopback. O ativo proto é packages/sdk/proto/ax_code/v1/headless.proto e é resolvido em tempo de execução com resolveAxCodeGrpcProtoUrl().

Agente no processo (somente hosts de código-fonte)

Este caminho exige o pacote privado de runtime ax-code. Não é a fronteira pública de integração de aplicativos.

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

A autenticação é detectada automaticamente a partir de variáveis de ambiente, injetada por auth: { provider, apiKey } ou obtida 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`)
}

Mais exemplos: example/programmatic.ts.

Testes

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

Compatibilidade de versão

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 requisição e direcionamento

O SDK 2.6 acrescenta controles opcionais aos pedidos sem interface. As chamadas existentes conservam o comportamento; nenhum prazo padrão é imposto.

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) expõe o endpoint atômico de acompanhamento enfileirado. O resultado generation_not_active deixa a linha inalterada. O SDK devolve recibos e motivos de rejeição sem alteração. accepted significa admitido para um limite de loop posterior; applied significa admitido de forma durável nesse limite, com a conclusão no provedor ainda separada. Os recibos são locais ao processo e limitados, então a ausência deles depois de um reinício não prova que uma correção nunca foi aplicada.

requestOptions fornece padrões para todos os pedidos e comandos de conveniência sem interface, inclusive operações de fluxo de trabalho e de fila de tarefas. Os métodos centrais de sessão e de comando, e o direcionamento, aceitam substituições por chamada; timeoutMs: 0 desativa um prazo padrão. As assinaturas usam o próprio signal, e client.client conserva os controles do cliente gerado. Um HeadlessTransport personalizado recebe o sinal e deve liberar os recursos pendentes quando aborta.

O cancelamento por HTTP e por IPC interrompe a espera local. Uma mutação já despachada ainda pode ser executada; reconcilie o estado da sessão e da fila antes de agir outra vez. Nenhum dos dois transportes repete mutações. Os prazos geram TimeoutError; abortos de quem chama preservam o motivo do sinal. Respostas HTTP e IPC que não indicam sucesso geram HeadlessRequestError com status, body, method e path; quadros de erro de protocolo IPC conservam IpcTransportError.

Compatibilidade do runtime e atualização a partir do SDK 2.5

A linha de base atual do contrato gerado é o código-fonte do AX Code v7.23.0. O SDK 2.6 não infere recursos não anunciados a partir da versão do runtime. O catálogo atual de capacidades não anuncia o direcionamento em separado; confira o endpoint de leitura antes de oferecer o direcionamento e trate erros de rota não suportada. O SDK 2.6 preserva os pontos de entrada gerados e os de execução sem interface já existentes. Os metadados novos de erro de resposta e os controles de requisição são aditivos; o código que captura Error continua funcionando.

Aplicativos que atualizam versões fixadas mais antigas devem primeiro verificar o runtime assinado e, depois, testar a negociação de capacidade, a projeção de eventos, permissões e perguntas pendentes, o cancelamento e o encerramento do backend. Mudanças de versão fixada no consumidor ficam no repositório consumidor, depois que o SDK alvo é publicado. Valide o pacote compilado localmente com pnpm --dir packages/sdk/js run test:consumer; isso confere importações públicas, declarações e ativos proto em um fixture isolado, sem o pacote privado de código-fonte do runtime.

Integrações em outras linguagens

Este pacote é o SDK oficial de TypeScript e JavaScript. Para Python, Go, Java, Rust ou outros runtimes, gere a partir do proto gRPC do repositório ou use a fronteira de CLI e de runtime pertencente a essa integração.

Migração a partir de @ax-code/sdk 1.4.0

O subcaminho ./programmatic ainda reexporta a entrada padrão; trate-o como obsoleto.

Licença

Apache-2.0