AgentRun

Un AgentRun es una ejecución de un Agent contra un Email. Los AgentRuns son de solo anexado (append-only): escritos por el worker, de solo lectura vía la API.

Propósito

• Proveer un rastro de auditoría por ejecución (modelo, tokens, costo, duración).
• Permitir depurar fallos sin volver a ejecutar.
• Agregar el costo de vuelta a los contadores mensuales del workspace.

Schema

Campo	Tipo	Descripción
id	UUID	ID interno.
workspace_id	UUID	Workspace propietario.
inbox_id	UUID	Inbox que produjo el correo.
agent_id	UUID	Agente que se ejecutó.
email_id	UUID	Correo objetivo.
llm_model	string	ID de modelo resuelto en el momento de la ejecución (congelado — Agent.llm_model puede haber cambiado desde entonces).
status	enum	running, success, failed.
error	string | null	Stack trace / mensaje cuando status=failed.
input_tokens	int	Tokens de prompt (system + user).
output_tokens	int	Tokens de completion.
cache_read	int	Tokens servidos desde el prompt cache.
cache_write	int	Tokens escritos en el prompt cache.
cost_per_token	decimal	USD/token combinado en el momento de la ejecución.
total_cost	decimal	cost_per_token * (input + output), tras descuentos de cache.
duration_ms	int | null	Tiempo real de la llamada al LLM.
started_at	datetime | null	Establecido cuando la ejecución sale de la cola.
finished_at	datetime | null	Establecido en el estado terminal.
created_at / updated_at / deleted_at	datetime

Ejemplo

{
  "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
}

Lectura

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

Sin endpoints de escritura

Los AgentRuns son creados por el worker. Para volver a ejecutar un agente contra un correo, usa POST /v1/emails/{id}/reprocess; se producirá una nueva fila de AgentRun.