API

Base URL predefinito: http://localhost:8000. Documentazione interattiva generata da FastAPI: /docs.

---

Contratto del sistema multi-agent

Il sistema si aspetta in input una richiesta testuale chiara, associata a un user_id e, quando si vuole continuita, a un thread_id.

In pratica:

• input minimo: un messaggio (message) che descriva bene obiettivo, contesto e vincoli;
• **identita**: user_id` serve per separare memoria e tracce;
• **continuita**: riusa thread_id` per proseguire la stessa conversazione;
• workflow dedicati: per casi strutturati come il sollecito o l'onboarding usa gli endpoint specifici, non la chat generica.

Come dovrebbe essere l'input

L'input funziona meglio quando contiene:

• il goal: cosa vuoi ottenere;
• il contesto: situazione, stato della relazione, dati utili;
• i vincoli: tono, tempi, limiti, informazioni da non inventare;
• se serve, l'output desiderato: risposta breve, bozza, analisi, elenco.

Esempio buono:

{
  "user_id": "fabio",
  "thread_id": "thread-123",
  "message": "Devo rispondere a un cliente in ritardo di pagamento. Tono fermo ma non aggressivo. Proponi un testo breve WhatsApp."
}

Esempio debole:

{
  "message": "scrivi qualcosa"
}

Cosa produce in output

Il sistema restituisce una risposta finale piu metadati utili a capire **come** ci e arrivato:

• response: testo finale per l'utente;
• thread_id: id conversazione da riusare;
• run_id: id esecuzione per osservabilita` e debug;
• agents_used: agenti coinvolti;
• stop_reason: motivo di chiusura;
• route_history: deleghe e decisioni del supervisore;
• usage: token, costo, durata, errori, numero di chiamate LLM/tool.

API di riferimento

• chat standard: POST /api/chat
• chat streaming: POST /api/chat/stream
• workflow sollecito: POST /api/sollecito
• registrazione esito sollecito: POST /api/sollecito/outcome
• workflow onboarding: POST /api/onboarding
• setup cliente salvato: GET /api/onboarding/setup
• storico conversazioni: GET /api/threads, GET /api/threads/{id}
• **osservabilita**: GET /api/runs, GET /api/runs/{id}`
• topologia / agenti / tool: GET /api/graph, GET /api/graph/agents, GET /api/graph/tools

---

Conversazione

POST /api/chat

Esegue un turno completo e attende la risposta.

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Quanto fa 17% di 4.320?", "user_id": "fabio"}'

{
  "thread_id": "7c1e…",
  "run_id": "0f9a…",
  "response": "Il 17% di 4.320 è 734,4.",
  "agents_used": ["analyst"],
  "stop_reason": "finish",
  "route_history": [
    {
      "turn": 1,
      "agent": "analyst",
      "instruction": "Calcola il 17% di 4320",
      "reason": "Richiesta numerica: serve un calcolo esatto."
    }
  ],
  "usage": {
    "input_tokens": 1840,
    "output_tokens": 96,
    "total_tokens": 1936,
    "cost_usd": 0.006984,
    "llm_calls": 3,
    "tool_calls": 1,
    "agents_used": ["analyst"],
    "duration_ms": 4210,
    "errors": []
  }
}

Passando lo stesso thread_id nella chiamata successiva la conversazione prosegue con tutta la memoria.

POST /api/chat/stream

Stessi parametri, risposta in Server-Sent Events.

curl -N -X POST http://localhost:8000/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Fammi una sintesi del progetto"}'

---

Sollecito

Workflow lineare separato dal chat multi-agent. Sceglie la tipologia in base alla memoria degli esiti e a una strategia standard a scalata, poi produce una bozza.

POST /api/sollecito

curl -X POST http://localhost:8000/api/sollecito \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "fabio",
    "goal": "Ottenere una data di pagamento entro questa settimana",
    "context": "Cliente con fattura scaduta da 12 giorni, rapporto buono.",
    "history": "Giorno 1: promemoria gentile senza risposta. Giorno 5: ha promesso di pagare venerdì."
  }'

Risposta (campi principali): nudge_type, type_reason, strategy, draft_body, next_checkpoint, memory_hits.

POST /api/sollecito/outcome

Registra se il sollecito ha funzionato → memoria kind=nudge_outcome.

curl -X POST http://localhost:8000/api/sollecito/outcome \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "fabio",
    "nudge_type": "commitment_recall",
    "worked": true,
    "goal": "Ottenere una data di pagamento entro questa settimana",
    "note": "Ha risposto in 2 ore con bonifico programmato"
  }'

---

Onboarding

Workflow conversazionale separato dal chat multi-agent. Conduce l'intervista della skill lia-onboarding-setup: tono, lingua, policy di sollecito, canali, testi, piani di rientro e comportamento del team agentico. Una domanda alla volta, default già valorizzati. A conferma salva client_setup e team_policy.

POST /api/onboarding

Ogni chiamata è un turno. Riusa thread_id per continuare. message vuoto avvia l'intervista.

curl -X POST http://localhost:8000/api/onboarding \
  -H "Content-Type: application/json" \
  -d '{"user_id": "fabio"}'

curl -X POST http://localhost:8000/api/onboarding \
  -H "Content-Type: application/json" \
  -d '{"user_id": "fabio", "thread_id": "…", "message": "ok"}'

Risposta: response (testo di Lia), step, mode (setup o edit), completed, saved, setup (JSON interno, non mostrato in chat).

GET /api/onboarding/setup?user_id=fabio

Restituisce il setup già salvato, se esiste.

GET /api/onboarding/topology

Topologia del grafo per la vista Workflow.

---

Conversazioni

---

Osservabilità

---

Configurazione del sistema

---

Memoria a lungo termine

---

Stato

GET /api/health

{
  "status": "ok",
  "version": "0.1.0",
  "environment": "development",
  "database": { "enabled": true, "reason": null },
  "checkpointer": { "persistent": true, "type": "postgres" },
  "agents": ["general", "researcher", "analyst", "writer"],
  "tracing_enabled": true
}

---

Errori

Autenticazione

Non è prevista: il backend è pensato per stare dietro al tuo perimetro. Prima di esporlo pubblicamente aggiungi autenticazione (dipendenza FastAPI o reverse proxy) e sostituisci user_id nel corpo della richiesta con l'identità verificata del chiamante.