Guías
Agentes
Haz que responda un agente de Piqline: un turno, un estado, una conversación.
Un agente es el asistente del panel, llamado por HTTP: lee tu petición, elige sus herramientas, las ejecuta y responde con sus fuentes. Usa el mismo motor que el chat. Solo dispone de las herramientas que tu clave podría llamar por sí misma.
Los agentes#
| Agente | Función |
|---|---|
piqline | Pipeline del workspace: corpus, vigilancia, tableros, tablas y marcadores. |
requete | Una pregunta precisa, con datos fechados tomados de la web, de registros y de archivos. |
facebook | Marketplace y grupos públicos, en directo. |
linkedin | Contratación, vigilancia y oportunidades a partir de publicaciones públicas. |
upwork | Ofertas de Upwork leídas, puntuadas y respondidas a partir de tu base de conocimiento. |
onboarding | Configuración guiada del workspace: necesidad, fuentes, tablero de inicio, alertas. Solo propietarios y administradores. |
La clave necesita el scope agents. GEThttps://piqline.com/api/v1/agents lista los agentes y, para cada uno, las herramientas que tu clave puede llamar.
Ejecutar un turno#
POST https://piqline.com/api/v1/agents/{agent}
Content-Type: application/json| Campo | Tipo | Función |
|---|---|---|
input | texto, 20 000 caracteres como máximo | Tu mensaje. |
messages | array | La conversación anterior, tal como la devolvió la llamada previa. |
model | texto | ID de un modelo que ofrece el asistente. Un ID desconocido se sustituye por el modelo por defecto. |
reasoning | low, medium o high | Esfuerzo de razonamiento, para los modelos que lo admiten. |
stream | booleano | true: respuesta en streaming (ver más abajo). |
Envía al menos 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 respuesta:
| Campo | Significado |
|---|---|
agent | el agente que consultaste |
status | completed, requires_input o requires_approval (ver más abajo) |
text | la respuesta del agente |
tool_calls | las herramientas llamadas durante el turno: tool, state, input y output o error |
pending | lo que espera tu respuesta: kind (input o approval), tool, input y, en una aprobación, approval_id |
messages | la conversación completa, para reenviarla en la siguiente llamada |
Continuar una conversación#
Reenvía el array messages de la respuesta anterior y pon tu nuevo mensaje en 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 @-Cuando el agente se detiene#
completed. El agente ha respondido.textcontiene su respuesta.requires_input. El agente hace una pregunta o propone una tarjeta, por ejemplo una elección entre varias fuentes.pendinglo describe. Responde con texto eninputy reenvíamessages.requires_approval. El agente propone una acción, por ejemplo suscribirse a una fuente, sin ejecutarla. Para ejecutarla, llama tú mismo a la herramienta indicada enpending[].toolconpending[].input, mediantePOSThttps://piqline.com/api/v1/tools/{nom}, con una clave que tenga el scopeact.
Streaming#
Con "stream": true, la respuesta llega como un flujo de Server-Sent Events: el mismo flujo que el chat del panel. Con curl, añade -N para verlo llegar.
Créditos y duración#
Un turno consume créditos del workspace, descontados de su tope mensual. Un turno dura de unos segundos a varias decenas de segundos. Configura un timeout de 5 minutos en el cliente.
Cada clave puede ejecutar 10 turnos por minuto por defecto: consulta Límites.