Primitives Overview
Understanding the core building blocks of VirtuousAI
Primitives Overview
VirtuousAI is built around core primitives that work together to enable powerful automation workflows. This page provides an overview of how these primitives interact.
How Primitives Relate
| Primitive | Role | Depends On |
|---|---|---|
| Templates | Blueprints for actions and connections | None (global) |
| Connections | Encrypted credentials for external services | Templates |
| Actions | Atomic units of work | Templates, Connections |
| Artifacts | Outputs from action runs | Actions |
| Agents | AI workers with tools and delegation | Actions, Connections |
| Automations | DAG orchestration of actions | Actions, Connections |
| Flashboards | Persistent data dashboards | Datasets (queries) |
| Events | Immutable audit log | All primitives emit events |
The Primitives
1. Templates
Templates are global, immutable blueprints that define how to configure actions or connections. They provide structure, validation, and documentation.
Key concepts:
- Immutable after publish (versioned)
- Snapshot stored when used (audit trail)
- Define input schemas with validation
- Include documentation and defaults
2. Connections
Connections are tenant-scoped credential stores for external services. They abstract away authentication complexity and enable secure access to third-party APIs.
Key concepts:
- Envelope encryption (DEK/KEK)
- OAuth token refresh handling
- Flexible resolution (by ID, slug, or provider)
- Default connection per service type
3. Actions
Actions are discrete units of work. Each ActionRun represents a single execution of business logic, from simple API calls to complex data extractions.
Key concepts:
- Two execution modes: SYNC (inline) and ASYNC_QUEUE (background workers)
- Lease-based ownership with watchdog recovery
- Input/output validation via Pydantic
- Approval workflows for sensitive operations
4. Artifacts
Artifacts are the outputs produced by action runs — JSON data, text content, or files stored in S3. They provide traceability for what each action produced.
Key concepts:
- Three kinds: JSON, TEXT, FILE
- Inline or S3 storage
- Linked to parent action run
- Immutable once created
5. Agents
Agents are first-class AI primitives defined as markdown documents. They encapsulate instructions, tool access, and composition rules into reusable specs that can be executed on demand or delegated to by other agents.
Key concepts:
- Defined as markdown with YAML frontmatter
- Two modes: primary (user-facing) and subagent (specialist)
- Composable delegation via
call_agent - SSE-streamed execution with approval gates
- Crystallization into deterministic automations
6. Automations
Automations orchestrate multiple actions as DAGs with triggers, conditions, and dependencies. They own all workflow logic.
Key concepts:
- Triggers (schedules, webhooks, events)
- DAG execution with dependencies
- Conditional logic and branching
- Error handling and retries
7. Flashboards
Flashboards are persistent, versioned dashboards that visualize your data through a composable UI component tree. They can be created from chat, built in Studio, or assembled via API.
Key concepts:
- UITree schema with 21+ component types
- Versioning (every edit creates an immutable version)
- Token-based public sharing
- AI-powered Studio build via SSE streaming
- Embedded data snapshots for offline rendering
8. Events
Events provide an immutable audit log of all system activity. Every action, automation run, and state change is recorded.
Key concepts:
- Immutable, append-only audit trail
- Event correlation for tracing
- Webhook subscriptions
- Compliance and debugging
How They Work Together
A typical workflow: An Automation triggers on a schedule, executes an Action (using a Template) that extracts data via a Connection, and every step is recorded as Events. For AI-driven workflows, an Agent orchestrates tool calls that can be crystallized into automations, and results can be visualized as Flashboards.
Example: Data Extraction Pipeline
| Step | Primitive | What Happens |
|---|---|---|
| 1 | Automation | Cron trigger fires at 6 AM |
| 2 | Action | ActionRun created for dlt_extract |
| 3 | Connection | Shopify credentials resolved and injected |
| 4 | Template | Action schema validated, snapshot stored |
| 5 | Events | automation.triggered, action.started, action.completed |
| 6 | Artifacts | Bronze parquet files written to S3 |
Next Steps
Dive deeper into each primitive:
Or jump directly to the OpenAPI Reference for detailed endpoint documentation.