# Agents

> Faire répondre un agent Piqline : un tour, un état, une conversation.

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

Un agent est l’assistant du dashboard, appelé par HTTP : il lit votre demande, choisit ses outils, les exécute et répond en citant ses sources. Il utilise le même moteur que le chat. Il ne dispose que des outils que votre clé pourrait appeler elle-même.

## Les agents

| Agent | Rôle |
| --- | --- |
| `piqline` | Pipeline du workspace : corpus, veille, boards, tables et bookmarks. |
| `requete` | Une question précise, des faits datés pris sur le web, les registres et les archives. |
| `facebook` | Marketplace et groupes publics, en direct. |
| `linkedin` | Recrutement, veille et opportunités à partir des posts publics. |
| `upwork` | Offres Upwork lues, notées et rédigées depuis votre base de connaissances. |
| `onboarding` | Configuration guidée du workspace : besoin, sources, tableau d’accueil, alertes. Réservé aux owners et admins. |

La clé doit porter le scope `agents`. `GET https://piqline.com/api/v1/agents` liste les agents et, pour chacun, les outils que votre clé peut appeler.

## Lancer un tour

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

| Champ | Type | Rôle |
| --- | --- | --- |
| `input` | texte, 20 000 caractères au plus | Votre message. |
| `messages` | tableau | La conversation précédente, telle que l’appel précédent l’a renvoyée. |
| `model` | texte | Identifiant d’un modèle proposé par l’assistant. Un identifiant inconnu est remplacé par le modèle par défaut. |
| `reasoning` | `low`, `medium` ou `high` | Effort de raisonnement, pour les modèles qui le permettent. |
| `stream` | booléen | `true` : réponse en flux (voir plus bas). |

Il faut au moins `input` ou `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 réponse :

| Champ | Sens |
| --- | --- |
| `agent` | l’agent interrogé |
| `status` | `completed`, `requires_input` ou `requires_approval` (voir plus bas) |
| `text` | la réponse de l’agent |
| `tool_calls` | les outils appelés pendant le tour : `tool`, `state`, `input` et `output` ou `error` |
| `pending` | ce qui attend votre réponse : `kind` (`input` ou `approval`), `tool`, `input` et, pour une approbation, `approval_id` |
| `messages` | la conversation complète, à renvoyer au prochain appel |

## Poursuivre une conversation

Renvoyez le tableau `messages` de la réponse précédente, et ajoutez votre nouveau message dans `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 @-
```

## Quand l’agent s’arrête

- **`completed`.** L’agent a répondu. `text` contient sa réponse.
- **`requires_input`.** L’agent pose une question ou propose une carte, par exemple choisir parmi plusieurs sources. `pending` la décrit. Répondez en texte dans `input`, en renvoyant `messages`.
- **`requires_approval`.** L’agent propose une action, par exemple s’abonner à une source, sans l’exécuter. Pour l’exécuter, appelez vous-même l’outil indiqué dans `pending[].tool` avec `pending[].input`, par `POST https://piqline.com/api/v1/tools/{nom}`, avec une clé qui porte le scope `act`.

## Réponse en flux

Avec `"stream": true`, la réponse arrive en flux, en Server-Sent Events : le même que celui du chat du dashboard. Avec `curl`, ajoutez `-N` pour le voir arriver.

## Crédits et délais

Un tour consomme des crédits du workspace, décomptés de son plafond du mois. Un tour dure de quelques secondes à plusieurs dizaines de secondes. Prévoyez un délai d’attente de 5 minutes côté client.

Chaque clé peut lancer 10 tours par minute par défaut : voir [Limites](/fr/docs/api/authentication#limites).
