# Guia para agentes

## Objetivo

Use este guia quando outro agente, automacao, orquestrador ou backend precisa descobrir rapidamente como chamar o ChatAgent.

O endpoint de descoberta e:

```http
GET /api/agents/manifest
Authorization: Bearer SUA_API_KEY
```

`/api/agent/manifest` continua aceito como alias de compatibilidade, mas a rota canonica e `/api/agents/manifest`.

Ele nao consome creditos e nao altera dados. A resposta e um manifesto JSON com:

- endpoint recomendado
- endpoints disponiveis
- campos obrigatorios
- exemplos de payload
- status de erro que a integracao deve tratar
- regra de memoria por `actor.id` e `conversation.id`

## Exemplo rapido

```bash
curl https://chatagentai.online/api/agents/manifest \
  -H "Authorization: Bearer SUA_API_KEY"
```

Resposta resumida:

```json
{
  "object": "chatagent.agent_manifest",
  "version": "2026-06-05",
  "service": "ChatAgent",
  "recommended_endpoint": {
    "method": "POST",
    "path": "/api/messages",
    "description": "Contrato principal para agentes e integracoes multi-canal."
  },
  "conversation_memory": {
    "stable_keys": ["actor.id", "conversation.id"],
    "guidance": "Use os mesmos IDs para a mesma pessoa e a mesma conversa; IDs variando quebram a continuidade."
  }
}
```

## Fluxo recomendado para um agente

1. Chame `GET /api/agents/manifest` com a API key recebida.
2. Leia `recommended_endpoint.path`.
3. Monte o payload usando `example_request` do endpoint escolhido.
4. Envie a mensagem para `POST /api/messages`.
5. Use `reply` como texto final.
6. Salve `thread_id` em log para rastreio.

## Contrato principal para agentes

```http
POST /api/messages
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
```

```json
{
  "actor": {
    "id": "lead:maria@example.com",
    "type": "lead",
    "name": "Maria"
  },
  "conversation": {
    "id": "site:maria@example.com",
    "channel": "web"
  },
  "message": {
    "text": "Quero entender os planos"
  },
  "metadata": {
    "source": "agent-integration"
  }
}
```

## Quando usar WhatsApp

Se a API key usada no manifesto retornar:

```json
{
  "authentication": {
    "type": "number"
  }
}
```

o endpoint `/api/whatsapp/message` nao precisa de `number_id`.

Se retornar:

```json
{
  "authentication": {
    "type": "tenant"
  }
}
```

o endpoint `/api/whatsapp/message` exige `number_id`.

Para novos agentes multi-canal, prefira `/api/messages`.

## Quando usar OpenAI-compatible

Use `/v1/chat/completions` ou `/v1/responses` quando o agente ja fala formato OpenAI-compatible e voce quer trocar apenas `base_url` e API key.

Para integracoes novas controladas por voce, `/api/messages` e mais explicito e mais facil de diagnosticar.

## Erros que o agente deve tratar

- `400`: payload invalido ou campo obrigatorio ausente
- `401`: API key ausente ou invalida
- `402`: creditos insuficientes
- `429`: rate limit excedido
- `503`: provedor temporariamente indisponivel

## Regra de memoria

A continuidade depende de estabilidade:

- mesmo `actor.id` para a mesma pessoa
- mesmo `conversation.id` para a mesma conversa

Nao use IDs temporarios de evento como conversa. Isso cria uma conversa nova a cada chamada.