Guide
Agenti
Far rispondere un agente Piqline: un turno, uno stato, una conversazione.
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. GEThttps://piqline.com/api/v1/agents elenca gli agenti e, per ciascuno, i tool che la tua chiave può chiamare.
Eseguire un turno#
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.
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 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:
# 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.textcontiene la sua risposta.requires_input. L'agente pone una domanda o propone una card, per esempio una scelta tra più fonti.pendingla descrive. Rispondi con del testo ininput, rinviandomessages.requires_approval. L'agente propone un'azione, per esempio l'iscrizione a una fonte, senza eseguirla. Per eseguirla, chiama tu stesso il tool indicato inpending[].toolconpending[].input, tramitePOSThttps://piqline.com/api/v1/tools/{nom}, con una chiave che ha lo scopeact.
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.