# 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 · Comece grátis em https://agents-app.catcher.one/register.

## Comece por aqui (agentes de IA)
- [Super skill](https://agents.catcher.one/skill/SKILL.md): o mapa do pacote — quickstart em 3 chamadas, referências por grupo de endpoints e scripts de conta/validação/smoke.
- [Manual completo](https://agents.catcher.one/llms-full.txt): toda a API num arquivo só (contexto completo em 1 fetch).

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

## Scripts utilitários (/skill/scripts/)
- [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).
- [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.
- [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.
- [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.
- [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.

## Skills por capacidade
- [Embutir um agente](https://agents.catcher.one/skills/embed/SKILL.md): Rode um agente Catcher no seu app em 3 chamadas: token de runtime (prt_) → sessão → mensagem, com streaming por SSE token a token.
- [Agentes e conversas](https://agents.catcher.one/skills/agents/SKILL.md): Gerencie agentes (CRUD, clone, stats) e conduza conversas: sessões, mensagens, runs e exportação.
- [Conhecimento (RAG)](https://agents.catcher.one/skills/knowledge/SKILL.md): Dê conhecimento próprio ao agente: adicione texto/arquivos, busque com citação e leia os cards de Q&A destilados.
- [Memória](https://agents.catcher.one/skills/memory/SKILL.md): 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.
- [Ferramentas e skills](https://agents.catcher.one/skills/tools/SKILL.md): Dê ações ao agente: catálogo de ferramentas, modelos, ferramentas REST próprias e skills reutilizáveis.
- [Uso, custo e tokens](https://agents.catcher.one/skills/usage/SKILL.md): Meça e controle: uso agregado por período, budget mensal e a emissão de credenciais (JWT, API key, runtime token).
- [Projetos, tenants e mídia](https://agents.catcher.one/skills/account/SKILL.md): A conta em volta do agente: projetos, tenants com schema dedicado, saúde dos provedores e upload de mídia.

## Documentação
- [Autenticação](https://agents.catcher.one/docs/autenticacao): A API aceita três credenciais, cada uma para um caso.
- [Início rápido](https://agents.catcher.one/docs/inicio-rapido): Do zero ao primeiro turno, embutindo o agente no seu app, em três passos.
- [Runtime — embutir um agente](https://agents.catcher.one/docs/runtime-embutir-um-agente): O grupo /v1/agent-runtime/{id} é a superfície de embed.
- [Streaming (SSE)](https://agents.catcher.one/docs/streaming-sse): O endpoint .../messages/stream responde com Content-Type: text/event-stream (Cache-Control: no-cache, X-Accel-Buffering: no), status 200 imediato.
- [Agentes](https://agents.catcher.one/docs/agentes): O grupo /v1/agents cobre o ciclo de vida do agente.
- [Sessões e mensagens](https://agents.catcher.one/docs/sessoes-e-mensagens): O chat pelo Console (autenticado por JWT/API key) usa os mesmos handlers do runtime, com endpoints extras de gestão de sessão.
- [Conhecimento](https://agents.catcher.one/docs/conhecimento): O RAG por agente: suba documentos e a busca híbrida entra automaticamente no turno.
- [Memória](https://agents.catcher.one/docs/memoria): O agente aprende com o uso — separado do conhecimento que você semeia.
- [Ferramentas e skills](https://agents.catcher.one/docs/ferramentas-e-skills): GET /v1/agent-tools — as ferramentas selecionáveis (embutidas ∪ custom): { tools: [ { name, label, description } ] }.
- [Document AI](https://agents.catcher.one/docs/document-ai): Document AI transforma PDF/JPEG/PNG/WebP privados em dados estruturados.
- [Uso e custo](https://agents.catcher.one/docs/uso-e-custo): Cada turno vira um registro Run com custo real em dólar.
- [Tokens de acesso](https://agents.catcher.one/docs/tokens-de-acesso): POST /v1/auth/login — corpo { email, password }.
- [Projetos e tenants](https://agents.catcher.one/docs/projetos-e-tenants): A hierarquia é Conta → Projeto → Tenant.
- [Provedores e mídia](https://agents.catcher.one/docs/provedores-e-midia): GET /v1/providers/health?hours=168 — resposta 200:
- [Geração de imagens](https://agents.catcher.one/docs/geracao-de-imagens): Intermediador multi-modelo de geração de imagens.
- [Convenções](https://agents.catcher.one/docs/convencoes): Todo 4xx/5xx usa o mesmo envelope, com um trace_id que casa com o header X-Trace-ID e a linha de log correspondente:
- [Códigos de erro](https://agents.catcher.one/docs/codigos-de-erro): Quando um handler não define um código explícito, o status mapeia para um fallback (400→BAD_REQUEST, 401→UNAUTHORIZED, 403→FORBIDDEN, 404→NOT_FOUND, 409→CONFLICT, 422→UNPROCESSABLE_ENTITY, 429→RATE_LIMITED, 501→NOT_IMPLEMENTED, 503→SERVICE_UNAVAILABLE, ≥500→INTERNAL_ERROR).