# Agentes

> Haz que responda un agente de Piqline: un turno, un estado, una conversación.

Source: https://piqline.com/es/docs/api/agents

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`. `GET https://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
```

| 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`.

```bash tab="curl"
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 ?"}'
```
```javascript tab="JavaScript"
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();
```
```python tab="Python"
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`:

```bash
# 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 `POST https://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](/es/docs/api/authentication#limites).
