Référence de l'API REST

Documentation interactive

Chaque application Agent-Lab sert automatiquement une documentation OpenAPI 3 — pour l'implémentation de référence, à l'adresse http://localhost:18000/docs (ou sur votre propre application, où qu'elle s'exécute). Le catalogue ci-dessous documente les routeurs intégrés du framework ; vos extra_routers apparaissent dans le même schéma.

Authentification

Lorsque auth.enabled vaut true (voir la Référence de configuration), les routes exigent un jeton bearer Keycloak. Le routeur /auth n'est monté que lorsque l'authentification est activée :

TOKEN=$(curl -s -X POST https://<host>/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "…", "password": "…"}' | jq -r '.access_token')

curl -s https://<host>/agents/list -H "Authorization: Bearer $TOKEN" | jq

La configuration du realm et du client est décrite dans Authentification avec Keycloak.

Chemins non authentifiés : /status/*, /docs, /openapi.json, /mcp, /static, les points de terminaison OAuth well-known et le montage de la SPA — tout le reste nécessite un jeton valide.

Points de terminaison

Agents

Créez des instances de n'importe quel type d'agent enregistré ; agent_type est validé dynamiquement par rapport au registre.

Messages

Modèles de langage

Intégrations

Pièces jointes

État et MCP

Exemples de requêtes

Créer une instance d'agent — agent_name accepte [a-zA-Z0-9_-] ; agent_type doit être un type enregistré ; language_model_id est facultatif :

curl -s -X POST http://localhost:18000/agents/create \
  -H "Content-Type: application/json" \
  -d '{
        "agent_name": "support-agent-1",
        "agent_type": "coordinator_planner_supervisor",
        "language_model_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      }' | jq

Envoyer un message — message_role vaut human, assistant ou tool ; attachment_id est facultatif :

curl -s -X POST http://localhost:18000/messages/post \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "message_role": "human",
        "message_content": "Summarize the attached report.",
        "attachment_id": null
      }' | jq

Mettre à jour un paramètre d'agent — setting_key accepte [a-zA-Z_-] ; setting_value contient jusqu'à 16 000 caractères (les templates de prompts et les charges utiles JSON se trouvent ici — voir le Modèle de domaine des entités) :

curl -s -X POST http://localhost:18000/agents/update_setting \
  -H "Content-Type: application/json" \
  -d '{
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "setting_key": "system_prompt",
        "setting_value": "You are a concise research assistant…"
      }' | jq

Conventions

• Les ID sont des UUID ; tous les points de terminaison de liste acceptent des corps JSON, et non des query strings.
• Les paramètres sont des paires clé-valeur persistées avec l'agent ou le modèle — c'est ainsi qu'une même implémentation peut faire tourner de nombreuses instances configurées différemment.
• Le registre fait foi pour les valeurs valides de agent_type — appelez GET /agents/types pour voir ce que l'application en cours d'exécution a découvert (y compris vos propres packages via scan_packages).