# API de Agentes de IA

Um **Agente de IA** é o cérebro por trás do seu bot: suas instruções, personalidade, idioma, conhecimento e ferramentas. Você cria um Agente uma vez e, em seguida, direciona o tráfego para ele. Este guia cobre tudo o que você pode fazer com um Agente via API — criá-lo, configurá-lo, fornecer conhecimento e ferramentas, revisar seus rascunhos e rotear conversas para ele.

- **URL Base** — `https://api.youraiconnector.com/v1`
- **Autenticação** — sua chave de API (veja [Autenticação](authentication.md))
- **Erros e paginação** — veja [Erros e Paginação](errors-and-pagination.md)

Todos os exemplos abaixo mostram a forma de consulta `?apiKey=` em cURL e o cabeçalho `X-API-Key` em JavaScript e Python — ambos funcionam em todos os endpoints.

Se você é novo no conceito de Agentes, leia [Agentes de IA](../ai-agents/ai-agents.md) primeiro.


---

## Como um Agente é estruturado

Quatro coisas são gerenciadas separadamente, e é útil saber o que é cada uma antes de começar:

| Peça | O que é | Onde você configura |
|---|---|---|
| **Configuração** | Instruções, regras, objetivo, personalidade, idioma, nível de IA, comportamento de agendamento e acompanhamento | `PUT /agents/{agentId}` ou o `PUT /agents/{agentId}/bot-config` mais restrito |
| **Conhecimento** | FAQs e fontes de conhecimento (páginas e documentos que a plataforma leu para você) | [API de FAQs](faqs.md) e `POST /agents/{agentId}/kb-sources` |
| **Ferramentas** | Funções personalizadas e servidores MCP que o Agente pode chamar durante a conversa | `POST /agents/{agentId}/custom-functions` e `POST /agents/{agentId}/mcp-servers` |
| **Roteamento** | Quais canais e conversas realmente chegam a este Agente | Pontos de Entrada — `PUT /entry-points/channel-defaults` e `POST /agents/{agentId}/entry-points` |

> **Um novo Agente não responde a ninguém até que você roteie para ele.** Criar um Agente não o coloca em um canal. Esse é o passo que a maioria das integrações perde — veja [Roteando conversas para um Agente](#routing-conversations-to-an-agent) no final desta página.

---

## O objeto Agente

Um documento completo de Agente é grande — várias centenas de kilobytes, principalmente sua lista de FAQs, suas fontes de conhecimento e qualquer conteúdo de página lido do seu site. Por causa disso, a listagem retorna uma **linha de resumo** curta por Agente quando você a solicita:

```json
{
  "id": "ag7HkQ2ZpLxR3mNb",
  "name": "Listing assistant",
  "active": true,
  "language": "en",
  "goal": "Book a viewing",
  "tags": [],
  "anthropic_model": "standard",
  "ai_speed": "balanced",
  "enable_bookings": false,
  "enable_follow_ups": true,
  "faq_refs_count": 42,
  "kb_source_refs_count": 3,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | string | Identificador único do Agente. |
| `name` | string \| null | Nome do Agente, conforme mostrado no painel. |
| `active` | boolean \| null | Se o Agente tem permissão para responder no momento. |
| `language` | string \| null | Idioma no qual o Agente responde. |
| `goal` | string \| null | O objetivo do Agente, encurtado para os primeiros 200 caracteres (uma reticência no final significa que foi encurtado). |
| `tags` | array \| null | Regras de marcação do Agente. |
| `anthropic_model` | string \| null | Nível de qualidade da IA: `standard`, `economy`, `max` ou `mini`. |
| `ai_speed` | string \| null | Quanto raciocínio o Agente aplica antes de responder: `fast`, `fast_thinker`, `balanced` ou `thorough`. |
| `enable_bookings` | boolean \| null | Se o Agente pode agendar compromissos. |
| `enable_follow_ups` | boolean \| null | Se o Agente envia mensagens de acompanhamento. |
| `faq_refs_count` | integer | Quantas FAQs existem na base de conhecimento deste Agente. |
| `kb_source_refs_count` | integer | Quantas fontes de conhecimento estão vinculadas a ele. |
| `created_at` | integer \| null | Hora de criação, milissegundos da época. |
| `last_modified_at` | integer \| null | Última alteração, milissegundos da época. |

O documento completo adiciona todo o resto: `instructions`, `rules`, `personality`, `availability`, `follow_up_config`, as listas vinculadas de FAQ e fontes de conhecimento, os blocos de texto gerados e qualquer estado de execução (`tag_generation`, `optimize_run`).

> Algumas respostas também contêm `substrate_campaign_id`. É um registro interno mantido em contas mais antigas; você nunca precisa agir sobre ele, e em contas mais novas ele é `null` ou ausente.

---

## Listar Agentes

`GET /agents` — todos os Agentes na conta, do mais novo para o mais antigo.

Este endpoint **não é paginado**. Por padrão, cada Agente retorna com sua configuração completa, o que é pesado: um único Agente pode chegar a 580 KB e uma conta com 64 Agentes a mais de 3 MB. Passe `view=summary` para obter uma linha curta por Agente, e então leia aquele que você deseja com [Obter um Agente](#get-an-agent).

**Parâmetros de consulta**

| Parâmetro | Descrição |
|---|---|
| `view` | Defina como `summary` para linhas curtas. Qualquer outro valor retorna `400`. Omitir para documentos completos. |
| `fields` | Aplica-se apenas em conjunto com `view=summary`. Chaves de resumo separadas por vírgula para manter, por exemplo `id,name,active`. `id` é sempre incluído; nomes desconhecidos são ignorados. |

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY&view=summary&fields=id,name,active"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents?view=summary", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agents } = await res.json();
```

**Python**

```python
import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"view": "summary"},
)
agents = res.json()["agents"]
```

**Resposta** (`200`)

```json
{
  "success": true,
  "agents": [
    { "id": "ag7HkQ2ZpLxR3mNb", "name": "Listing assistant", "active": true }
  ]
}
```

---

## Criar um Agente

`POST /agents` — apenas `name` é realmente necessário; envie qualquer configuração que você já conheça junto com ele. Um novo Agente está ativo por padrão.

**Campos da requisição** (todos opcionais, exceto `name`)

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do Agente. |
| `active` | boolean | Se ele pode responder imediatamente. O padrão é `true`. |
| `language` | string | Idioma no qual o Agente responde. |
| `instructions` | string | Instruções principais que direcionam como ele fala com os contatos. |
| `rules` | string | Regras rígidas que ele deve sempre seguir. |
| `goal` | string | O resultado pelo qual ele deve trabalhar. |
| `personality` | string | Tom de voz e personalidade. |
| `availability` | object | Horário de funcionamento por dia da semana — veja [Definir horário de funcionamento](#set-active-hours). |
| `ai_speed` | string | `fast`, `fast_thinker`, `balanced` ou `thorough`. |
| `anthropic_model` | string | `standard`, `economy`, `max` ou `mini`. |
| `scrape_urls` | string[] | Páginas para ler e construir as instruções do Agente a partir delas. |

**Construindo um Agente a partir do seu site.** Inclua `scrape_urls` e a plataforma lerá essas páginas e escreverá as instruções para você. A resposta informa se essa geração foi iniciada, para que você saiba se deve verificar o progresso do Agente.

**cURL**

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Listing assistant",
    "language": "en",
    "instructions": "Answer questions about our listings and book viewings.",
    "goal": "Book a viewing"
  }'
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Listing assistant",
    scrape_urls: ["https://example.com", "https://example.com/faq"],
  }),
});
const data = await res.json();
console.log(data.agent_id);
```

**Python**

```python
res = requests.post(
    "https://api.youraiconnector.com/v1/agents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"name": "Listing assistant", "scrape_urls": ["https://example.com"]},
)
print(res.json()["agent_id"])
```

**Resposta** (`201`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "substrate_campaign_id": null,
  "agent_generation_queued": true
}
```

`agent_generation_queued` é `true` quando a plataforma começou a escrever as instruções a partir das páginas que você forneceu.

Um `400` significa que o corpo não era um objeto JSON, um campo foi rejeitado ou o Agente excede o tamanho de configuração permitido pelo seu plano. Um `403` significa que a conta não tem permissão para usar uma das configurações que você enviou — por exemplo, um nível de IA que o provedor da conta não concedeu.

---

## Obter um Agente

`GET /agents/{agentId}`

Passe `fields` com uma lista separada por vírgulas para obter de volta apenas o que você precisa, por exemplo `fields=name,active,goal`. O `id` é sempre incluído, e nomes que não existem no Agente são ignorados em vez de rejeitados. Omita-o para obter o documento completo.

**cURL**

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY&fields=name,active,goal"
```

**JavaScript**

```javascript
const res = await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?fields=name,active", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { agent } = await res.json();
```

**Python**

```python
res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"fields": "name,active"},
)
agent = res.json()["agent"]
```

Um Agente que não existe na sua conta retorna `404`.

---

## Atualizar um Agente

`PUT /agents/{agentId}` — envie apenas os campos que você deseja alterar; todo o resto permanece inalterado.

Configurações aninhadas podem ser endereçadas folha por folha com uma chave pontuada, portanto `"availability.monday"` altera apenas a segunda-feira e deixa o restante da semana inalterado.

**Notas**

- Para alterar para qual tipo de evento agendável o Agente faz reservas, envie `event_id` (o id do evento, ou `null` para limpá-lo). Envie `event_ids` com uma matriz para vincular vários de uma vez — o primeiro se torna o principal e `[]` desvincula tudo. `event_id` e `event_ids` são mutuamente exclusivos, e o campo `event` em si não pode ser gravado diretamente.
- `enable_bookings` deve ser um booleano real, e `booking_provider` deve ser um entre `default`, `zenchef`, `formitable`.
- Campos de propriedade e identidade são ignorados, assim como o estado de execução interno (progresso de geração e otimização).
- **O roteamento não é definido aqui.** Use `PUT /entry-points/channel-defaults` para tornar o Agente o respondente de um canal, `POST /agents/{agentId}/entry-points` para regras de palavras-chave e comentários, e `PATCH /agents/{agentId}/active` para pausá-lo ou retomá-lo.

**cURL**

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Answer questions about our listings and always offer a viewing.",
    "anthropic_model": "standard"
  }'
```

**JavaScript**

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ "availability.monday": { start_time: "09:00", end_time: "17:00" } }),
});
```

**Python**

```python
requests.put(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"goal": "Book a viewing within three messages"},
)
```

**Resposta** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Um corpo vazio retorna `400` com `"No fields to update"`.

---

## Atualizar configurações do bot

`PUT /agents/{agentId}/bot-config` — a maneira restrita de alterar apenas as configurações de conversação.

Um Agente não possui uma seção de bot separada: suas configurações ficam diretamente no Agente, portanto, os nomes dos campos aqui são os mesmos que você enviaria para `PUT /agents/{agentId}`. Este endpoint existe como a maneira segura e focada de alterar alguns deles. Pelo menos um campo é obrigatório.

| Campo | Descrição |
|---|---|
| `instructions` | Instruções principais que orientam como o Agente fala com os contatos. |
| `rules` | Regras rígidas que ele deve sempre seguir. |
| `goal` | O resultado pelo qual ele deve trabalhar em cada conversa. |
| `personality` | Descrição do tom de voz e personalidade. |
| `language` | Idioma no qual o Agente responde. |
| `ai_speed` | `fast`, `fast_thinker`, `balanced` ou `thorough`. |
| `anthropic_model` | `standard`, `economy`, `max` ou `mini`. |
| `max_messages` | Número máximo de mensagens do Agente por conversa. |
| `alert_human_when` | Quando o Agente deve alertar um colega de equipe humano. |
| `ai_transparency` | Se o Agente revela que é uma IA. |

> **Os nomes dos campos devem ser nomes simples aqui** — letras, números, sublinhados e hifens. Caminhos pontuados não são aceitos neste endpoint (ao contrário de `PUT /agents/{agentId}`), portanto `bot.goal` é rejeitado com um `400`.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/bot-config?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "goal": "Book a viewing within three messages", "ai_speed": "thorough" }'
```

Textos longos contam contra o tamanho de configuração permitido pelo seu plano, portanto, um conjunto de instruções muito grande pode ser recusado com um `400`.

---

## Definir horário de funcionamento

`PUT /agents/{agentId}/active-hours` — as horas durante as quais o Agente responde automaticamente. Fora dessas janelas, ele permanece inativo.

Envie um objeto `availability` com chaves por dia da semana (`monday` a `sunday`). Cada dia aceita uma única janela de tempo ou uma lista de janelas, no formato `HH:MM` de 24 horas. Os dias que você omitir mantêm o que já tinham, e qualquer chave que não seja um dia da semana é rejeitada — assim, um erro de digitação não pode passar despercebido sem fazer nada.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active-hours?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "availability": {
      "monday": { "start_time": "09:00", "end_time": "17:00" },
      "tuesday": [
        { "start_time": "09:00", "end_time": "12:00" },
        { "start_time": "13:00", "end_time": "17:00" }
      ]
    }
  }'
```

**Resposta** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Uma chave de dia da semana inválida retorna `400`: `"Invalid availability keys: funday. Allowed keys: monday through sunday."`

---

## Pausar ou retomar um Agente

`PATCH /agents/{agentId}/active` — liga ou desliga o Agente. Um Agente pausado mantém toda a sua configuração, mas para de responder imediatamente; a retomada entra em vigor instantaneamente.

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'
```

```javascript
await fetch("https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/active", {
  method: "PATCH",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ active: false }),
});
```

**Resposta** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "active": false }
```

`active` deve ser um booleano real — qualquer outro valor retorna `400` com `"active (boolean) is required"`.

---

## Duplicar um Agente

`POST /agents/{agentId}/duplicate` — cria uma cópia com sua configuração preservada. A cópia não envia nada até que você aponte um canal ou um Ponto de Entrada para ela.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/duplicate?apiKey=YOUR_API_KEY"
```

**Resposta** (`201`)

```json
{ "success": true, "agent_id": "ag9WsX3cRfV6tGyH", "source_agent_id": "ag7HkQ2ZpLxR3mNb" }
```

Uma duplicata conta para o limite de Agentes do seu plano exatamente como criar um do zero, portanto, é recusada com `403` quando a conta atinge o limite.

---

## Excluir um Agente

`DELETE /agents/{agentId}`

A exclusão é recusada enquanto o Agente ainda estiver anexado a algo que pararia de funcionar sem ele — uma transmissão, um Ponto de Entrada ou (em contas mais antigas) uma campanha. A resposta lista o que o está mantendo para que você possa desanexá-los primeiro e tentar novamente.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb?apiKey=YOUR_API_KEY"
```

**Resposta** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

**Bloqueado** (`409`)

```json
{
  "success": false,
  "error": "Agent is still attached to one or more broadcast(s). Detach it first.",
  "blocking_campaign_ids": [],
  "blocking_broadcast_ids": ["bc5TgYhUj8IkOlPm"],
  "blocking_entry_point_ids": []
}
```

---

## Rascunhos: revise as alterações antes que entrem em vigor

As edições feitas no editor e qualquer reescrita produzida pelo [Otimizar com IA](#optimize-an-agent-with-ai) são mantidas como um **rascunho não publicado** até que você as publique. O Agente ativo continua respondendo com sua configuração atual até lá.

### Publicar o rascunho

`POST /agents/{agentId}/publish-draft` — move o rascunho para a configuração ativa e limpa o rascunho na mesma etapa.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/publish-draft?apiKey=YOUR_API_KEY"
```

**Resposta** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "published_keys": ["instructions", "goal"] }
```

`published_keys` lista as configurações que foram movidas do rascunho para o Agente ativo, para que você possa mostrar o que mudou.

> **Verifique se um rascunho existe antes de chamar isso.** Publicar um Agente que não possui rascunho não é uma chamada suportada e atualmente retorna um `500` com uma mensagem genérica, não específica. Para descartar um rascunho, use o descarte abaixo.

### Descartar o rascunho

`POST /agents/{agentId}/discard-draft` — descarta o rascunho e deixa a configuração ativa exatamente como está. É seguro chamar quando não há rascunho; nada acontece.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/discard-draft?apiKey=YOUR_API_KEY"
```

---

## Otimizar um Agente com IA

`POST /agents/{agentId}/optimize` — reescreve a configuração do Agente a partir do seu feedback ("ele continua oferecendo descontos", "as respostas são muito longas") e salva a reescrita **como um rascunho** em vez de colocá-la em produção.

Envie `user_feedback` (uma instrução simples) ou, ao reagir a uma resposta ruim específica, `thumbs_down_feedback` junto com a `thumbs_down_message` ofensiva. Pelo menos um dos dois deve conter texto.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/optimize?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "user_feedback": "Keep replies under three sentences." }'
```

**Resposta** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb" }
```

O trabalho é executado em segundo plano e a chamada retorna imediatamente. Leia o Agente com `GET /agents/{agentId}` e observe `optimize_run.status`; assim que ele voltar para `Draft`, a reescrita estará aguardando como rascunho do Agente. Revise-a e, em seguida, publique-a ou descarte-a.

Apenas uma execução por vez por Agente — uma segunda chamada enquanto uma está em andamento retorna `409`. Isso utiliza créditos de IA.

---

## Regras de marcação

Uma regra de marcação é uma tag mais uma descrição de quando ela se aplica. Durante uma conversa, o Agente lê essa descrição e marca o contato quando ela se encaixa, que é como as automações baseadas em tags são acionadas.

**O objeto de regra**

| Campo | Obrigatório | Descrição |
|---|---|---|
| `name` | Sim | A tag a ser aplicada, por exemplo `hot-lead`. |
| `description` | Não | Quando o Agente deve aplicá-la, escrita como uma instrução que ele segue. |
| `webhook` | Não | URL chamada quando o Agente aplica esta tag. |
| `ai_can_remove` | Não | Se o Agente também pode remover a tag novamente. O padrão é `false`. |
| `tag_id` | Não | ID de uma tag existente em sua conta para vincular a regra. Sem ele, a regra é vinculada à tag com o mesmo nome, criando-a se não existir — assim, toda regra pode ser endereçada pelo ID da tag posteriormente. |

### Adicionar uma regra de marcação

`POST /agents/{agentId}/tags`

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": {
      "name": "hot-lead",
      "description": "Apply when the contact asks about pricing or wants to book a call.",
      "ai_can_remove": false
    }
  }'
```

**Resposta** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "tag": { "name": "hot-lead", "...": "..." } }
```

### Substituir uma regra de marcação

`PUT /agents/{agentId}/tags/{tagId}` — a regra é encontrada pelo ID da tag no caminho e **substituída integralmente**, não mesclada, portanto, envie a regra completa em vez de apenas a parte que você está alterando. A tag para a qual ela aponta é preservada mesmo se você omitir `tag_id`, portanto, uma edição não pode desvincular a regra de sua tag.

```bash
curl -X PUT "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": { "name": "hot-lead", "description": "Apply only when the contact asks to book a call." } }'
```

### Remover uma regra de marcação

`DELETE /agents/{agentId}/tags/{tagId}` — o Agente para de aplicar essa tag. A tag em si, e quaisquer contatos que já a possuam, permanecem inalterados.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/tg8YuIoP2aSdF3gH?apiKey=YOUR_API_KEY"
```

Ambos os endpoints retornam `404` quando o Agente não existe **ou** quando ele não possui nenhuma regra para essa tag.

### Gerar um conjunto de tags com IA

`POST /agents/{agentId}/tags/generate` — projeta um conjunto completo de regras (os nomes das tags e a redação "aplicar quando..." por trás de cada uma) lendo as próprias instruções e o objetivo do Agente.

| Campo | Descrição |
|---|---|
| `mode` | `merge` (o padrão) mantém as regras já existentes no Agente e as complementa. `replace` projeta o conjunto do zero. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/tags/generate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "merge" }'
```

**Resposta** (`202`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mode": "merge" }
```

O trabalho é executado em segundo plano. Leia o Agente e observe `tag_generation.status`; as regras em si são inseridas em `tags` do Agente. Apenas uma execução por vez por Agente (`409` caso contrário), e isso consome créditos de IA.

---

## Fontes de conhecimento

Fontes de conhecimento são as páginas e documentos que a plataforma leu para você. Anexar uma a um Agente permite que ele responda com base nesse conteúdo.

**De onde vêm os IDs de origem.** Adicione conteúdo com os endpoints da base de conhecimento — `POST /kb-sources/url` para uma página, `POST /kb-sources/file` para um documento, `POST /kb-sources/bulk-import` para um site inteiro. Eles retornam um `source_id` que você consulta com `GET /kb-sources/{sourceId}` até que esteja pronto. `POST /kb-sources/url` também aceita `autoLinkToAgentId`, que anexa a fonte a um Agente assim que a importação termina, para que você possa pular a chamada de anexo abaixo.

### Anexar fontes de conhecimento

`POST /agents/{agentId}/kb-sources` — envie `kb_source_ids` com uma lista para anexar um conjunto inteiro em uma única chamada (o que você deseja após rastrear um site), ou `kb_source_id` para uma única fonte. Envie uma ou outra. Anexar algo que já está anexado não altera nada.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"] }'
```

**Resposta** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "kb_source_id": "kb2QwErTyUi9OpAs",
  "kb_source_ids": ["kb2QwErTyUi9OpAs", "kb6ZxCvBnM4kLjHg"]
}
```

### Desanexar fontes de conhecimento

`DELETE /agents/{agentId}/kb-sources/{kbSourceId}` para um, ou `POST /agents/{agentId}/kb-sources/bulk-remove` com `kb_source_ids` para vários. A remoção em massa é um `POST` porque a lista de IDs é enviada no corpo da requisição.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/kb-sources/bulk-remove?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kb_source_ids": ["kb2QwErTyUi9OpAs"] }'
```

As fontes em si não são excluídas e permanecem disponíveis para seus outros Agentes. Desanexar algo que não está anexado não altera nada.

### Perguntas Frequentes (FAQs)

As FAQs são gerenciadas em seus próprios endpoints e vinculadas a um Agente a partir deles: `POST /faqs/{faqId}/link` com `{ "agent_id": "ag7HkQ2ZpLxR3mNb" }`, e `POST /faqs/{faqId}/unlink` para removê-las novamente. Uma FAQ pode ser compartilhada por qualquer número de Agentes. Veja a [API de FAQs](faqs.md).

> Uma FAQ só é usada pelos Agentes aos quais está vinculada — criá-la não é suficiente por si só.

---

## Ferramentas

### Funções personalizadas

`POST /agents/{agentId}/custom-functions` permite que o Agente chame uma de suas funções personalizadas durante as conversas. Apenas funções pertencentes à mesma conta podem ser anexadas, e anexar uma que já esteja anexada não altera nada.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/custom-functions?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "custom_function_id": "cf7Hk2ZpLxR3mNbV" }'
```

`DELETE /agents/{agentId}/custom-functions/{customFunctionId}` a desanexa. A função em si não é excluída e permanece disponível para seus outros Agentes.

Gerencie as funções em `/custom-functions` — veja [Funções Personalizadas](../ai-automation/custom-functions.md) para saber o que são.

### Servidores MCP

Um servidor MCP é um pacote pronto de ferramentas que seu Agente pode descobrir e chamar por conta própria — veja [Conectar Servidores MCP ao Seu Bot](../ai-automation/mcp-servers.md). Os servidores são registrados uma vez na conta e, em seguida, anexados aos Agentes que devem usá-los.

> Os servidores MCP exigem o recurso de **funções personalizadas** em seu plano. Sem ele, os endpoints de nível de conta `/mcp-servers` retornam `403`. Anexar um servidor já registrado a um Agente não é restrito.

#### Registrar um servidor

`POST /mcp-servers`

| Campo | Obrigatório | Descrição |
|---|---|---|
| `name` | Sim | Um rótulo para o servidor. |
| `url` | Sim | O endereço do servidor. Deve ser acessível pela internet pública. |
| `auth_type` | Não | `header` (o padrão) para um cabeçalho de autenticação estático, ou `oauth2`. |
| `auth_header_name` | Não | Cabeçalho para enviar a credencial. O padrão é `Authorization`. |
| `auth_header_value` | Não | A credencial em si. Nunca retornada em nenhuma resposta. |
| `enabled` | Não | Se o servidor está disponível para Agentes. O padrão é `true`. |
| `enabled_tools` | Não | Lista de permissões de nomes de ferramentas. `null` significa que todas as ferramentas que o servidor oferece estão ativadas. |
| `tool_policies` | Não | Limites por ferramenta, indexados pelo nome da ferramenta — com que frequência uma ferramenta pode ser disparada, cache de resultados e uma substituição somente leitura. Passe `null` para limpar todos eles. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inventory",
    "url": "https://tools.example.com/mcp",
    "auth_header_value": "Bearer sk_live_xxx"
  }'
```

**Resposta** (`201`)

```json
{
  "success": true,
  "server_id": "ms4TgBnH7yUj2kLp",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }],
  "last_error": null,
  "server": { "server_id": "ms4TgBnH7yUj2kLp", "name": "Inventory", "...": "..." }
}
```

Ao salvar, a plataforma conecta-se ao servidor e faz cache da lista de ferramentas que ele oferece. **Um servidor que não pode ser alcançado ainda é salvo**, com o motivo em `last_error` e uma lista de ferramentas vazia — para que você possa registrar primeiro e corrigir a conectividade depois.

Um `auth_type` de `oauth2` salva o registro com `oauth_connected: false` e sem ferramentas: ainda não há token. Autorizar um servidor OAuth requer um login via navegador e é feito pelo painel, não pela API.

#### Listar, atualizar e excluir servidores

- `GET /mcp-servers` — todos os servidores registrados, do mais recente para o mais antigo, em `servers`.
- `PUT /mcp-servers/{serverId}` — envie apenas o que deseja alterar. Alterar a URL ou os campos de autenticação testa novamente a conexão e atualiza a lista de ferramentas em cache.
- `DELETE /mcp-servers/{serverId}` — remove o registro e desvincula-o de todos os Agentes e campanhas que o tinham ativado.

```bash
curl "https://api.youraiconnector.com/v1/mcp-servers?apiKey=YOUR_API_KEY"
```

**Segredos nunca retornam.** As respostas trazem `auth_header_value_set` (um sinalizador `true`/`false` informando que um valor está armazenado) em vez da credencial, e tokens OAuth e segredos de cliente permanecem no lado do servidor. Todo o resto é retornado: `name`, `url`, `enabled`, `auth_type`, `auth_header_name`, `tools`, `enabled_tools`, `tool_policies`, `oauth_connected`, `tools_cached_at`, `last_connected_at`, `last_error`, `created_at`, `updated_at`.

#### Testar uma conexão

`POST /mcp-servers/test-connection` — conecta-se a um servidor e lista suas ferramentas. Duas maneiras de chamá-lo:

- com `server_id` — testa a configuração **salva** e atualiza sua lista de ferramentas em cache;
- com um `url` em linha (mais `auth_header_name` / `auth_header_value`) — um teste pré-salvamento que não armazena nada.

```bash
curl -X POST "https://api.youraiconnector.com/v1/mcp-servers/test-connection?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://tools.example.com/mcp", "auth_header_value": "Bearer sk_live_xxx" }'
```

**Resposta** (`200`)

```json
{
  "success": true,
  "server_name": "Inventory tools",
  "tools": [{ "name": "check_stock", "description": "Look up stock for a SKU." }]
}
```

Uma falha de conexão **não** é um erro HTTP — você recebe um `200` com `success: false` e um `error` descrevendo o que deu errado, para que você possa exibi-lo ao lado do campo que o operador está editando.

#### Anexar um servidor a um Agente

Registrar um servidor não dá a nenhum Agente acesso a ele. Anexe-o:

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/mcp-servers?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mcp_server_id": "ms4TgBnH7yUj2kLp" }'
```

**Resposta** (`200`)

```json
{ "success": true, "agent_id": "ag7HkQ2ZpLxR3mNb", "mcp_server_id": "ms4TgBnH7yUj2kLp" }
```

`DELETE /agents/{agentId}/mcp-servers/{mcpServerId}` desanexa-o novamente. O servidor em si não é excluído e permanece disponível para seus outros Agentes. Anexar ou desanexar algo que já está nesse estado não altera nada.

---

## Biblioteca de mídia

A biblioteca de mídia armazena os arquivos que um Agente pode enviar durante uma conversa — um menu, uma lista de preços, uma foto de produto. Um Agente pode conter no máximo **50 itens**.

### Listar mídia

`GET /agents/{agentId}/media-library`

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY"
```

**Resposta** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "media_items": [
    {
      "id": "mi4RtY7uIoP1aSdF",
      "item_id": "mi4RtY7uIoP1aSdF",
      "media_home": "agent",
      "title": "Spring menu",
      "description": "Send when someone asks what is on the menu.",
      "ai_description": "A one-page menu listing seasonal dishes and prices.",
      "type": "document",
      "media_content_type": "application/pdf",
      "media_url": "https://storage.googleapis.com/...",
      "max_sends_per_conversation": 1,
      "created_at": 1700000000000
    }
  ]
}
```

Os itens armazenados no Agente aparecem primeiro, seguidos por quaisquer itens mais antigos ainda armazenados na campanha a partir da qual o Agente foi criado; `media_home` (`agent` ou `campaign`) indica qual é qual. Dentro de cada grupo, o mais recente aparece primeiro.

> **`media_url` expira após 7 dias.** É o link de download criado quando o arquivo foi carregado — trate um link antigo como obsoleto em vez de quebrado, e leia a lista novamente para obter um link atualizado.

### Carregar mídia

`POST /agents/{agentId}/media-library` — o arquivo é carregado inline como base64, até **10 MB**. A chamada retorna assim que o arquivo é armazenado, portanto, permita um pouco mais de tempo do que para uma solicitação normal. Observe que este corpo usa nomes de campo em camelCase.

| Campo | Obrigatório | Descrição |
|---|---|---|
| `base64Data` | Sim | Conteúdo do arquivo, codificado em base64, sem um prefixo data-URL. |
| `mimeType` | Sim | Tipo MIME do arquivo. |
| `fileName` | Sim | Nome original do arquivo, usado para nomear o arquivo armazenado. |
| `title` | Não | Rótulo curto exibido na biblioteca. |
| `description` | Não | A instrução "quando o Agente deve enviar isto". |
| `sendMessage` | Não | Texto preferencial que o Agente diz ao enviar o item. Limitado a 500 caracteres. |
| `maxSendsPerConversation` | Não | Quantas vezes pode ser enviado para o mesmo contato em uma conversa. O padrão é `1`. |
| `sendAsVoiceNote` | Não | Apenas uploads de áudio — armazena o arquivo como uma nota de voz do WhatsApp. Ignorado para outros tipos de arquivo. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "base64Data": "JVBERi0xLjQKJcfs...",
    "mimeType": "application/pdf",
    "fileName": "spring-menu.pdf",
    "title": "Spring menu",
    "description": "Send when someone asks what is on the menu.",
    "maxSendsPerConversation": 1
  }'
```

Duas coisas acontecem automaticamente: um GIF animado é convertido em vídeo para que seja reproduzido em todos os canais, e a plataforma escreve um breve resumo do que realmente está no arquivo para que o Agente saiba quando ele se encaixa.

Um `400` cobre campos ausentes, um tipo de arquivo não suportado, um arquivo vazio ou muito grande, e atingir o limite de 50 itens. Um `403` significa que a biblioteca de mídia está desativada para a conta.

### Atualizar um item de mídia

`PATCH /agents/{agentId}/media-library/{itemId}` — apenas metadados. O arquivo em si não pode ser substituído; carregue um novo item e exclua o antigo. Este corpo usa snake_case: `title`, `description`, `send_message`, `max_sends_per_conversation` (um número inteiro não negativo, ou `null` para limpar o limite).

```bash
curl -X PATCH "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Summer menu", "max_sends_per_conversation": 2 }'
```

**Resposta** (`200`)

```json
{
  "success": true,
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "item_id": "mi4RtY7uIoP1aSdF",
  "campaign_id": "",
  "media_home": "agent"
}
```

### Excluir um item de mídia

`DELETE /agents/{agentId}/media-library/{itemId}` — remove o item e seu arquivo armazenado. Excluir um item que já se foi é bem-sucedido e retorna `deleted: false`, portanto, a chamada é segura para tentar novamente.

```bash
curl -X DELETE "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/media-library/mi4RtY7uIoP1aSdF?apiKey=YOUR_API_KEY"
```

---

## Gerar mensagens de acompanhamento

`POST /agents/{agentId}/template-generation` — escreve as mensagens de acompanhamento do Agente para você (os lembretes que ele envia quando uma conversa fica silenciosa), com base na finalidade do Agente.

| Campo | Descrição |
|---|---|
| `type` | `all` (o padrão) grava o conjunto completo. `cold_only` grava apenas as mensagens para contatos que nunca responderam. |

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'
```

Existem duas maneiras de isso retornar, e o campo `target` informa qual:

- **`target: "agent"` com um `200`** — as mensagens foram gravadas durante a chamada e o resultado está em `data`. Leia-as a partir do `follow_up_config` do Agente. Este é o caso comum.
- **`target: "campaign"` com um `202`** — o trabalho foi colocado na fila da campanha nomeada em `campaign_id`. Monitore o `template_generation_status` dessa campanha até que ela termine.

`cold_only` requer uma campanha de saída e é recusado com `409` (`reason: "cold_only_requires_campaign"`) em um Agente que não possui nenhuma. Um `403` significa que os acompanhamentos automáticos não estão ativados para a conta. Isso utiliza créditos de IA, e um `400` com `"Insufficient credits."` significa que a conta não possui créditos.

---

## Encaminhando conversas para um Agente

Um Agente só responde às conversas que um **Ponto de Entrada** envia para ele. Até que um canal tenha um, a primeira mensagem de alguém com quem você nunca falou ainda é armazenada, mas nada a captura e nenhum assistente responde.

| O que você deseja fazer | Chamada |
|---|---|
| Tornar um Agente o responsável por responder a um canal inteiro | `PUT /entry-points/channel-defaults` com `{ "channel": "instagram", "agent_id": "AGENT_ID" }` |
| Adicionar uma regra mais específica (palavras-chave, comentários, novos seguidores) | `POST /agents/{agentId}/entry-points` |
| Ver as regras apontando para um Agente | `GET /agents/{agentId}/entry-points` |
| Deixar um canal sem ninguém respondendo | `DELETE /entry-points/channel-defaults?channel=instagram` |

### Listar os Pontos de Entrada de um Agente

`GET /agents/{agentId}/entry-points` — as regras de roteamento que enviam conversas para este Agente, da mais recente para a mais antiga. Tanto as regras atuais quanto as inativas retornam; uma regra inativa possui `enabled: false`.

```bash
curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"
```

Para os padrões de canal de toda a conta, incluindo um canal deliberadamente definido como sem ninguém, leia `GET /entry-points/channel-defaults` em vez disso.

### Criar um Ponto de Entrada

`POST /agents/{agentId}/entry-points` — o Agente no caminho sempre vence, portanto, uma regra nunca pode ser criada para um Agente diferente daquele na URL.

| `type` | O que faz |
|---|---|
| `channel_default` | O Agente responde a cada novo contato nos canais listados. Prefira `PUT /entry-points/channel-defaults` para isso — ele inativa o responsável anterior para você, o que criar um segundo padrão aqui não faz. |
| `keyword` | O Agente assume quando a primeira mensagem contém uma das `match_config.keywords`. Pelo menos uma palavra-chave é necessária. |
| `instagram_comment` / `facebook_comment` | O Agente responde a comentários em suas postagens. O canal correspondente deve estar listado em `channels`. |
| `instagram_follower` | O Agente cumprimenta novos seguidores. |

`channels` é obrigatório e indica quais canais a regra cobre — por exemplo `whatsapp`, `whatsapp_web`, `instagram`, `messenger`, `telegram`, `sms`, `email`, `chat_widget` ou `custom_channel`. Novas regras são habilitadas, a menos que você especifique o contrário.

```bash
curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'
```

**Resposta** (`201`)

```json
{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }
```

**Qual regra vence quando várias podem:** uma conversa em andamento ou uma atribuição manual mantém o Agente que já possui; caso contrário, as regras de palavra-chave superam as regras de comentário, que superam as regras de seguidor, e um padrão de canal é o último recurso. Se essas regras decidem algo em uma conta é relatado por `GET /entry-points/routing-status`.

Esta é a versão resumida. O guia da [Entry Points API](entry-points.md) cobre todas as regras de ladder, comentários e seguidores, um Agente por número de WhatsApp, e como alterar ou excluir uma regra. Consulte [Entry Points](../ai-agents/entry-points.md) para o conceito, e a [Channels API](channels.md) para conectar o canal em si.

---

## Erros da API de Agentes de IA

Os endpoints de Agente retornam o envelope de erro padrão:

```json
{
  "success": false,
  "error": "Agent not found"
}
```

| Status | Quando ocorre em um endpoint de Agente |
|---|---|
| `400` | Um campo obrigatório está ausente ou inválido — um corpo de atualização vazio, um valor fora de uma lista permitida (`ai_speed`, `anthropic_model`, `booking_provider`, `mode`, `type`), uma chave que não é um dia da semana em `availability`, um nome de campo com pontos em `bot-config`, ou um ID malformado no caminho. |
| `403` | A conta não tem permissão para usar uma configuração que você enviou, você atingiu o limite de Agentes do seu plano, ou um recurso necessário para este endpoint (biblioteca de mídia, follow-ups, funções personalizadas para servidores MCP) está desativado. Uma alteração que excede o tamanho de configuração permitido pelo seu plano é recusada com `400`. |
| `404` | O Agente, regra de tag, item de mídia ou servidor MCP não foi encontrado — ou ele não existe ou pertence a outra conta. |
| `409` | Algo já está em processamento ou bloqueando: uma otimização ou geração de tag está em execução, o Agente ainda está vinculado a uma transmissão, Ponto de Entrada ou campanha, ou `cold_only` foi solicitado sem uma campanha de saída. |

Os códigos compartilhados que todo endpoint pode retornar — `401`, `403` (seu plano não inclui acesso à API), `429` (limite de taxa) e `500` — estão listados com orientações de nova tentativa em [Erros e Paginação](errors-and-pagination.md).

> **Uma nota sobre o explorador.** Os endpoints `/agents` estão na especificação OpenAPI publicada, então você pode navegar pelos seus campos exatos e executar solicitações ao vivo na [Referência da API](reference.md). Os endpoints `/mcp-servers` em nível de conta também estão na especificação, então você pode explorá-los lá também.


---

## Relacionado

- [Agentes de IA](../ai-agents/ai-agents.md) — o que é um Agente, em linguagem simples.
- [Pontos de Entrada](../ai-agents/entry-points.md) — como as conversas são direcionadas para um Agente.
- [API de FAQs](faqs.md) — crie e vincule o conhecimento a partir do qual seu Agente responde.
- [API de Canais](channels.md) — conecte os canais nos quais um Agente responde.
- [Conecte Servidores MCP ao Seu Bot](../ai-automation/mcp-servers.md) · [Funções Personalizadas](../ai-automation/custom-functions.md)
- [Referência da API](reference.md) — o explorador de endpoints interativo completo.