Riferimento della REST API

Documentazione interattiva

Ogni applicazione Agent-Lab espone automaticamente la specifica OpenAPI 3: per l'implementazione di riferimento su http://localhost:18000/docs (o ovunque venga eseguita la tua app). Il catalogo seguente documenta i router integrati nel framework; i tuoi extra_routers compaiono nello stesso schema.

Autenticazione

Quando auth.enabled è true (vedi il Riferimento della configurazione), le route richiedono un bearer token di Keycloak. Il router /auth viene montato solo quando l'autenticazione è abilitata:

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 configurazione di realm e client è descritta in Autenticazione con Keycloak.

Path non autenticati: /status/*, /docs, /openapi.json, /mcp, /static, gli endpoint OAuth well-known e il mount della SPA; tutto il resto richiede un token valido.

Endpoint

Agenti

Crea istanze di qualsiasi tipo di agente registrato; agent_type viene validato dinamicamente rispetto al registro.

Messaggi

Modelli linguistici

Integrazioni

Allegati

Stato e MCP

Esempi di richiesta

Creare un'istanza di agente: agent_name accetta [a-zA-Z0-9_-]; agent_type deve essere un tipo registrato; language_model_id è facoltativo:

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

Inviare un messaggio: message_role è uno tra human, assistant, tool; attachment_id è facoltativo:

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

Aggiornare un'impostazione di un agente: setting_key accetta [a-zA-Z_-]; setting_value contiene fino a 16.000 caratteri (qui risiedono i template dei prompt e i payload JSON; vedi il Modello di dominio delle entità):

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

Convenzioni

• Gli ID sono UUID; tutti gli endpoint di elenco accettano body JSON, non query string.
• Le impostazioni sono coppie chiave-valore persistite insieme all'agente o al modello: è così che la stessa implementazione esegue molte istanze configurate in modo diverso.
• Il registro è la fonte di verità per i valori validi di agent_type: esegui GET /agents/types per vedere cosa ha individuato l'app in esecuzione (inclusi i tuoi package tramite scan_packages).