Agent

Um Agent é uma configuração de LLM: um modelo, uma mensagem de sistema e um repositório de skills. Agents são associados a inboxes (via Inbox.agent_id); quando um e-mail é aprovado, o agente da inbox é executado contra ele.

Propósito

• Centralizar modelo + prompt + tooling que processa uma classe de e-mails.
• Desacoplar roteamento de inbox da lógica de processamento — várias inboxes podem compartilhar um agente.
• Rastrear toda execução como um AgentRun para observabilidade, contabilidade de custo e replay.

Schema

Campo	Tipo	Descrição
id	UUID	ID interno.
external_id	UUID	ID estável do sistema de origem. Unique.
workspace_id	UUID	Workspace dono.
label	string	Label humano.
llm_model	string	ID de modelo do Vercel AI Gateway (ex.: anthropic/claude-sonnet-4-6, openai/gpt-4o).
system_message	string	O system prompt. Texto plano, pode incluir tokens de template.
skills_repo	string	URL Git do repositório de skills (diretório de arquivos .md descrevendo tools/operações).
created_at / updated_at / deleted_at	datetime

Exemplo

{
  "id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
  "external_id": "00000000-0000-0000-0000-00000000002b",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "label": "Extrator de Faturas",
  "llm_model": "anthropic/claude-sonnet-4-6",
  "system_message": "Você é um agente de extração de faturas...",
  "skills_repo": "https://github.com/universokobana/skills-invoices.git",
  "created_at": "2026-01-04T12:00:00.000Z",
  "updated_at": "2026-04-12T15:30:00.000Z",
  "deleted_at": null
}

Repositório de skills

A URL skills_repo aponta para um repositório Git contendo arquivos .md. Cada arquivo documenta uma skill chamável — uma tool que o LLM pode invocar (chamada HTTP, API interna, etc.). O repositório é clonado no início de cada AgentRun (cacheado por 5 minutos). Definições de skill não são autoradas pela API; são gerenciadas via source control.

Contabilidade de custo

Cada AgentRun registra contagens de tokens e custo derivado em USD. Custos são somados em Workspace.monthly_cost_used; se o workspace tiver monthly_cost_limit, runs são rejeitados com failed ao atingir o limite.

Ciclo de vida

• POST /agents — cria.
• PATCH /agents/{id} — atualiza label, model, system message, skills repo. Mutações entram em vigor na próxima execução — runs em andamento não são interrompidos.
• DELETE /agents/{id} — soft-delete. Inboxes que ainda referenciam o agente vão rejeitar e-mails com failed até serem rebinded.