Guias
Agentes
Faça um agente Piqline responder: um turno, um status, uma conversa.
Um agente é o assistente do painel, chamado via HTTP: ele lê o seu pedido, escolhe suas ferramentas, as executa e responde com as fontes. Usa o mesmo motor do chat. Só tem as ferramentas que a sua chave poderia chamar.
Os agentes#
| Agente | Função |
|---|---|
piqline | Pipeline do workspace: corpus, monitoramento, boards, tabelas e favoritos. |
requete | Uma pergunta precisa, fatos datados extraídos da web, de registros e de arquivos. |
facebook | Marketplace e grupos públicos, ao vivo. |
linkedin | Contratação, monitoramento e oportunidades a partir de posts públicos. |
upwork | Vagas do Upwork lidas, pontuadas e respondidas a partir da sua base de conhecimento. |
onboarding | Configuração guiada do workspace: necessidade, fontes, board inicial, alertas. Somente owners e admins. |
A chave precisa do scope agents. GEThttps://piqline.com/api/v1/agents lista os agentes e, para cada um, as ferramentas que a sua chave pode chamar.
Executar um turno#
POST https://piqline.com/api/v1/agents/{agent}
Content-Type: application/json| Campo | Tipo | Função |
|---|---|---|
input | texto, no máximo 20.000 caracteres | Sua mensagem. |
messages | array | A conversa anterior, como a chamada anterior a devolveu. |
model | texto | ID de um modelo oferecido pelo assistente. Um ID desconhecido é substituído pelo modelo padrão. |
reasoning | low, medium ou high | Esforço de raciocínio, para os modelos que o aceitam. |
stream | booleano | true: resposta em streaming (veja abaixo). |
Envie pelo menos 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()A resposta:
| Campo | Significado |
|---|---|
agent | o agente que você consultou |
status | completed, requires_input ou requires_approval (veja abaixo) |
text | a resposta do agente |
tool_calls | as ferramentas chamadas durante o turno: tool, state, input e output ou error |
pending | o que aguarda a sua resposta: kind (input ou approval), tool, input e, para uma aprovação, approval_id |
messages | a conversa completa, para reenviar na próxima chamada |
Continuar uma conversa#
Reenvie o array messages da resposta anterior e coloque a nova mensagem em 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 o agente para#
completed. O agente respondeu.textcontém a resposta.requires_input. O agente faz uma pergunta ou propõe um cartão, por exemplo uma escolha entre várias fontes.pendingo descreve. Responda em texto eminput, reenviandomessages.requires_approval. O agente propõe uma ação, por exemplo assinar uma fonte, sem executá-la. Para executá-la, chame você mesmo a ferramenta indicada empending[].toolcompending[].input, por meio dePOSThttps://piqline.com/api/v1/tools/{nom}, com uma chave que tenha o scopeact.
Streaming#
Com "stream": true, a resposta chega como um fluxo de Server-Sent Events: o mesmo fluxo do chat do painel. Com curl, adicione -N para vê-la chegar.
Créditos e duração#
Um turno consome créditos do workspace, debitados do seu limite mensal. Um turno dura de alguns segundos a várias dezenas de segundos. Defina um timeout de 5 minutos no cliente.
Cada chave pode executar 10 turnos por minuto por padrão: veja Limites.