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 },
"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).