Agent

An Agent is an LLM configuration: a model, a system message and a skills repository. Agents are bound to inboxes (via Inbox.agent_id); when an email is approved, its inbox's agent is executed against it.

Purpose

• Centralise the model + prompt + tooling that processes a class of emails.
• Decouple inbox routing from processing logic — multiple inboxes can share one agent.
• Track every execution as an AgentRun for observability, cost accounting and replay.

Schema

Field	Type	Description
id	UUID	Internal id.
external_id	UUID	Stable id from the source system. Unique.
workspace_id	UUID	Owning workspace.
label	string	Human label.
llm_model	string	Vercel AI Gateway model id (e.g. anthropic/claude-sonnet-4-6, openai/gpt-4o).
system_message	string	The system prompt. Plaintext, may include templating tokens.
skills_repo	string	Git URL of the skills repository (a directory of .md files describing tools/operations).
created_at / updated_at / deleted_at	datetime

Example

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

Skills repository

The skills_repo URL points to a Git repository containing .md files. Each file documents a callable skill — a tool the LLM can invoke (HTTP call, internal API, etc.). The repository is cloned at the start of each AgentRun (cached for 5 minutes). Skill definitions are not authored through the API; they are managed in source control.

Cost accounting

Every AgentRun records token counts and a derived USD cost. Costs are summed against Workspace.monthly_cost_used; if the workspace has a monthly_cost_limit, runs are rejected with failed once the limit is reached.

Lifecycle

• POST /agents — create.
• PATCH /agents/{id} — update label, model, system message, skills repo. Mutations take effect on the next run — in-flight runs are not interrupted.
• DELETE /agents/{id} — soft-delete. Inboxes that still reference the agent will reject incoming emails with failed until rebound.