Documentazione dell'API
Tutto quello che serve per integrare AgileLLM: una rotta OpenAI-compatibile, una chiave per prodotto e per tenant, streaming a frase, misura d'uso. La porta è l'unica che sa dire chi ha risposto davvero.
Basi e autenticazione
Base URL: https://api.agilellm.agile.software/v1.
La chiave si passa nell'intestazione Authorization: Bearer <chiave> (il client OpenAI) o X-API-Key: <chiave>. Ogni chiave ha ambiti (chat, uso), un ritmo (richieste al minuto) e una quota di token al mese; si ruota (24 ore di sovrapposizione) e si revoca.
Authorization: Bearer all_…
X-Api-Key: all_…Endpoint
GET/health — stato del servizio
Senza chiave. Dice se il servo è su (ok, altrimenti 503), lo stato (ok, caricamento, giù), il peso e il contesto caricati, gli slot, la VRAM, le richieste e gli errori del mese. È la rotta che il serverino vigila.
GET/v1/models — modelli disponibili
Elenca i modelli realmente disponibili su questa istanza.
POST/v1/chat/completions — la conversazione
Formato OpenAI, con stream (pezzi data: {…}, chiusi da data: [DONE]) o senza (un JSON solo).
B=https://api.agilellm.agile.software; K=all_…
curl -s -X POST $B/v1/chat/completions -H "Authorization: Bearer $K" \
-H 'Content-Type: application/json' -d '{
"model": "agilellm", "stream": true, "max_tokens": 120,
"messages": [{"role": "system", "content": "Sei Nadia, addetta all'accoglienza."},
{"role": "user", "content": "Quando siete aperti?"}]}'from openai import OpenAI
c = OpenAI(api_key="all_…", base_url="https://api.agilellm.agile.software/v1")
for pezzo in c.chat.completions.create(model="agilellm", stream=True, max_tokens=120,
extra_body={"a_frase": True},
messages=[{"role": "user", "content": "Quando siete aperti?"}]):
if pezzo.choices and pezzo.choices[0].delta.content:
print(pezzo.choices[0].delta.content)GET/v1/chiave — la scheda della chiave
Ambiti, quota, usati e residui (mai il valore della chiave), famiglia.
GET/v1/uso — la misura d'uso del mese
Richieste, errori, token del prompt e della risposta, millisecondi. Si registra solo quando, quale chiave, quale modello e motore, stato, tempi e conteggi: mai i testi, né domanda né risposta.
Streaming a frase
Con "a_frase": true nel corpo (o X-A-Frase: si) i pezzi escono a frasi chiuse, come nel cervello a flusso di AgileVolto: la voce parte alla prima frase senza aspettare la risposta intera. Ogni pezzo porta agilellm.frase (1, 2, …).
Che cosa torna sempre
X-Motore-Cervello: agilellm/<modello>— chi ha risposto davvero.X-Chiave-Id— la chiave usata;X-Quota-Avvisoquando si è sopra l'80 % della quota del mese.X-Chiave-ScadeeX-Chiave-Nuova— solo con una chiave ruotata ancora nelle 24 ore.
404, mai la risposta di un altro cervello. Se il servo principale non risponde e la sede ha una riserva sovrana (un secondo modello nostro), risponde lei e lo dice: X-Ripiego: riserva: <perché>, X-Motore-Cervello col suo modello, agilellm.ripiego nel corpo. Una chiave può vietarlo (ripiego=nessuno): arriva 502 servo_non_pronto. Mai un fornitore esterno.Errori
Ogni errore ha la forma di OpenAI, con error.code in italiano.
| HTTP | code | che fare |
|---|---|---|
| 401 | chiave_mancante, chiave_sconosciuta, chiave_scaduta | mettere la chiave; dopo una rotazione usare la nuova. |
| 403 | chiave_revocata, ambito_non_ammesso | chiedere una chiave nuova o l'ambito che manca. |
| 404 | modello_sconosciuto, rotta_sconosciuta | chiedere agilellm. |
| 429 | troppo_frequente, quota_superata | rallentare, o chiedere un ritmo/quota più alti. |
| 400 | richiesta_non_valida | il corpo non ha messages; oppure il servo ha rifiutato la richiesta: correggere, non riprovare uguale. |
| 502 | servo_non_pronto | il servo è giù o sta caricando: riprovare fra qualche secondo. |
| 502 | servo_interrotto | il servo si è fermato a metà: nel flusso arriva come ultimo pezzo e senza [DONE]. |