Aller au contenu principal

Intégrer Apollia via le contrat de pilotage

Ce guide s'adresse aux équipes qui embarquent un runtime Apollia dans un produit. Il couvre le contrat que votre application hôte pilote : l'API HTTP, sa garantie de stabilité, l'authentification et les clients générés. Il suppose que vous savez faire tourner un daemon Apollia et que vous voulez le raccorder à une application.

Si vous voulez simplement voir le flux fonctionner une fois, commencez par Piloter Apollia depuis votre produit.

Le contrat​

Un runtime Apollia expose ses capacités via une API HTTP sous /api/v1 : soumettre des tâches, ouvrir des sessions de chat, diffuser des résultats en continu, consulter le journal d'audit et administrer le runtime.

Le daemon lancé par apollia-os start écoute sur un socket Unix et sur 127.0.0.1:7771. Le TCP est lié à chaque démarrage ; --port ne fait que choisir le numéro.

L'API est décrite par une spécification OpenAPI 3.1 générée à partir du code source du runtime : elle ne peut donc pas diverger du code. Le runtime la sert à cette adresse :

GET /api/v1/openapi.json

Une copie versionnée existe aussi dans clients/openapi.json. Pour une vue navigable de chaque opération, consultez la référence de l'API HTTP, générée à partir de cette même spécification.

Garantie de stabilité​

/api/v1 est le contrat versionné, et le document OpenAPI de chaque version le décrit exactement. Avant la 1.0, une version peut encore retirer ou changer une opération de v1, et chacun de ces changements est listé avec sa migration sous « Breaking changes and migration » dans le journal des modifications. La 0.3.0 a retiré les routes des projets (dont PUT /api/v1/sessions/{id}/project et GET /api/v1/projects/{id}/sessions, et le champ project de POST /api/v1/sessions), la route des approbations résolues et PUT /api/v1/onboarding/profile. Lisez cette section avant de mettre à jour le runtime sous une intégration.

Authentification​

Choisissez la surface adaptée à votre déploiement :

  • Socket Unix : confiance locale. L'accès est régi par les permissions du système de fichiers, aucun jeton n'est requis. À utiliser quand l'hôte et le runtime partagent la même machine et le même périmètre de confiance.
  • TCP sur 127.0.0.1 : authentifié par jeton. Chaque requête doit porter l'en-tête Authorization: Bearer <token>. Au premier démarrage, quand [api] require_token est activé (c'est le comportement par défaut), le daemon génère un jeton et l'écrit dans ~/.apollia/api-token avec des permissions réservées au propriétaire. Votre hôte lit ce fichier et transmet le jeton.

Le runtime que l'application desktop embarque se lie lui aussi aux deux surfaces : le socket Unix, et un port TCP sur 127.0.0.1 ([api] port, 7771 par défaut) où le jeton est exigé.

Utiliser un client généré​

Deux clients de pilotage côté hôte sont générés à partir de la spécification OpenAPI et vivent sous clients/. Les deux sont générés, pas écrits à la main, ce qui les maintient synchronisés avec le contrat. Ne modifiez jamais un fichier généré à la main : changez le runtime, puis régénérez.

ClientCheminChaîne d'outils
TypeScriptclients/tstypes openapi-typescript plus openapi-fetch
Pythonclients/pythonopenapi-python-client

Aucun des deux n'est publié sur un registre, il n'existe donc pas de commande d'installation pour l'un ou pour l'autre. Les deux se consomment depuis une copie du dépôt. @apollia/runtime-client déclare comme point d'entrée ses propres sources TypeScript : dépendez de clients/ts par chemin (une dépendance file:, ou une entrée d'espace de travail) et laissez votre bundler le compiler ; il tire openapi-fetch. clients/python est généré avec --meta none : il ne porte donc pas de pyproject.toml et pip install n'a rien à lire. Placez son répertoire parent sur PYTHONPATH ou copiez clients/python/apollia_runtime_client dans votre projet, et installez httpx et attrs vous-même.

TypeScript​

import { readFileSync } from "node:fs";
import { homedir } from "node:os";
import { createApolliaClient } from "@apollia/runtime-client";

const token = readFileSync(`${homedir()}/.apollia/api-token`, "utf8").trim();
const apollia = createApolliaClient({ token }); // baseUrl vaut 127.0.0.1:7771 par défaut

const health = await apollia.GET("/api/v1/health");

const submit = await apollia.POST("/api/v1/tasks", {
  body: {
    agent_id: "coach",
    input: { parts: [{ type: "text", text: "hello from the host" }] },
  },
});

Chaque opération est typée contre le contrat, si bien que la forme des requêtes et des réponses est vérifiée à la compilation. agent_id nomme un agent installé ; coach est celui que construit Votre premier agent.

Python​

import pathlib
from apollia_runtime_client import AuthenticatedClient
from apollia_runtime_client.api.tasks import submit_task, get_task
from apollia_runtime_client.models import SubmitTaskRequest, SubmitTaskRequestInput

token = (pathlib.Path.home() / ".apollia" / "api-token").read_text().strip()
client = AuthenticatedClient(base_url="http://127.0.0.1:7771", token=token)

resp = submit_task.sync(client=client, body=SubmitTaskRequest(
    agent_id="coach",
    input_=SubmitTaskRequestInput.from_dict(
        {"parts": [{"type": "text", "text": "hello"}]}
    ),
))
task = get_task.sync(id=resp.task_id, client=client)

Diffuser les résultats en continu​

Au-delà du modèle soumettre-puis-interroger, le contrat expose des flux d'événements serveur (server-sent events) pour les traitements longs : la sortie d'une tâche à GET /api/v1/tasks/{id}/stream et la sortie d'une session de chat à GET /api/v1/sessions/{id}/stream. GET /api/v1/events diffuse le bus d'événements du runtime tout entier, pour un hôte qui suit chaque exécution plutôt qu'une seule. Consultez la référence de l'API HTTP pour la forme de leurs événements.

Régénérer les clients​

Quand le contrat du runtime change, actualisez les clients à partir de la spécification :

# À partir de la spécification versionnée :
bash clients/regen.sh

# Ou actualisez d'abord la spécification depuis un daemon en cours d'exécution :
bash clients/regen.sh --from-daemon

Voir aussi​