Skip to content
3 min read · 585 words

Agents Overview

An agent is a configured identity: a system prompt wrapped in a name, language, tone, and an explicit tool allow-list. Every other object in the platform — messages, runs, tasks, tool calls, documents, workflows — belongs to exactly one agent.

Anatomy of an agent

json
{
  "name": "Ops Assistant",              // identity: injected as "You are {name}"
  "type": "Email Ops",                  // functional label (drives the UI icon)
  "description": "Internal note",       // humans only — never reaches the LLM
  "system_prompt": "You are a precise operations assistant...",
  "language": "English",                // injected into every LLM call
  "tone": "Professional",               // injected into every LLM call
  "enabled_tools": "email_analyzer,task_creator,document_search,reply_generator"
}
FieldReaches the LLM?Where it acts
name✅chat + RAG prompts ("You are {name}")
system_prompt✅chat prompt core — see Prompts
language, tone✅chat + RAG prompts
type, description❌UI display / internal notes only
enabled_tools❌ (gates, not prompts)authorization checks — see Tools

The create form offers Email Ops, HR & Recruiting, Customer Support, and Data Analysis (each mapped to an icon in AgentCard), but the backend accepts any string — type never changes behavior.

What an agent owns

Rendering diagram…

All of it cascade-deletes with the agent (cascade="all, delete"), and the knowledge base is additionally isolated at query time by the Chroma agent_id filter — one agent can never search another's documents (ORM Models, Retrieval).

Lifecycle

PhaseHowNotes
CreatePOST /agents/ or the create-agent UIlive immediately — no deploy step
Operatechat, analyze, workflows, RAGevery action leaves telemetry (Observability)
ObserveGET /agents/{id}/dashboard, runs, tool-calls, tracesthe ops loop
Update❌ no PUT /agents/{id} existsrecreate to change config; the UI's Edit button is inert (Known Issues)
Delete⚠️ the only delete path is the broken stats endpointeffectively: no supported delete today

The missing update/delete endpoints are the most conspicuous CRUD gap — top of the Roadmap.

Agents vs. "agents" — a terminology note

Two related meanings coexist (see Glossary):

  1. Platform Agent — the database entity documented on this page.
  2. Workflow agents — the Analysis/Reply/Reviewer roles inside the email workflow. These are stages acting on behalf of a platform agent, not rows in the agents table. One platform agent running one workflow briefly animates three workflow agents.

Designing a good agent

  • Put behavior in system_prompt, not in hopes — it is the only free-text field the LLM sees. State role, scope, boundaries, and output expectations. The runtime wrapper already adds "answer clearly / don't invent facts" rules (Prompt Catalog).
  • Grant the minimum tool set — tools are capability grants; an email-triage agent needs email_analyzer (+ task_creator if it should file work), not document_search.
  • language/tone are enforced per call — they are appended to every prompt, so "French" + "Friendly" genuinely shapes output; don't duplicate them inside the system prompt.
PreviousEmail WorkflowNextTools