AI Agents
How composable AI agents work in VirtuousAI — delegation, specialization, and autonomy
AI Agents
VirtuousAI's agent system lets you define specialized AI workers that can reason, use tools, and delegate to each other. Agents turn natural language instructions into repeatable, auditable operations.
Why Agents?
A single all-purpose AI struggles with specialized domains. A data analyst needs different skills than a web researcher, and both need different skills than a report builder. Agents solve this with composable specialization:
| Approach | Limitation |
|---|---|
| One general AI | Shallow expertise, inconsistent results across domains |
| Composable agents | Deep expertise per domain, delegation for cross-cutting tasks |
Each agent gets:
- Scoped tools — Only the tools relevant to its domain
- Focused instructions — Natural language guidance tuned for its specialty
- Defined boundaries — Explicit permissions and cost limits
Primary vs. Subagent
Agents operate in one of two modes:
Primary agents are user-facing entry points. They appear in the agent picker, handle user messages directly, and can delegate to other agents.
Subagents are domain specialists. They don't appear in the picker — they only execute when called by a primary agent via call_agent. Subagents cannot delegate further, which prevents infinite loops.
How Agents Compose
Agents form a directed graph of capabilities. A primary agent can call any agent listed in its sub_agents field, and those agents execute with their own tools and instructions.
Composition Rules
| Rule | Why |
|---|---|
Agents can only call agents in their sub_agents list | Prevents uncontrolled delegation |
Subagents cannot use call_agent | Prevents infinite recursion |
| Maximum delegation depth is enforced | Safety net for deep chains |
| An agent cannot call itself | Prevents self-referential loops |
Agents are defined as markdown documents with YAML frontmatter. This makes them version-controllable, reviewable, and easy to iterate on.
Agent Execution
When an agent executes, it follows a structured pipeline:
- Instructions loaded — Agent spec's markdown body parsed as system prompt
- Tools resolved — Only tools listed in the spec's
toolsfield are available - Context injected — User, org, temporal context provided
- Execution streamed — Each tool call is a step, streamed via SSE
- Approval gates — Write operations pause for human approval
- DAG built — Every step is recorded for potential crystallization
Each execution creates an AgentRun with full audit trail — what tools were called, what parameters were used, and what results were returned.
From Chat to Automation
The most powerful aspect of agents is the bridge between ad-hoc AI work and deterministic automation:
- Chat — User asks an agent to do something
- Agent executes — Tools run, results returned
- Crystallize — If the run was successful, convert it to an automation
- Replay — The automation runs the same steps without AI involvement
This is called crystallization. It captures the agent's execution DAG as a reusable workflow.