Guides
Agents
Faire répondre un agent Piqline : un tour, un état, une conversation.
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. GEThttps://piqline.com/api/v1/agents liste les agents et, pour chacun, les outils que votre clé peut appeler.
Lancer un tour#
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.
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 ?"}'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();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 :
# 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.textcontient sa réponse.requires_input. L’agent pose une question ou propose une carte, par exemple choisir parmi plusieurs sources.pendingla décrit. Répondez en texte dansinput, en renvoyantmessages.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é danspending[].toolavecpending[].input, parPOSThttps://piqline.com/api/v1/tools/{nom}, avec une clé qui porte le scopeact.
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.