---
name: catcher-agents
description: >-
  Catcher Agents dá ao seu produto agentes de IA com memória por usuário
  final, conhecimento próprio com citação (RAG) e ferramentas REST — embutíveis
  por um runtime token + REST/SSE. Esta skill é o MAPA do pacote: quickstart
  em 3 chamadas, uma referência .md por grupo de endpoints e scripts de
  conta/validação/smoke — puxe só o arquivo que a tarefa atual pede.
---

# Catcher Agents

Catcher Agents é uma plataforma multi-tenant de agentes de IA que lembram (memória por usuário final), sabem (conhecimento próprio com citação, RAG) e agem (ferramentas REST criadas por IA). Você monta o agente no Console e o embute em qualquer produto por uma API REST com streaming SSE, com custo medido por execução.

- **Console (montar o agente):** https://agents.catcher.one
- **API REST + SSE:** https://agents-api.catcher.one (versão v1, JSON, UTF-8)
- **Comece grátis:** https://agents-app.catcher.one/register — ou programe: `bash <(curl -s https://agents.catcher.one/skill/scripts/create-account.sh) --email voce@empresa.com`

## Como usar esta skill

Este arquivo é o **mapa**. O pacote tem três camadas — puxe sob demanda
(cada URL é `text/plain`, pronta para `curl`, não HTML):

1. **Referências** (`/skill/references/*.md`) — o contrato detalhado de
   UM grupo de endpoints. Leia só o arquivo da tarefa atual.
2. **Scripts** (`/skill/scripts/*.sh`) — criar conta, validar credencial,
   ver se a API está de pé, smoke-testar o embed.
3. **Skills por capacidade** (`/skills/<cap>/SKILL.md`) — um dossiê
   autocontido por área (embed, agentes, conhecimento, memória, …).

Tudo é gerado do mesmo manual público — se discordarem, o manual manda:
`curl https://agents.catcher.one/llms-full.txt` (contexto completo em 1 fetch).

## Pegue as credenciais

Você monta o agente no Console (modelo, prompt, ferramentas, conhecimento) e o dirige pela API. Três credenciais, cada uma para um caso:

| Credencial | Header | Uso |
| --- | --- | --- |
| Runtime token `prt_` | `X-Agent-Token: prt_…` | Embed — um app externo dirige **um** agente (auth por header, sem CSRF). Gere na aba de runtime tokens do agente (owner-only, mostrado uma vez). |
| API key `ctc_` | `X-API-Key: ctc_…` | Servidor-a-servidor autenticado como a sua conta. Guardada com hash — a chave crua aparece uma vez. |
| JWT | `Authorization: Bearer <jwt>` | Sessão do Console (login → refresh + CSRF). |

Para embutir um agente no seu app, o caminho é o **runtime token `prt_`**. Sem conta ainda? `POST /v1/auth/quick-register` cria uma programaticamente (veja a referência `autenticacao`).

## Embuta um agente em 3 chamadas

Do zero ao primeiro turno, embutindo o agente no seu app, em três passos.

### GET 1. Crie o agente e o token no Console

Crie a conta em `https://agents-app.catcher.one/register` — ou programaticamente
via `POST /v1/auth/quick-register` (veja Autenticação) — monte um agente (nome,
modelo, prompt, ferramentas, conhecimento) e copie o `AGENT_ID` da URL da página
do agente. Na aba de tokens de runtime do agente, gere um `prt_` (owner-only —
mostrado uma vez).

### POST 2. Abra uma sessão

Cada sessão é isolada por usuário final via `end_user_external_id` — é esse id
que separa a memória de um cliente do outro.

```bash
curl -X POST https://agents-api.catcher.one/v1/agent-runtime/AGENT_ID/sessions \
  -H "X-Agent-Token: prt_SEU_RUNTIME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "end_user_external_id": "cliente-42", "title": "Atendimento" }'
```

Resposta `201 Created`:

```json
{ "id": "sess_a1b2c3", "agent_id": "AGENT_ID", "title": "Atendimento", "created_at": "2026-07-02T01:00:00Z" }
```

### POST 3. Mande a mensagem

```bash
curl -X POST https://agents-api.catcher.one/v1/agent-runtime/AGENT_ID/sessions/sess_a1b2c3/messages \
  -H "X-Agent-Token: prt_SEU_RUNTIME_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Qual foi o último pedido do cliente?" }'
```

A resposta traz o turno completo (memória + conhecimento + ferramentas aplicados)
num envelope — o texto do agente está em `assistant_message.content`:

```json
{
  "run_id": "9f2c…",
  "user_message": { "id": "…", "role": "user", "content": "Qual foi o último pedido do cliente?", "…": "…" },
  "assistant_message": { "id": "…", "role": "assistant", "content": "O último pedido foi #4821…", "run_id": "9f2c…", "…": "…" },
  "usage": { "input_tokens": 812, "output_tokens": 143, "total_tokens": 955 },
  "provider": "engine",
  "model": "gpt-5.4-mini",
  "tool_calls": [ { "name": "brain_search", "is_error": false, "…": "…" } ]
}
```

Pronto — o agente está embutido. Para uma UX ao vivo (token a token), use a
variante de streaming (Streaming SSE).

## Mapa da skill — referências por grupo de endpoints

| Arquivo | Cobre | Leia quando |
| --- | --- | --- |
| [`autenticacao.md`](https://agents.catcher.one/skill/references/autenticacao.md) | Autenticação | Escolher/formatar a credencial (ctc_, JWT, prt_) e criar conta programaticamente (quick-register). |
| [`inicio-rapido.md`](https://agents.catcher.one/skill/references/inicio-rapido.md) | Início rápido | Do zero ao primeiro turno em 3 passos — o quickstart mínimo. |
| [`runtime.md`](https://agents.catcher.one/skill/references/runtime.md) | Runtime — embutir um agente | Sessões e mensagens via X-Agent-Token (prt_) — o contrato do embed. |
| [`streaming-sse.md`](https://agents.catcher.one/skill/references/streaming-sse.md) | Streaming (SSE) | Token a token ao vivo: o catálogo de eventos SSE do turno. |
| [`agentes.md`](https://agents.catcher.one/skill/references/agentes.md) | Agentes | CRUD de agentes, clone, eval (A/B de modelos), versionamento, stats, run_class. |
| [`sessoes-e-mensagens.md`](https://agents.catcher.one/skill/references/sessoes-e-mensagens.md) | Sessões e mensagens | Chat via JWT/ctc_: sessões, mensagens (+stream), runs, traço do turno, end-users, export. |
| [`conhecimento.md`](https://agents.catcher.one/skill/references/conhecimento.md) | Conhecimento (RAG) | Semear texto/arquivos, gerir fontes (pausar/reindexar/remover), buscar com citação, Q&A e Refinery. |
| [`memoria.md`](https://agents.catcher.one/skill/references/memoria.md) | Memória | Insights L3, memórias L4, memória de conversa verbatim, ciclo dream (consolidação) — o agente que aprende. |
| [`ferramentas-e-skills.md`](https://agents.catcher.one/skill/references/ferramentas-e-skills.md) | Ferramentas e skills | Catálogos, ferramentas REST próprias (+cofre de segredos), skills e bindings por agente. |
| [`uso-e-custo.md`](https://agents.catcher.one/skill/references/uso-e-custo.md) | Uso e custo | Métricas agregadas, budget mensal — medir e limitar gasto. |
| [`tokens-de-acesso.md`](https://agents.catcher.one/skill/references/tokens-de-acesso.md) | Tokens de acesso | Emitir/inspecionar/revogar JWT, API keys (ctc_) e runtime tokens (prt_, incl. tenant-scoped). |
| [`projetos-e-tenants.md`](https://agents.catcher.one/skill/references/projetos-e-tenants.md) | Projetos e tenants | Hierarquia Conta→Projeto→Tenant; criar/gerir tenants com schema dedicado. |
| [`provedores-e-midia.md`](https://agents.catcher.one/skill/references/provedores-e-midia.md) | Provedores e mídia | Saúde dos provedores de LLM e upload/download de mídia. |
| [`convencoes.md`](https://agents.catcher.one/skill/references/convencoes.md) | Convenções | Envelope de erro, idempotência, listas, status codes, pegadinhas do contrato. |
| [`codigos-de-erro.md`](https://agents.catcher.one/skill/references/codigos-de-erro.md) | Códigos de erro | Tabela completa de error_code → HTTP → significado. |

## Scripts utilitários

Baixe e rode (`chmod +x` após o download; todos aceitam `--help`):

| Script | Faz | Uso |
| --- | --- | --- |
| [`check-api-up.sh`](https://agents.catcher.one/skill/scripts/check-api-up.sh) | Proba /health e /ready; exit 0=up, 1=degradado, 2=fora. Sem dependências (curl + grep). | `bash check-api-up.sh` |
| [`create-account.sh`](https://agents.catcher.one/skill/scripts/create-account.sh) | Cria a conta programaticamente e valida a API key; com --out grava um env file (chmod 600) com CATCHER_API_KEY/CATCHER_PASSWORD. | `bash create-account.sh --email voce@empresa.com --out ~/.config/catcher-agents.env` |
| [`validate-token.sh`](https://agents.catcher.one/skill/scripts/validate-token.sh) | Detecta o tipo pelo prefixo (prt_ cria uma sessão-sonda sem custo de run; ctc_/JWT lê /v1/agents) e diz se a credencial está viva. | `bash validate-token.sh ctc_…  ·  bash validate-token.sh prt_… --agent-id AGENT_ID` |
| [`smoke-embed.sh`](https://agents.catcher.one/skill/scripts/smoke-embed.sh) | Cria uma sessão, manda uma mensagem e imprime a resposta + telemetria (usage/custo/tools); --stream consome o SSE cru. | `bash smoke-embed.sh --agent-id AGENT_ID --token prt_… [--stream]` |
| [`test-custom-tool.sh`](https://agents.catcher.one/skill/scripts/test-custom-tool.sh) | O caminho feliz das ferramentas custom: upsert do segredo (nome no alfabeto do resolvedor) → cria a ferramenta → anexa ao tools[] do agente (união — sem isso o modelo nunca a vê) → dry-run real que mostra o que o endpoint recebeu. | `CATCHER_API_KEY=ctc_… bash test-custom-tool.sh --agent-id AGENT_ID --tool-name http_x --tool-url URL [--secret-name K --secret-value V --header "H: ${secret:K}"]` |

Ordem sugerida do primeiro contato: `check-api-up.sh` → `create-account.sh`
→ crie o agente no Console → `validate-token.sh` → `smoke-embed.sh`.

## Skills por capacidade

Cada uma é um dossiê autocontido (referência + auth + erros da área):

- **Embutir um agente** — Rode um agente Catcher no seu app em 3 chamadas: token de runtime (prt_) → sessão → mensagem, com streaming por SSE token a token.
  `curl https://agents.catcher.one/skills/embed/SKILL.md`
- **Agentes e conversas** — Gerencie agentes (CRUD, clone, stats) e conduza conversas: sessões, mensagens, runs e exportação.
  `curl https://agents.catcher.one/skills/agents/SKILL.md`
- **Conhecimento (RAG)** — Dê conhecimento próprio ao agente: adicione texto/arquivos, busque com citação e leia os cards de Q&A destilados.
  `curl https://agents.catcher.one/skills/knowledge/SKILL.md`
- **Memória** — O agente aprende com o uso: insights L3 do dia, memórias L4 curadas, memória de conversa verbatim e o ciclo dream (consolidação), tudo operável por API.
  `curl https://agents.catcher.one/skills/memory/SKILL.md`
- **Ferramentas e skills** — Dê ações ao agente: catálogo de ferramentas, modelos, ferramentas REST próprias e skills reutilizáveis.
  `curl https://agents.catcher.one/skills/tools/SKILL.md`
- **Uso, custo e tokens** — Meça e controle: uso agregado por período, budget mensal e a emissão de credenciais (JWT, API key, runtime token).
  `curl https://agents.catcher.one/skills/usage/SKILL.md`
- **Projetos, tenants e mídia** — A conta em volta do agente: projetos, tenants com schema dedicado, saúde dos provedores e upload de mídia.
  `curl https://agents.catcher.one/skills/account/SKILL.md`

## Autenticação, convenções e erros (referência)

A API aceita **3 credenciais**: `X-API-Key: ctc_…` (servidor-a-servidor, conta), `Authorization: Bearer <jwt>` (Console) e `X-Agent-Token: prt_…` (embed, preso a um agente). Todo erro é um envelope `{ error_code, message, trace_id }`. Base URL da API: `https://agents-api.catcher.one`.

Leia a referência completa em: https://agents.catcher.one/docs/autenticacao · https://agents.catcher.one/docs/convencoes · https://agents.catcher.one/docs/codigos-de-erro — ou o manual inteiro em https://agents.catcher.one/llms-full.txt

Contexto completo (manual inteiro): `curl https://agents.catcher.one/llms-full.txt` · índice: `curl https://agents.catcher.one/llms.txt`