Agent

Un Agent es una configuración de LLM: un modelo, un mensaje de sistema y un repositorio de skills. Los agents se asocian a inboxes (vía Inbox.agent_id); cuando un correo es aprobado, se ejecuta el agente de su inbox contra él.

Propósito

• Centralizar el modelo + prompt + tooling que procesa una clase de correos.
• Desacoplar el enrutamiento de inbox de la lógica de procesamiento — varios inboxes pueden compartir un agente.
• Rastrear cada ejecución como un AgentRun para observabilidad, contabilidad de costos y replay.

Schema

Campo	Tipo	Descripción
id	UUID	ID interno.
external_id	UUID	ID estable del sistema de origen. Único.
workspace_id	UUID	Workspace propietario.
label	string	Etiqueta legible.
llm_model	string	ID de modelo de Vercel AI Gateway (p. ej. anthropic/claude-sonnet-4-6, openai/gpt-4o).
system_message	string	El system prompt. Texto plano, puede incluir tokens de templating.
skills_repo	string	URL Git del repositorio de skills (un directorio de archivos .md que describen tools/operaciones).
created_at / updated_at / deleted_at	datetime

Ejemplo

{
  "id": "c4d5e6f7-8a9b-4c0d-9e1f-2a3b4c5d6e7f",
  "external_id": "00000000-0000-0000-0000-00000000002b",
  "workspace_id": "a8b2c1d4-9e7f-4a3b-8c5d-1f2e3a4b5c6d",
  "label": "Invoice Extractor",
  "llm_model": "anthropic/claude-sonnet-4-6",
  "system_message": "You are an invoice extraction agent...",
  "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
}

Repositorio de skills

La URL skills_repo apunta a un repositorio Git que contiene archivos .md. Cada archivo documenta una skill invocable — una herramienta que el LLM puede invocar (llamada HTTP, API interna, etc.). El repositorio se clona al inicio de cada AgentRun (cacheado por 5 minutos). Las definiciones de skills no se autorean a través de la API; se gestionan en el control de versiones.

Contabilidad de costos

Cada AgentRun registra conteos de tokens y un costo derivado en USD. Los costos se suman a Workspace.monthly_cost_used; si el workspace tiene un monthly_cost_limit, las ejecuciones se rechazan con failed una vez alcanzado el límite.

Ciclo de vida

• POST /agents — crea.
• PATCH /agents/{id} — actualiza label, model, system message, skills repo. Las mutaciones surten efecto en la siguiente ejecución — las ejecuciones en curso no se interrumpen.
• DELETE /agents/{id} — soft-delete. Los inboxes que aún referencian al agente rechazarán los correos entrantes con failed hasta que se reasocien.