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.
`facebook`	Marketplace et groupes publics, en direct via Scrape Creators.
`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#

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.

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
`cost_usd`	le coût des appels de modèle du tour, en dollars américains

Poursuivre une conversation#

Renvoyez le tableau messages de la réponse précédente, et ajoutez votre nouveau message dans input :

Shell

# 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 POSThttps://piqline.com/api/v1/tools/{nom}, avec une clé qui porte le scope act.

Réponse en flux#

Avec "stream": true, la réponse est le flux « UI message stream » de l’AI SDK, en Server-Sent Events : celui du chat du dashboard. Un client useChat de l’AI SDK le lit tel quel. Avec curl, ajoutez -N pour le voir arriver.

Coûts et délais#

Un tour consomme des crédits modèle (cost_usd) et, selon les outils appelés, des crédits fournisseurs. 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.