# Agentes

> Faça um agente Piqline responder: um turno, um status, uma conversa.

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

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`. `GET https://piqline.com/api/v1/agents` lista os agentes e, para cada um, as ferramentas que a sua chave pode chamar.

## Executar um turno

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

```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()
```

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

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

## Quando o agente para

- **`completed`.** O agente respondeu. `text` contém a resposta.
- **`requires_input`.** O agente faz uma pergunta ou propõe um cartão, por exemplo uma escolha entre várias fontes. `pending` o descreve. Responda em texto em `input`, reenviando `messages`.
- **`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 em `pending[].tool` com `pending[].input`, por meio de `POST https://piqline.com/api/v1/tools/{nom}`, com uma chave que tenha o scope `act`.

## 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](/pt/docs/api/authentication#limites).
