Questa pagina è tradotta dalla documentazione inglese. Comandi, identificatori ed esempi restano invariati. Runtime 7.24.4 · SDK 2.6.7. Testo inglese

Compatibilità HTTP e OpenAPI

Stato: attivo Ambito: stato attuale Ultima revisione: 2026-09-02 Responsabile: SDK di ax-code

AX Code ha due percorsi di integrazione:

Il nome del pacchetto JSR qui sotto è pronto per il rilascio, ma non ha ancora ricevuto la prima versione pubblica.

Usa @defai-digital/ax-code-sdk per l’integrazione di app TypeScript e JavaScript di prima parte.
Usa @defai-digital/ax-code-sdk/headless oppure @defai-digital/ax-code-sdk/grpc per il lavoro di app e di GUI desktop di prima parte.
Usa ax-code serve più il contratto OpenAPI quando serve un altro linguaggio o un confine di processo di compatibilità.
Usa Trasporto SDK nativo per il lavoro di GUI desktop di prima parte in cui AX Code possiede entrambe le estremità del trasporto.

Il percorso HTTP/OpenAPI è infrastruttura di compatibilità e di client generati. Permette a client Python, Go, Java, Rust e ad altri client di chiamare la stessa API del server senza che AX Code si impegni a mantenere un pacchetto ufficiale completo per ogni linguaggio. Non va trattato come il ponte privilegiato preferito dentro una GUI desktop di prima parte quando il contratto gRPC/nativo è disponibile, e non è più esposto come sottopercorsi dell’SDK JavaScript di prima parte.

Scegliere un percorso

Esigenza	Percorso consigliato	Motivo
TypeScript o JavaScript nello stesso processo	adattatore del workspace sorgente `createAgent()`	Disponibile solo quando il pacchetto sorgente privato del runtime di AX Code è risolvibile di proposito
GUI desktop o nativa di prima parte	`@defai-digital/ax-code-sdk/grpc`	Contratto headless più stretto, streaming dal server, adatto a metadati e scadenze, e minore esposizione della WebView
TypeScript o JavaScript con un backend locale	`@defai-digital/ax-code-sdk/headless`	Mantiene tipizzati il ciclo di vita e la proiezione degli eventi, senza esporre l’intera superficie HTTP dell’SDK
Python, Go, Java, Rust o un altro runtime	Genera un client da `packages/sdk/openapi.json`	Riutilizza il contratto HTTP senza aggiungere manutenzione di pacchetti di prima parte per ogni linguaggio
CI, automazione o script occasionali	Chiamate HTTP verso `ax-code serve`	Modello di distribuzione semplice e isolamento dei processi agevole

Che cosa è ufficiale oggi

@defai-digital/ax-code-sdk è l’SDK TypeScript e JavaScript di prima parte; i suoi confini pubblici per le app sono headless e grpc.
@defai-digital/ax-code-sdk/grpc è la facciata facoltativa di prima parte per il trasporto headless desktop/nativo.
@defai-digital/ax-code-sdk/headless è l’SDK di prima parte, in TypeScript e JavaScript, per ciclo di vita ed eventi sui confini di processo del backend locale.
packages/sdk/openapi.json è l’istantanea OpenAPI per i client HTTP generati.
I client generati non JavaScript sono supportati come integrazioni su HTTP, ma non sono pacchetti pubblicati di prima parte, a meno che esistano un responsabile del pacchetto, test e un workflow di rilascio.

Flusso HTTP di base

Avvia il server:

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

L’helper di ciclo di vita @defai-digital/ax-code-sdk/headless genera una password Basic Auth monouso e collega il client restituito con l’intestazione Authorization corrispondente in modo automatico. Chi usa ax-code serve manualmente deve impostare AX_CODE_SERVER_PASSWORD in modo esplicito e inviare l’intestazione Basic Auth corrispondente. La documentazione OpenAPI in esecuzione su /doc e tutti gli endpoint del server sono soltanto in loopback.

Gli helper di backend gestiti dall’SDK rifiutano sempre nomi host di rete come 0.0.0.0. L’opzione legacy allowNetworkBind è conservata per la compatibilità del sorgente, ma non aggira più la policy solo locale. Le shell delle GUI desktop dovrebbero preferire @defai-digital/ax-code-sdk/grpc oppure un confine SDK nello stesso processo.

Gli helper di runtime HTTP non sono più sottopercorsi pubblici dell’SDK JavaScript. Il pacchetto contiene ancora gli interni del client generato perché li usano @defai-digital/ax-code-sdk/headless, il fallback HTTP di gRPC e il codice legacy del runtime di AX Code, ma le integrazioni esterne devono usare client headless, gRPC o generati dall’istantanea OpenAPI, invece di importare valori di runtime HTTP da @defai-digital/ax-code-sdk.

Controlla lo stato del server:

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

Crea client generati dall’istantanea OpenAPI dopo aver validato l’istantanea come JSON e come 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

Barriere di generazione

Tratta il documento OpenAPI come il contratto neutrale rispetto al linguaggio. Non mantenere a mano grandi wrapper attorno alle singole route, a meno che serva un piccolo livello ergonomico.

Fissa insieme la versione di AX Code e la versione del client generato. Se lo schema delle route del server cambia, rigenera il client e rilascialo con una nota di compatibilità chiara.

Tieni il codice generato separato dagli helper scritti a mano. I file generati devono essere facili da sostituire, mentre i file scritti a mano devono contenere soltanto autenticazione, valori predefiniti, tentativi ripetuti e API di comodità di livello più alto.

Conserva il comportamento del confine di servizio. I client non JavaScript usano il percorso del server HTTP e non ottengono createAgent() nello stesso processo, l’esecuzione di strumenti personalizzati JavaScript né le utilità @defai-digital/ax-code-sdk/testing.

Copri le parti difficili prima di promuovere un client generato allo stato di prima parte:

La validazione OpenAPI gira in CI.
Un test di contratto avvia ax-code serve e chiama route rappresentative.
Il comportamento di streaming o SSE è testato se il client espone API di eventi.
Le intestazioni di ambito delle directory e il comportamento di autenticazione sono documentati.
Pubblicazione, versionamento e responsabilità sono espliciti.

Il pacchetto SDK include un controllo locale leggero per l’istantanea corrente:

pnpm run check:openapi

Il comando a livello di pacchetto è disponibile anche quando si lavora dentro il pacchetto SDK:

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

Questo verifica che packages/sdk/openapi.json sia JSON analizzabile, dichiari OpenAPI 3.x e contenga le route principali necessarie ai client generati.