Saltar al contenido

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#

AgenteFunción
piqlinePipeline del workspace: corpus, vigilancia, tableros, tablas y marcadores.
requeteUna pregunta precisa, con datos fechados tomados de la web, de registros y de archivos.
facebookMarketplace y grupos públicos, en directo.
linkedinContratación, vigilancia y oportunidades a partir de publicaciones públicas.
upworkOfertas de Upwork leídas, puntuadas y respondidas a partir de tu base de conocimiento.
onboardingConfiguració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#

HTTP
POST https://piqline.com/api/v1/agents/{agent}
Content-Type: application/json
CampoTipoFunción
inputtexto, 20 000 caracteres como máximoTu mensaje.
messagesarrayLa conversación anterior, tal como la devolvió la llamada previa.
modeltextoID de un modelo que ofrece el asistente. Un ID desconocido se sustituye por el modelo por defecto.
reasoninglow, medium o highEsfuerzo de razonamiento, para los modelos que lo admiten.
streambooleanotrue: 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 ?"}'

La respuesta:

CampoSignificado
agentel agente que consultaste
statuscompleted, requires_input o requires_approval (ver más abajo)
textla respuesta del agente
tool_callslas herramientas llamadas durante el turno: tool, state, input y output o error
pendinglo que espera tu respuesta: kind (input o approval), tool, input y, en una aprobación, approval_id
messagesla 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:

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

Cuando el agente se detiene#

  • completed. El agente ha respondido. text contiene su respuesta.
  • requires_input. El agente hace una pregunta o propone una tarjeta, por ejemplo una elección entre varias fuentes. pending lo describe. Responde con texto en input y reenvía messages.
  • 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 en pending[].tool con pending[].input, mediante POSThttps://piqline.com/api/v1/tools/{nom}, con una clave que tenga el scope act.

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.

¿Tienes una pregunta sobre la API o has encontrado un error en esta página? Escríbenos.