# Agenti

> Far rispondere un agente Piqline: un turno, uno stato, una conversazione.

Source: https://piqline.com/it/docs/api/agents

Un agente è l'assistente della dashboard, chiamato via HTTP: legge la tua richiesta, sceglie i suoi tool, li esegue e risponde con le sue fonti. Usa lo stesso motore della chat. Ha solo i tool che la tua chiave potrebbe chiamare direttamente.

## Gli agenti

| Agente | Ruolo |
| --- | --- |
| `piqline` | Pipeline del workspace: corpus, monitoraggio, board, tabelle e segnalibri. |
| `requete` | Una domanda precisa, fatti datati ricavati dal web, dai registri e dagli archivi. |
| `facebook` | Marketplace e gruppi pubblici, in diretta. |
| `linkedin` | Assunzioni, monitoraggio e opportunità a partire da post pubblici. |
| `upwork` | Offerte Upwork lette, valutate e riscontrate a partire dalla tua knowledge base. |
| `onboarding` | Configurazione guidata del workspace: esigenza, fonti, board home, avvisi. Solo owner e admin. |

La chiave richiede lo scope `agents`. `GET https://piqline.com/api/v1/agents` elenca gli agenti e, per ciascuno, i tool che la tua chiave può chiamare.

## Eseguire un turno

```http
POST https://piqline.com/api/v1/agents/{agent}
Content-Type: application/json
```

| Campo | Tipo | Ruolo |
| --- | --- | --- |
| `input` | testo, al massimo 20.000 caratteri | Il tuo messaggio. |
| `messages` | array | La conversazione precedente, come l'ha restituita la chiamata precedente. |
| `model` | testo | ID di un modello offerto dall'assistente. Un ID sconosciuto viene sostituito dal modello predefinito. |
| `reasoning` | `low`, `medium` o `high` | Livello di ragionamento, per i modelli che lo supportano. |
| `stream` | booleano | `true`: risposta in streaming (vedi sotto). |

Invia almeno `input` o `messages`.

```bash tab="curl"
curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Quelles sources sont en erreur, et depuis quand ?"}'
```
```javascript tab="JavaScript"
const response = await fetch("https://piqline.com/api/v1/agents/piqline", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.PIQLINE_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ input: "Quelles sources sont en erreur, et depuis quand ?" }),
});
const data = await response.json();
```
```python tab="Python"
import os
import requests

response = requests.post(
    "https://piqline.com/api/v1/agents/piqline",
    headers={"Authorization": "Bearer " + os.environ["PIQLINE_API_KEY"]},
    json={"input": "Quelles sources sont en erreur, et depuis quand ?"},
)
data = response.json()
```

La risposta:

| Campo | Significato |
| --- | --- |
| `agent` | l'agente che hai interrogato |
| `status` | `completed`, `requires_input` o `requires_approval` (vedi sotto) |
| `text` | la risposta dell'agente |
| `tool_calls` | i tool chiamati durante il turno: `tool`, `state`, `input` e `output` oppure `error` |
| `pending` | ciò che attende la tua risposta: `kind` (`input` o `approval`), `tool`, `input` e, per un'approvazione, `approval_id` |
| `messages` | la conversazione completa, da rinviare alla chiamata successiva |

## Proseguire una conversazione

Rinvia l'array `messages` della risposta precedente e metti il tuo nuovo messaggio in `input`:

```bash
# Premier tour : on garde la réponse.
curl -s https://piqline.com/api/v1/agents/piqline \
  -H "Authorization: Bearer $PIQLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":"Quelles sources sont en erreur ?"}' > tour1.json

# Deuxième tour : on renvoie la conversation.
jq '{messages: .messages, input: "Et depuis quand ?"}' tour1.json \
  | curl -s https://piqline.com/api/v1/agents/piqline \
      -H "Authorization: Bearer $PIQLINE_API_KEY" \
      -H "Content-Type: application/json" \
      -d @-
```

## Quando l'agente si ferma

- **`completed`.** L'agente ha risposto. `text` contiene la sua risposta.
- **`requires_input`.** L'agente pone una domanda o propone una card, per esempio una scelta tra più fonti. `pending` la descrive. Rispondi con del testo in `input`, rinviando `messages`.
- **`requires_approval`.** L'agente propone un'azione, per esempio l'iscrizione a una fonte, senza eseguirla. Per eseguirla, chiama tu stesso il tool indicato in `pending[].tool` con `pending[].input`, tramite `POST https://piqline.com/api/v1/tools/{nom}`, con una chiave che ha lo scope `act`.

## Streaming

Con `"stream": true`, la risposta arriva come flusso di Server-Sent Events: lo stesso flusso della chat della dashboard. Con `curl`, aggiungi `-N` per vederlo arrivare.

## Crediti e tempi

Un turno consuma crediti del workspace, prelevati dal suo limite mensile. Un turno dura da pochi secondi a diverse decine di secondi. Imposta un timeout di 5 minuti lato client.

Ogni chiave può eseguire 10 turni al minuto per impostazione predefinita: vedi [Limiti](/it/docs/api/authentication#limiti).
