Vai al contenuto

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#

AgenteRuolo
piqlinePipeline del workspace: corpus, monitoraggio, board, tabelle e segnalibri.
requeteUna domanda precisa, fatti datati ricavati dal web, dai registri e dagli archivi.
facebookMarketplace e gruppi pubblici, in diretta.
linkedinAssunzioni, monitoraggio e opportunità a partire da post pubblici.
upworkOfferte Upwork lette, valutate e riscontrate a partire dalla tua knowledge base.
onboardingConfigurazione 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#

HTTP
POST https://piqline.com/api/v1/agents/{agent}
Content-Type: application/json
CampoTipoRuolo
inputtesto, al massimo 20.000 caratteriIl tuo messaggio.
messagesarrayLa conversazione precedente, come l'ha restituita la chiamata precedente.
modeltestoID di un modello offerto dall'assistente. Un ID sconosciuto viene sostituito dal modello predefinito.
reasoninglow, medium o highLivello di ragionamento, per i modelli che lo supportano.
streambooleanotrue: 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 ?"}'

La risposta:

CampoSignificato
agentl'agente che hai interrogato
statuscompleted, requires_input o requires_approval (vedi sotto)
textla risposta dell'agente
tool_callsi tool chiamati durante il turno: tool, state, input e output oppure error
pendingciò che attende la tua risposta: kind (input o approval), tool, input e, per un'approvazione, approval_id
messagesla 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:

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 @-

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 POSThttps://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.

Una domanda sull'API, o un errore in questa pagina? Scrivici.