Início rápido

Início rápido#

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

GET1. 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).

POST2. 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.

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:

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

POST3. Mande a mensagem#

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:

{
  "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, "cached_tokens": 640 },
  "provider": "engine",
  "model": "gpt-5.6-luna",
  "tool_calls": [ { "name": "brain_search", "is_error": false, "…": "…" } ]
}

usage.cached_tokens é a fatia de input_tokens que o provider serviu do próprio cache de prompt. Entrada cacheada custa uma fração do preço cheio, então esse é o campo que responde "quanto do meu input saiu barato?". Ele é aditivo: input_tokens continua sendo o total de entrada (a parte cacheada inclusa), e cached_tokens vem sempre presente — 0 quando o provider não reportou cache (prefixo frio ou provider sem cache), nunca ausente.

Mudança em 2026-08-12, se você integra com codex/* ou gpt-5.6-*: nesse caminho o campo respondia 0 em todo run, inclusive nos de centenas de milhares de tokens com prefixo idêntico. Aquilo não era "sem cache" — era o campo não sendo lido. Corrigido: agora traz o valor real. Se você escreveu lógica assumindo que esses modelos sempre devolvem 0, ela precisa mudar.

Atualização em 2026-08-26 — o aproveitamento em codex/* subiu. A nota acima dizia que essa rota aproveitava pouco (~5%). Isso descrevia um defeito nosso, não o provider: cada chamada ia com um identificador de sessão novo, e é por ele que aquele backend roteia o cache — então cada rodada caía num nó diferente e repagava um prefixo que não tinha mudado um byte. Medido ao vivo em três conversas de 6 rodadas por configuração: 29,3% antes, 71,6% depois, com o cache aquecendo na rodada 2 em vez da 4ª–5ª. Nada muda no contrato — cached_tokens tem o mesmo nome, o mesmo lugar e a mesma semântica; ele só passa a vir maior. Se você dimensionou custo assumindo ~5% nessa rota, redimensione.

O cache do provider é por prefixo exato: ele só acerta enquanto o começo do payload (system prompt + ferramentas + histórico) chegar byte a byte igual ao da chamada anterior. Reaproveitar a mesma sessão ajuda; mudar o começo do prompt a cada chamada zera o cache do payload inteiro.

Duas consequências práticas para quem tem system prompt grande e turnos longos:

• input_tokens é bruto, com a parte cacheada inclusa. Ele não cai quando o cache acerta — quem cai é o custo. Um turno de N rodadas soma a entrada de todas elas, então input_tokens cresce de forma quadrática com o número de rodadas mesmo com 90% de cache. Para saber o que saiu barato, olhe cached_tokens, nunca a variação de input_tokens.
• Encolher o system prompt costuma ser a otimização errada. O system prompt é a parte mais estável do payload, logo a que mais cacheia; o que não cacheia é o histórico que cresce a cada rodada (resultados de ferramenta, sobretudo). Antes de cortar capacidade do agente, compare cached_tokens com input_tokens rodada a rodada — o endpoint de trace (GET /v1/agents/{id}/runs/{runId}/trace) traz os dois por rodada.

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