Primitives Overview
Understanding the core building blocks of VirtuousAI
Primitives Overview
VirtuousAI is built around four 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 |
| Automations | DAG orchestration of actions | Actions, Connections |
| Events | Immutable audit log | All primitives emit events |
The Four 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. 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
5. 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.
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.