# Pepper — API Agente (v1) Questo documento definisce la **modalità agente** di Pepper: multi-turno, tool-use (function calling) e streaming. È un contratto **separato e aggiuntivo** rispetto a [API.md](?f=api), che resta valido e invariato per tutti gli altri progetti. | | API classica (`/api.php`) | API agente (`/agent`) | |---|---|---| | Cosa manda il chiamante | `progetto` + `encode` + `contenuto` | `system` + `messages` + `tools` | | Istruzioni (system prompt) | le decide Pepper (le "ricette") | le decide il chiamante | | Memoria | la tiene Pepper (`conversazione`) | la tiene il chiamante (`messages`) | | Attrezzi | no | sì | | Streaming | no | sì (SSE) | **Principio**: Pepper Plus è il cervello, non le mani. Capisce, pianifica e decide quale attrezzo chiamare, ma **non esegue niente**: gli attrezzi li esegue il chiamante, con i propri permessi e le proprie conferme. ## Come si attiva La modalità agente va abilitata **per progetto** dal pannello di Pepper: **Progetti → apri il progetto → "Modalità agente"**. Un progetto in modalità "Standard" che chiama `/agent` riceve `403 agente_non_abilitato`. Un progetto in modalità agente può comunque continuare a usare `/api.php`. ## Endpoint ``` POST https://gateway.pepperai.it/agent Content-Type: application/json Accept: text/event-stream # quando stream = true X-Pepper-Key: X-Pepper-Project: ``` Funziona anche `POST /agent.php` (utile se il rewrite non è configurato — vedi [Configurazione nginx](#configurazione-nginx) in fondo). Chiave e progetto sono gli stessi di `/api.php`; qui il nome del progetto sta nell'header `X-Pepper-Project` invece che nel corpo (è accettato anche come campo `project` del corpo, come ripiego). ## Richiesta ```jsonc { "session_id": "andrea-dashboard-8f3a", // facoltativo, solo per il log "stream": true, // true = SSE, false = JSON unico "max_tokens": 1024, "system": "Sei Pepper, l'assistente di casa di Andrea. Regole: proponi le azioni, non darle per fatte; chiedi se ambiguo; sii conciso.", "messages": [ {"role": "user", "content": "prepara casa per stanotte"}, {"role": "assistant", "content": null, "tool_calls": [{"id": "c1", "name": "get_home_status", "arguments": {}}]}, {"role": "tool", "tool_call_id": "c1", "content": "{\"presenza\":\"solo Andrea\",\"cancelletto\":\"aperto\"}"} ], "tools": [ { "name": "get_home_status", "description": "Stato sintetico di casa: presenza, cancelli, clima, allarme.", "parameters": {"type": "object", "properties": {}, "required": []} }, { "name": "set_climate", "description": "Accende o spegne il condizionatore di una stanza o zona.", "parameters": { "type": "object", "properties": { "target": {"type": "string", "enum": ["salone", "zona_notte"]}, "action": {"type": "string", "enum": ["on", "off"]} }, "required": ["target", "action"] } } ] } ``` | Campo | Tipo | Obbl. | Note | |---|---|:---:|---| | `messages` | array | ✅ | La cronologia completa, in ordine. Formato qui sotto. | | `system` | string | ❌ | Le istruzioni dell'agente. Se manca, valgono le istruzioni del modello Pepper. Se c'è, di serie **prende il posto** di quelle del modello; con la modalità «voce nelle app» invece **si somma** (vedi [Modello, limiti, comportamento](#modello-limiti-comportamento)). | | `tools` | array | ❌ | Gli attrezzi disponibili. Può cambiare a ogni richiesta. | | `stream` | bool | ❌ | `true` → SSE (§ Streaming). Predefinito `false`. | | `max_tokens` | int | ❌ | Predefinito 4096. Limitato fra 256 e 32000. | | `session_id` | string | ❌ | Serve solo a raggruppare le chiamate nel log di Pepper. **Pepper non tiene stato**: non è una sessione. | ### Formato `messages` - `{"role": "user", "content": ""}` — dalla 6d `content` può essere anche una **lista di blocchi**, per allegare documenti: vedi [Documenti](#documenti-pdf). Chi manda stringhe non cambia niente. - `{"role": "assistant", "content": ""}` — risposta testuale del modello. - `{"role": "assistant", "content": null, "tool_calls": [{"id", "name", "arguments"}]}` — il modello ha chiesto uno o più attrezzi. `arguments` è un **oggetto JSON**. `content` può contenere anche testo insieme alle `tool_calls`. - In ogni messaggio `assistant` può esserci anche **`"blocchi": [...]`**: la lista che Pepper ha mandato nell'evento `done` di quel turno, **tale e quale**. Serve ai modelli che ragionano: vedi [Il ragionamento e i `blocchi`](#il-ragionamento-e-i-blocchi). Chi non la manda funziona come prima. - `{"role": "tool", "tool_call_id": "", "content": ""}` — il risultato che il chiamante ridà al modello. `content` è una **stringa** (testo o JSON serializzato). Gli `id` delle `tool_calls` e i `tool_call_id` devono corrispondere: ogni attrezzo richiesto deve avere il suo risultato prima della chiamata successiva. ### Formato `tools` Function calling standard: `name`, `description`, `parameters` in **JSON Schema**. `parameters` deve essere un oggetto (anche vuoto: `{"type":"object","properties":{}}`). ## Risposta A ogni chiamata il modello può rispondere in testo, chiedere uno o più attrezzi, o entrambe le cose. Chiude sempre con uno `stop_reason`: - `"end_turn"` → ha finito, il testo è la risposta per l'utente. - `"tool_use"` → vuole che il chiamante esegua gli attrezzi e richiami l'endpoint. ### Streaming — `stream: true` `Content-Type: text/event-stream`, HTTP `200`. Sequenza di eventi tipizzati: ``` event: delta data: {"text": "sto controllando"} event: delta data: {"text": " lo stato di casa…"} event: tool_call data: {"id": "toolu_01ABC", "name": "get_home_status", "arguments": {}} event: done data: {"stop_reason": "tool_use", "usage": {"input_tokens": 1840, "output_tokens": 96}, "versione": "Pepper 7", "novita": "…", "blocchi": [{"type": "thinking", "thinking": "", "signature": "…"}, {"type": "tool_use", "id": "toolu_01ABC", "name": "get_home_status", "input": {}}]} ``` - **`delta`** — un pezzo incrementale di testo. Concatenati danno il testo completo. - **`tool_call`** — emesso quando gli argomenti dell'attrezzo sono **completi** (già come oggetto JSON, non a pezzi). Possono essercene più d'uno. - **`done`** — chiude il turno, con `stop_reason` (`end_turn` | `tool_use`), `usage` (token consumati da **questa** chiamata, non dalla conversazione), `versione` (il **modello** che ha risposto — «Pepper 7» — cioè il cervello scelto per il progetto nel pannello: chi lo mostra lo prende da qui invece di tenerne una copia, vedi I modelli), `novita` (una riga del modello che dice cosa ha in più) e `blocchi` (la risposta com'era, pezzo per pezzo: da conservare nel messaggio `assistant` di questo turno, vedi [Il ragionamento e i `blocchi`](#il-ragionamento-e-i-blocchi)). `blocchi` c'è con i modelli Claude. `novita` c'è qui e non su `/api.php` per un motivo preciso: qui dall'altra parte c'è una persona che guarda una chat, e quando il numero cambia il [kit della chat](#il-kit-della-chat) può scriverglielo da sé. Su `/api.php` le risposte se le legge una macchina e finiscono nei log: una riga di novità a ogni chiamata sarebbe solo peso. Chi la vuole comunque la trova su `/capacita.php`. - **`error`** — `{"message": "...", "code": "..."}`; subito dopo lo stream si chiude. - Ogni ~15 secondi di silenzio Pepper manda un commento di keep-alive (`: ping`), così i timeout intermedi non chiudono la connessione. ### Non-streaming — `stream: false` Risposta unica `application/json`: ```json { "stop_reason": "tool_use", "content": "sto controllando lo stato di casa…", "tool_calls": [{"id": "toolu_01ABC", "name": "get_home_status", "arguments": {}}], "usage": {"input_tokens": 1840, "output_tokens": 96}, "versione": "Pepper 7", "novita": "…", "blocchi": [ … ] } ``` `content` è `null` se il modello non ha prodotto testo; `tool_calls` è `[]` se non ha chiesto attrezzi. `usage`, `versione`, `novita` e `blocchi` sono gli stessi dell'evento `done`. In `usage` ci sono anche `cache_read_input_tokens` (letti dalla cache: costano un decimo) e `cache_creation_input_tokens` (scritti in cache: un quarto in più). Pepper mette in cache da sé attrezzi + istruzioni e la cronologia già mandata: la cache regge solo se quella parte resta **identica** da un giro all'altro. Un orario al minuto nel `system` la azzera a ogni messaggio: l'ora va nel messaggio. ### Come sommare `usage` senza contare due volte `usage` è per singola chiamata. In un loop di attrezzi la cronologia viene rimandata da capo a ogni giro, quindi **sommare gli `input_tokens` dei vari giri conta lo stesso testo più volte**: cinque giri non costano cinque volte la cronologia, la contano solo in modo crescente. Per il costo reale di un turno dell'utente: - `output_tokens`: **somma** di tutti i giri; - `input_tokens`: prendi **solo l'ultimo** giro (è il più grande e comprende i precedenti). È un'approssimazione per difetto sull'input, ma è molto più vicina al vero della somma. ## Il loop di tool-use 1. `POST /agent` con `messages` + `tools`. 2. Pepper risponde: eventuale testo + eventuali `tool_call` + `done{stop_reason}`. 3. `stop_reason == "end_turn"` → fine, si mostra il testo. **Stop.** 4. `stop_reason == "tool_use"`: - si accoda il turno assistant (testo + `tool_calls` + i `blocchi` del `done`) a `messages`; - si eseguono gli attrezzi **in locale**, con permessi e conferme; - si accoda un messaggio `{"role": "tool", tool_call_id, content}` per ciascuno (anche per quelli non ancora eseguiti: es. `{"status":"in_attesa_conferma"}`); - si richiama `POST /agent` con la cronologia aggiornata. Torna al punto 2. 5. Conviene mettere un tetto di sicurezza (es. 8 giri per messaggio utente): quello sta al chiamante, Pepper non lo impone. ### Tre regole da non sbagliare 1. **Il testo dei `delta` è esattamente il `content` da rimandare.** I pezzi concatenati danno la stringa da mettere nel turno assistant: non va rielaborata. 2. **Testo e attrezzi stanno nello stesso messaggio assistant, non in due.** Se il turno ha prodotto sia `delta` sia `tool_call`, si rimanda un solo messaggio: `{"role": "assistant", "content": "...", "tool_calls": [...]}`. 3. **Ogni `tool_call` deve avere il suo risultato, senza eccezioni.** Anche quando l'azione è in attesa della conferma dell'utente va mandato il messaggio `tool` con un contenuto qualsiasi (es. `{"status":"in_attesa_conferma"}`). Se ne manca anche uno solo, la chiamata successiva viene **rifiutata dal provider**: è il modo più facile di rompere il loop, e capita proprio nel caso più frequente — le azioni che passano dalla conferma. Gli `id` delle `tool_call` li genera Pepper e vanno riecheggiati **identici**, sia in `assistant.tool_calls[].id` sia nel `tool_call_id` del risultato. ## Errori Formato: HTTP `4xx`/`5xx` con corpo ```json {"error": {"code": "agente_non_abilitato", "message": "La modalità agente non è attiva per il progetto 'pepper-home'."}} ``` | HTTP | `code` | Quando | |---|---|---| | 400 | `richiesta_non_valida` | JSON malformato, `messages` mancante o messaggi con ruoli/campi errati | | 401 | `non_autorizzato` | Chiave assente, errata o non abbinata al progetto | | 403 | `agente_non_abilitato` | Il progetto non ha la modalità agente attiva | | 405 | `metodo_non_valido` | Non è una POST | | 413 | `richiesta_troppo_grande` | Corpo oltre 32 MB | | 429 | `troppe_richieste` | Superato il limite orario del progetto (header `Retry-After`) | | 429 | `budget_esaurito` | Superato il tetto di spesa giornaliero del progetto (header `Retry-After`) | | 422 | `richiesta_rifiutata` | Il modello si è rifiutato di rispondere per motivi di sicurezza: riprovare uguale non serve | | 502 | `errore_ai` | Il provider AI ha risposto con un errore | | 503 | `servizio_non_disponibile` | Database o configurazione non raggiungibili | Se l'errore capita **a stream già aperto** non si può più cambiare il codice HTTP: esce come `event: error` sullo stream, che poi si chiude. Il chiamante deve quindi gestire l'errore in tutti e due i modi. ## Modello, limiti, comportamento - **Motore**: quello del **modello Pepper** del progetto (pannello → Progetti, e i modelli in pannello → Modelli). Provider Claude o OpenAI secondo il modello: il contratto qui sopra non cambia, l'adattatore traduce. - **Istruzioni**: il `system` lo decide chi chiama. Se non lo manda, valgono le istruzioni del modello. Se lo manda, dipende dal modello: - di serie il `system` dell'app **prende il posto** delle istruzioni del modello: l'app parla con un assistente che non sa di essere Pepper, se non glielo dice lei; - con la modalità **«voce nelle app»** accesa si **sommano**: prima le istruzioni del modello (chi è Pepper), poi il `system` dell'app. In questo caso l'app manda solo le sue regole operative, e la voce resta quella di Pepper. Quale dei due vale lo dice `/capacita.php` (`pepper.voce_nelle_app`). La modalità si sceglie quando nasce un modello e non cambia più mentre qualcuno lo usa: un progetto non si ritrova un comportamento diverso senza aver cambiato modello. - **Ragionamento**: lo decide il modello, non l'app. Vedi qui sotto. - **Timeout**: nessun limite imposto da Pepper oltre i 900 secondi di sicurezza dello script e i 600 verso il provider. In streaming i ping tengono viva la connessione. - **Contesto**: il limite è quello del modello (1M token su Opus/Sonnet recenti). Chi chiama è responsabile di non mandare cronologie infinite. - **Dimensione dei risultati degli attrezzi**: Pepper non mette un limite per singolo campo. I tetti veri sono tre: il corpo della richiesta (32 MB, come il provider), il contesto del modello, e il costo. Un risultato da 100 KB di testo sono circa 25.000 token, che vengono **rimandati a ogni giro successivo** del loop: conviene che gli attrezzi restituiscano già il sunto (le ultime N righe, i totali) invece del dump completo, e che sia l'agente a chiedere il dettaglio con un secondo attrezzo se gli serve. - **Log**: ogni chiamata finisce nel monitor di Pepper come encode `agente`, con token consumati, durata ed esito. ## Il ragionamento e i `blocchi` Un modello può **ragionare prima di rispondere** («Pepper 7»). Non lo sceglie l'app: lo sceglie chi gestisce Pepper, nel pannello, modello per modello. Risponde meglio sulle cose difficili, ci mette di più e costa di più. Su alcuni motori (Opus 5.5, Fable 5.1) il ragionamento non si può spegnere affatto. **Il lavoro in più per l'app, e perché.** Quando Pepper ragiona e poi chiede un attrezzo, al giro dopo vuole indietro anche i pezzi del suo ragionamento, **identici e nello stesso ordine**. Per questo `done` porta `blocchi`: la risposta com'era, pezzo per pezzo. L'app non la guarda e non la tocca — è una scatola chiusa — e la rimette nel messaggio `assistant` di quel turno: ```json {"role": "assistant", "content": "Controllo il salone.", "tool_calls": [{"id": "toolu_01ABC", "name": "get_home_status", "arguments": {}}], "blocchi": [ …esattamente quello arrivato nel `done`… ]} ``` Quando ci sono, Pepper rimanda al provider **quelli** e non ricostruisce niente da `content` e `tool_calls`. Tre regole: 1. **I `blocchi` vanno conservati come JSON, non ricostruiti.** Niente campi tolti, niente riordinati, e `{}` deve restare `{}` (non `[]`). 2. **La cronologia si allunga soltanto.** Mai togliere, accorciare o riscrivere un messaggio vecchio mentre la conversazione è aperta, e mai cambiare `system` o `tools` a metà: il ragionamento dopo quel punto non varrebbe più. Pepper in quel caso lo scarta invece di dare errore (la risposta è un po' meno ragionata, e nel log di Pepper si vede), ma è meglio non succeda. 3. **Chi non manda i `blocchi` non si rompe.** Se in un giro di attrezzi ancora aperto un messaggio `assistant` arriva senza, per quel giro risponde la **riserva** del modello: un motore che sa andare avanti senza ragionamento. La conversazione continua, e nel pannello di Pepper il progetto risulta «app senza blocchi» finché non viene aggiornata. Nessuna levetta da accendere: Pepper se ne accorge da solo, a ogni chiamata. Con un modello che non ragiona i `blocchi` arrivano lo stesso (testo e attrezzi): conservarli da subito non costa niente, e il giorno che il progetto passa a un modello che ragiona l'app è già pronta. Chi ragiona ha bisogno di spazio: se il modello ragiona, Pepper alza da solo `max_tokens` ad almeno 16.000. ## Documenti (PDF) Dalla 6d un messaggio dell'utente può portarsi dietro dei PDF, senza uscire dal contratto: `content`, invece di una stringa, diventa una lista di blocchi. ```jsonc { "role": "user", "content": [ {"tipo": "documento", "nome": "verbale.pdf", "dati": ""}, {"tipo": "testo", "testo": "Di cosa parla? Chi erano i presenti?"} ] } ``` Un blocco è `{"tipo": "testo", "testo": "..."}` oppure `{"tipo": "documento", "nome": "...", "dati": ""}` — o `"url"` al posto di `"dati"`, con un indirizzo `https://` raggiungibile. Vale tutto quello che è scritto in [API.md → Documenti](?f=api#documenti-pdf): stessi limiti (5 documenti, 10 MB l'uno, 600 pagine — 100 sul modello economico), stesso permesso per progetto (**Progetti → Documenti**, `403 documenti_non_abilitati` senza), e solo con Claude. Le **foto** viaggiano nello stesso blocco, con `tipo_file`: `{"tipo": "documento", "nome": "foto.jpg", "tipo_file": "image/jpeg", "dati": ""}`. Valgono le regole di [API.md → Foto](?f=api#foto): JPEG, PNG, GIF, WebP, 5 MB l'una, e un permesso loro (**Progetti → Immagini**, `403 immagini_non_abilitate` senza). **Le citazioni qui non ci sono.** In modalità agente la risposta esce a pezzi via streaming e il contratto non ha un posto dove metterle. È la stessa scelta fatta per il ragionamento esteso: meglio una capacità dichiaratamente assente che una che si perde per strada. Chi ha bisogno delle citazioni usa `/api.php`. ## Il kit della chat Se stai costruendo una chat sopra questo endpoint, non serve disegnarla da zero: Pepper serve lui `pepper-chat.css` e `pepper-chat.js`, e si collegano così: ```html
``` Sono due file senza librerie e sanno già leggere gli eventi di questa pagina: bolla che si allunga mentre il testo arriva, pallino dell'attrezzo che Pepper sta usando, riga di stato, il nome del Pepper con cui si parla sulla chat vuota — e la riga di novità quando il modello cambia. Per il nome sulla chat vuota, la pagina dice al kit a che progetto appartiene: `PepperChat.attacca(el, {indirizzo: '/mio-server/chat', progetto: 'dossiero'})`. Il kit chiede a `kit.php?progetto=dossiero` e scrive «Pepper 7» sopra «Come posso aiutarti?». È il **nome** del progetto, non la chiave: `kit.php` restituisce solo il nome del modello, niente altro. **Collegati così, si aggiornano da soli.** Il giorno che nel kit si sistema una cosa, arriva al ricaricamento dopo, in tutte le chat insieme — anche in quelle che non abbiamo scritto noi. Non serve nessuna chiave: la chat parla col *tuo* server, non con Pepper. `kit.php` risponde con un `ETag` e `Cache-Control: public, no-cache`, quindi il browser se lo tiene e quasi sempre riceve un `304` invece del file; `https:///kit.php` senza parametri dice quale versione del kit c'è adesso, se un deploy vuole saperlo senza scaricarlo. Nessuna delle chat di casa ne tiene più una copia: il pannello di Pepper, Dossiero, il pannello workspace e la V5 collegano tutti `kit.php`, e nessuno dei quattro ha l'indirizzo scritto a mano — se lo ricava da quello dell'API che ha già in configurazione, così il kit arriva sempre dallo *stesso* Pepper che poi risponde. Copiarli si può ancora, e per qualcuno resta obbligatorio: una chat che deve funzionare con internet giù non può prendere il suo JavaScript da fuori. In quel caso però la copia non si aggiorna a mano — vedi `scripts/kit-chat.sh` nel repository di Pepper, che il gancio `post-commit` fa scattare da solo ogni volta che il kit cambia. Il kit capisce `delta`, `tool_call`, `done` ed `error` così come sono definiti qui, più due eventi che **puoi mandare tu**: `tool_done {id, ok}`, per far diventare verde (o rosso) il pallino dell'attrezzo quando l'hai eseguito, e `pending {actions}`, per i bottoni di conferma di un'azione che Pepper ha proposto. Pepper non può mandarli — gli attrezzi li esegui tu, e solo tu sai quando hanno finito e cosa richiede una conferma. Dentro ci sono anche allegati, lettura ad alta voce, microfono push-to-talk, i bottoni di conferma e «Nuova chat» (che vuole `nuova: { quando }`: la cronologia sta sul tuo server, e la cancella lui): si accendono una per una (`funzioni`), e di fabbrica sono quasi tutte spente. L'elenco completo è nella pagina **API** del pannello di Pepper. Quello che **non** si accende è lo stile: l'a capo dopo ogni frase e il grassetto valgono sempre, in tutte le chat, e la levetta per spegnerli non c'è più. Erano due opzioni, e il risultato è stato che la stessa risposta di Pepper si leggeva in due modi a seconda del progetto. **Se ti serve qualcosa che non c'è, si aggiunge al kit e non al progetto**: è l'unico modo perché il progetto dopo se la trovi già pronta. E se è una cosa di aspetto, si cambia nel kit senza farne un'opzione. Una raccomandazione che vale più del kit: **la chiave del progetto non deve mai finire nel browser**. Il giro è sempre *pagina → il tuo server → Pepper*. ## Cosa non c'è nella v1 - **`tool_choice`** (forzare o vietare l'uso degli attrezzi). Attenzione se un giorno si aggiunge: sui motori nuovi (Opus 5.5, Fable 5.1) *forzare* un attrezzo (`any` o un attrezzo preciso) è un errore del provider; resta possibile solo `auto` o `none`. - **La ricerca sul web di Pepper**: su `/api.php` si accende dal pannello, qui no — e non è una dimenticanza. In modalità agente gli attrezzi li dichiari tu: se vuoi che Pepper cerchi, la ricerca la metti fra i tuoi `tools` e la esegui tu, con le tue regole. È lo stesso principio di tutto il resto: **Pepper è il cervello, non le mani**. - **Memoria lato Pepper**: in modalità agente la cronologia è del chiamante, per scelta. ## Configurazione nginx L'URL `/agent` (senza `.php`) richiede una riga nel vhost: ```nginx location = /agent { rewrite ^ /agent.php last; } ``` Senza questa riga funziona comunque `POST /agent.php`. Va inoltre verificato che il buffering non spezzi lo streaming: Pepper manda già `X-Accel-Buffering: no`, che nginx rispetta, quindi normalmente non serve altro. ## Esempio — un giro completo ```bash curl -N https://gateway.pepperai.it/agent \ -H "Content-Type: application/json" \ -H "Accept: text/event-stream" \ -H "X-Pepper-Key: " \ -H "X-Pepper-Project: pepper-home" \ -d '{ "stream": true, "max_tokens": 1024, "system": "Sei Pepper, l assistente di casa. Proponi le azioni, non darle per fatte.", "messages": [{"role": "user", "content": "che aria fa in salone?"}], "tools": [{ "name": "get_home_status", "description": "Stato sintetico di casa.", "parameters": {"type": "object", "properties": {}, "required": []} }] }' ```