Cette page est traduite de la documentation anglaise. Les commandes, identifiants et exemples sont inchangés. Runtime 7.24.4 · SDK 2.6.7. Source anglaise

Compatibilité HTTP et OpenAPI

Statut : Actif Portée : état actuel Dernière revue : 2026-09-02 Responsable : sdk ax-code

AX Code a deux chemins d’intégration :

Le nom de paquet JSR ci-dessous est prêt pour une publication, mais n’a pas encore reçu sa première version publique.

• Utilisez @defai-digital/ax-code-sdk pour l’intégration d’applications TypeScript et JavaScript de première partie.
• Utilisez @defai-digital/ax-code-sdk/headless ou @defai-digital/ax-code-sdk/grpc pour le travail d’application et d’interface de bureau de première partie.
• Utilisez ax-code serve plus le contrat OpenAPI lorsqu’une autre langue ou une frontière de processus de compatibilité est exigée.
• Utilisez Transport SDK natif pour le travail d’interface de bureau de première partie lorsque AX Code possède les deux extrémités du transport.

Le chemin HTTP/OpenAPI est une infrastructure de compatibilité et de clients générés. Il permet à Python, Go, Java, Rust et d’autres clients d’appeler la même API serveur sans qu’AX Code s’engage à maintenir un paquet officiel complet pour chaque langue. Il ne doit pas être traité comme le pont privilégié préféré à l’intérieur d’une interface de bureau de première partie lorsque le contrat gRPC/natif est disponible, et il n’est plus exposé comme sous-chemins du SDK JavaScript de première partie.

Choisir un chemin

Ce qui est officiel aujourd'hui

• @defai-digital/ax-code-sdk est le SDK TypeScript et JavaScript de première partie ; ses frontières d’application publiques sont headless et grpc.
• @defai-digital/ax-code-sdk/grpc est la façade de transport sans interface, de bureau ou native, facultative et de première partie.
• @defai-digital/ax-code-sdk/headless est le SDK de cycle de vie et d’événements TypeScript et JavaScript de première partie pour les frontières de processus de moteur local.
• packages/sdk/openapi.json est l’instantané OpenAPI pour les clients HTTP générés.
• Les clients générés hors JavaScript sont pris en charge comme intégrations sur HTTP, mais ce ne sont pas des paquets publiés de première partie, sauf si un responsable de paquet, des tests et un flux de publication existent.

Flux HTTP de base

Démarrez le serveur :

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

L’assistant de cycle de vie @defai-digital/ax-code-sdk/headless génère un mot de passe Basic Auth à usage unique et branche le client renvoyé avec l’en-tête Authorization correspondant, automatiquement. Les utilisateurs manuels de ax-code serve doivent définir AX_CODE_SERVER_PASSWORD explicitement et envoyer l’en-tête Basic Auth correspondant. La documentation OpenAPI en direct à /doc et tous les points de terminaison du serveur sont limités à la boucle locale.

Les assistants de moteur gérés par le SDK rejettent toujours les noms d’hôte réseau tels que 0.0.0.0. L’option héritée allowNetworkBind est conservée pour la compatibilité des sources, mais ne contourne plus la politique locale seulement. Les enveloppes d’interface de bureau doivent préférer @defai-digital/ax-code-sdk/grpc ou une frontière de SDK dans le processus.

Les assistants du runtime HTTP ne sont plus des sous-chemins publics du SDK JavaScript. Le paquet contient encore des internes de client généré parce que @defai-digital/ax-code-sdk/headless, le repli HTTP de gRPC et le code hérité du runtime AX Code les utilisent, mais les intégrations externes doivent utiliser le mode sans interface, gRPC ou des clients générés depuis l’instantané OpenAPI, au lieu d’importer des valeurs du runtime HTTP depuis @defai-digital/ax-code-sdk.

Vérifiez la santé du serveur :

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

Créez des clients générés depuis l’instantané OpenAPI après avoir validé l’instantané comme JSON et 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

Gardes de génération

Traitez le document OpenAPI comme le contrat neutre vis-à-vis du langage. Ne maintenez pas à la main de grands enrobages autour de routes individuelles, sauf si une petite couche ergonomique est nécessaire.

Épinglez ensemble la version d’AX Code et la version du client généré. Si le schéma de routes du serveur change, régénérez le client et publiez-le avec une note de compatibilité claire.

Gardez le code généré séparé des assistants écrits à la main. Les fichiers générés doivent être faciles à remplacer, tandis que les fichiers écrits à la main ne doivent contenir que l’authentification, les valeurs par défaut, les nouvelles tentatives et les API de commodité de plus haut niveau.

Préservez le comportement de frontière de service. Les clients hors JavaScript utilisent le chemin du serveur HTTP et n’obtiennent pas createAgent() dans le processus, l’exécution d’outils personnalisés JavaScript, ni les utilitaires @defai-digital/ax-code-sdk/testing.

Couvrez les parties difficiles avant de promouvoir un client généré au statut de première partie :

1. La validation OpenAPI s’exécute en CI.
2. Un test de contrat démarre ax-code serve et appelle des routes représentatives.
3. Le comportement de flux ou SSE est testé si le client expose des API d’événements.
4. Les en-têtes de portée de répertoire et le comportement d’authentification sont documentés.
5. La publication, le versionnage et la responsabilité sont explicites.

Le paquet SDK inclut une garde locale légère pour l’instantané courant :

pnpm run check:openapi

La commande au niveau du paquet est aussi disponible lorsque vous travaillez dans le paquet SDK :

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

Cela valide que packages/sdk/openapi.json est du JSON analysable, déclare OpenAPI 3.x et contient les routes centrales nécessaires aux clients générés.