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

Compatibilidade HTTP e OpenAPI

Status: Ativo Escopo: estado atual Última revisão: 2026-09-02 Responsável: SDK do ax-code

O AX Code tem dois caminhos de integração:

O nome do pacote JSR abaixo está pronto para lançamento, mas ainda não recebeu a primeira versão pública.

• Use @defai-digital/ax-code-sdk para integração de aplicativo TypeScript e JavaScript de primeira parte.
• Use @defai-digital/ax-code-sdk/headless ou @defai-digital/ax-code-sdk/grpc para trabalho de aplicativo e de GUI de desktop de primeira parte.
• Use ax-code serve mais o contrato OpenAPI quando outra linguagem ou um limite de processo de compatibilidade for necessário.
• Use Transporte gRPC e do SDK nativo para trabalho de GUI de desktop de primeira parte em que o AX Code é dono das duas pontas do transporte.

O caminho HTTP/OpenAPI é infraestrutura de compatibilidade e de cliente gerado. Ele permite que clientes Python, Go, Java, Rust e outros chamem a mesma API de servidor sem que o AX Code se comprometa a manter um pacote oficial completo para cada linguagem. Ele não deve ser tratado como a ponte privilegiada preferida dentro de uma GUI de desktop de primeira parte quando o contrato gRPC/nativo está disponível, e não é mais exposto como subcaminhos de primeira parte do SDK JavaScript.

Escolher um caminho

O que é oficial hoje

• @defai-digital/ax-code-sdk é o SDK TypeScript e JavaScript de primeira parte; os limites públicos de aplicativo são headless e grpc.
• @defai-digital/ax-code-sdk/grpc é a fachada opcional de primeira parte de transporte sem interface para desktop e código nativo.
• @defai-digital/ax-code-sdk/headless é o SDK de ciclo de vida e de eventos TypeScript e JavaScript de primeira parte para limites de processo de backend local.
• packages/sdk/openapi.json é o instantâneo OpenAPI para clientes HTTP gerados.
• Clientes gerados fora de JavaScript são aceitos como integrações sobre HTTP, mas não são pacotes publicados de primeira parte, salvo se existirem um responsável pelo pacote, testes e um fluxo de lançamento.

Fluxo HTTP básico

Inicie o servidor:

export AX_CODE_SERVER_PASSWORD="$(openssl rand -base64 24)"
ax-code serve --hostname=127.0.0.1 --port=4096

O auxiliar de ciclo de vida @defai-digital/ax-code-sdk/headless gera uma senha Basic Auth de uso único e liga o cliente devolvido ao cabeçalho Authorization correspondente de forma automática. Usuários manuais de ax-code serve devem definir AX_CODE_SERVER_PASSWORD de forma explícita e enviar o cabeçalho Basic Auth correspondente. A documentação OpenAPI ao vivo em /doc e todos os endpoints do servidor são somente loopback.

Auxiliares de backend administrados pelo SDK sempre rejeitam nomes de host de rede como 0.0.0.0. A opção legada allowNetworkBind permanece para compatibilidade de código-fonte, mas não contorna mais a política somente local. Shells de GUI de desktop devem preferir @defai-digital/ax-code-sdk/grpc ou um limite de SDK no processo.

Auxiliares de runtime HTTP não são mais subcaminhos públicos do SDK JavaScript. O pacote ainda contém internos de cliente gerado porque @defai-digital/ax-code-sdk/headless, a contingência HTTP do gRPC e o código legado de runtime do AX Code os usam, mas integrações externas devem usar clientes sem interface, gRPC ou gerados a partir do instantâneo OpenAPI, em vez de importar valores de runtime HTTP de @defai-digital/ax-code-sdk.

Confira a saúde do servidor:

curl http://127.0.0.1:4096/global/health

Crie clientes gerados a partir do instantâneo OpenAPI depois de validar o instantâneo como JSON e OpenAPI:

openapi-python-client generate --path packages/sdk/openapi.json

oapi-codegen -package axcode -generate types,client packages/sdk/openapi.json > axcode.gen.go

openapi-generator-cli generate -i packages/sdk/openapi.json -g java -o ./ax-code-java

Travas da geração

Trate o documento OpenAPI como o contrato neutro em relação à linguagem. Não mantenha à mão grandes wrappers em torno de rotas individuais, salvo se uma camada ergonômica pequena for necessária.

Fixe juntas a versão do AX Code e a versão do cliente gerado. Se o esquema de rotas do servidor mudar, regenere o cliente e lance-o com uma nota clara de compatibilidade.

Mantenha o código gerado separado dos auxiliares escritos à mão. Arquivos gerados devem ser fáceis de substituir, enquanto arquivos escritos à mão devem guardar apenas autenticação, padrões, novas tentativas e APIs de conveniência de nível mais alto.

Preserve o comportamento do limite de serviço. Clientes fora de JavaScript usam o caminho do servidor HTTP e não recebem createAgent() no processo, execução de ferramenta personalizada em JavaScript nem utilitários @defai-digital/ax-code-sdk/testing.

Cubra as partes difíceis antes de promover um cliente gerado a status de primeira parte:

1. A validação OpenAPI roda em CI.
2. Um teste de contrato inicia ax-code serve e chama rotas representativas.
3. O comportamento de streaming ou SSE é testado se o cliente expõe APIs de evento.
4. Cabeçalhos de escopo de diretório e o comportamento de autenticação estão documentados.
5. Publicação, versionamento e responsabilidade são explícitos.

O pacote SDK inclui uma trava local leve para o instantâneo atual:

pnpm run check:openapi

O comando no nível do pacote também está disponível ao trabalhar dentro do pacote SDK:

pnpm --dir packages/sdk/js run validate:openapi

Isto valida que packages/sdk/openapi.json é JSON analisável, declara OpenAPI 3.x e contém as rotas centrais de que os clientes gerados precisam.