AgentRun

Um AgentRun é uma execução de um Agent sobre um Email. AgentRuns são append-only: escritos pelo worker, read-only via API.

Propósito

• Prover um audit trail por-execução (modelo, tokens, custo, duração).
• Permitir debug de falhas sem re-rodar.
• Agregar custo de volta para os contadores mensais do workspace.

Schema

Campo	Tipo	Descrição
id	UUID	ID interno.
workspace_id	UUID	Workspace dono.
inbox_id	UUID	Inbox que produziu o e-mail.
agent_id	UUID	Agent que rodou.
email_id	UUID	E-mail alvo.
llm_model	string	Modelo resolvido no momento da execução (congelado — Agent.llm_model pode ter mudado).
status	enum	running, success, failed.
error	string | null	Stack trace / mensagem quando status=failed.
input_tokens	int	Tokens de prompt (system + user).
output_tokens	int	Tokens de completion.
cache_read	int	Tokens servidos do prompt cache.
cache_write	int	Tokens escritos no prompt cache.
cost_per_token	decimal	USD/token blended no momento da execução.
total_cost	decimal	cost_per_token * (input + output), descontado cache.
duration_ms	int | null	Wall time da chamada LLM.
started_at	datetime | null	Setado quando o run sai da fila.
finished_at	datetime | null	Setado no estado terminal.
created_at / updated_at / deleted_at	datetime

Exemplo

{
  "id": "d5e6f7a8-9b0c-4d1e-2f3a-4b5c6d7e8f9a",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "inbox_id": "b3c4d5e6-7a89-4b0c-9d1e-2f3a4b5c6d7e",
  "agent_id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
  "email_id": "e5f6a7b8-9c0d-4e1f-2a3b-4c5d6e7f8a9b",
  "llm_model": "anthropic/claude-sonnet-4-6",
  "status": "success",
  "error": null,
  "input_tokens": 1842,
  "output_tokens": 312,
  "cache_read": 1200,
  "cache_write": 642,
  "cost_per_token": "0.00000400",
  "total_cost": "0.00328400",
  "duration_ms": 4127,
  "started_at": "2026-05-17T10:00:14.700Z",
  "finished_at": "2026-05-17T10:00:18.827Z",
  "created_at": "2026-05-17T10:00:14.500Z",
  "updated_at": "2026-05-17T10:00:18.827Z",
  "deleted_at": null
}

Leitura

Método	Path
GET	/agent-runs?agent_id=…&email_id=…
GET	/agent-runs/{id}

Filtros: agent_id, inbox_id, email_id, status, created_at[gte|lt].

Sem endpoints de escrita

AgentRuns são criados pelo worker. Para reexecutar um agente sobre um e-mail use POST /v1/emails/{id}/reprocess; uma nova linha de AgentRun será produzida.