Automations
Run workflows on a schedule or in response to platform events — app-level automation without writing server code.
Overview
Automations execute a WorkflowGraph automatically, either on a cron schedule or when a platform event occurs. They are app-level constructs — unlike routines which are scoped to a specific agent, automations run at the app level and can orchestrate across agents, users, and teams.
Automations are managed through the developer portal, SDK, or CLI. Each automation links to a WorkflowGraph config that defines the logic to execute.
Automation types
Trigger automations
Trigger automations fire when a specific platform event occurs. The event payload is passed into the workflow as input.
const automation = await client.automations.create(appId, {
name: "Welcome New Members",
type: "trigger",
trigger: "thread.member_joined",
config_id: "cfg_welcome_workflow",
});
await client.automations.activate(appId, automation.id);
When thread.member_joined fires, the linked workflow receives:
{
"trigger": "thread.member_joined",
"payload": { /* event-specific data */ }
}
Scheduled automations
Scheduled automations fire on a cron schedule. The workflow receives the scheduled timestamp as input.
const automation = await client.automations.create(appId, {
name: "Daily Digest",
type: "scheduled",
schedule: "0 9 * * *", // 9am UTC daily
config_id: "cfg_digest_workflow",
run_as_user_id: "usr_abc123", // optional: execute as this user
});
await client.automations.activate(appId, automation.id);
The workflow receives:
{
"trigger": "workflow.scheduled",
"payload": { "scheduled_at": "2026-02-28T09:00:00Z" }
}
Available event types
Query the available events through the API or SDK:
const events = await client.automations.events(appId);
// Returns [{ name: "thread.created", description: "A new thread was created" }, ...]
Thread events
| Event | Description |
|---|---|
thread.created |
A new thread was created |
thread.deleted |
A thread was deleted |
thread.message_added |
A message was added to a thread |
thread.member_joined |
A member joined a thread |
thread.member_left |
A member left a thread |
| Conversation session started | An active conversation session started |
| Conversation session completed | An active conversation session completed |
| Conversation session ended | A conversation session ended |
Connector events
| Event | Description |
|---|---|
connector.connected |
An OAuth connector was connected |
Context events
| Event | Description |
|---|---|
context.ingestion.started |
A context ingestion job started |
context.ingestion.running |
A context ingestion job is running |
context.ingestion.succeeded |
A context ingestion job completed |
context.ingestion.failed |
A context ingestion job failed |
context.source.paused |
A context source was auto-paused after consecutive failures |
context.installation.suspended |
A context installation was suspended due to auth errors |
Credential events
| Event | Description |
|---|---|
credential.created |
A new credential was created |
credential.updated |
A credential was updated |
Email events
| Event | Description |
|---|---|
email.received |
An inbound email was received |
email.processed |
An email was processed |
Agent session events
| Event | Description |
|---|---|
agent_session.started |
An agent session started in a thread |
agent_session.stopped |
An agent session stopped |
agent_session.event_received |
An agent session received a chat event |
Status lifecycle
Automations have three statuses:
stateDiagram-v2
[*] --> draft
draft --> running : activate
running --> paused : pause
paused --> running : activate
paused --> draft : reset
draft --> [*] : delete
paused --> [*] : delete
running --> [*] : delete
| Status | Behavior |
|---|---|
draft |
Default. Automation exists but does not run. |
running |
Active. Trigger automations fire on matching events. Scheduled automations are enqueued for the next cron occurrence. |
paused |
Suspended. Trigger events are ignored. Scheduled jobs are cancelled. |
Activating requires a config_id pointing to a valid WorkflowGraph config. The workflow must contain a trigger node matching the automation's event.
Automation runs
Each execution creates an AutomationRun record that tracks status and results.
Run statuses
| Status | Meaning |
|---|---|
pending |
Queued, awaiting execution |
running |
Workflow is executing |
completed |
Finished successfully |
failed |
Execution failed (check result.error) |
cancelled |
Cancelled (e.g., automation paused or deleted) |
Viewing runs
// List runs for an automation
const runs = await client.automations.runs(appId, automation.id, {
status: "failed", // optional filter
limit: 20, // default 50, max 100
});
// Get a specific run
const run = await client.automations.run(appId, runId);
console.log(run.status); // "completed"
console.log(run.result); // { payload: {...}, output: [...] }
archastro list automationruns --automation aut_abc123
archastro list automationruns --automation aut_abc123 --status failed
archastro describe automationrun atr_abc123
Run results
On success, the result field contains:
{
"payload": { /* final workflow output value */ },
"output": ["line 1 from println", "line 2 from println"]
}
On failure:
{
"error": "Script execution timed out"
}
Automation properties
| Field | Type | Description |
|---|---|---|
id |
string | Automation ID (aut_ prefix) |
name |
string | Display name (required) |
description |
string | Optional description |
type |
enum | trigger or scheduled |
status |
enum | draft, running, or paused |
trigger |
string | Event name (required for trigger type) |
schedule |
string | Cron expression (required for scheduled type) |
config_id |
string | WorkflowGraph config to execute |
run_as_user_id |
string | Optional user identity for execution context |
lookup_key |
string | Optional unique slug per app |
metadata |
object | Arbitrary metadata |
Automations vs. routines
Both automations and routines react to events, but they serve different purposes:
| Automations | Routines | |
|---|---|---|
| Scope | App-level | Agent-level |
| ID prefix | aut_ |
arn_ |
| Handler types | WorkflowGraph only | WorkflowGraph, Script, or Preset |
| Managed by | Developer (portal, SDK, CLI) | Developer per-agent |
| Use case | App-wide orchestration, scheduled jobs | Agent behavior and personality |
| Status values | draft / running / paused |
draft / active / paused |
Use automations for cross-cutting concerns (daily reports, event-driven workflows, data pipelines). Use routines for agent-specific behavior (how an agent responds to messages, memory capture, participation patterns).
CLI commands
# List automations
archastro list automations
archastro list automations --type trigger
# Create
archastro create automation -n "Nightly Report" -t scheduled --schedule "0 0 * * *" --config-id cfg_abc123
# Manage lifecycle
archastro activate automation aut_abc123
archastro pause automation aut_abc123
# Update
archastro update automation aut_abc123 -n "Updated Name" --config-id cfg_def456
# Delete
archastro delete automation aut_abc123
# View runs
archastro list automationruns --automation aut_abc123
archastro describe automationrun atr_abc123
API reference
Automation management
| Operation | Endpoint | Description |
|---|---|---|
| List | GET /apps/:app_id/automations |
List automations (optional ?type= filter) |
| Create | POST /apps/:app_id/automations |
Create an automation |
| Show | GET /apps/:app_id/automations/:id |
Get automation details |
| Update | PATCH /apps/:app_id/automations/:id |
Update an automation |
| Delete | DELETE /apps/:app_id/automations/:id |
Delete an automation |
| Activate | POST /apps/:app_id/automations/:id/activate |
Set status to running |
| Pause | POST /apps/:app_id/automations/:id/pause |
Set status to paused |
| Events | GET /apps/:app_id/automations/events |
List available event types |
Automation runs
| Operation | Endpoint | Description |
|---|---|---|
| List | GET /apps/:app_id/automations/:id/runs |
List runs (optional ?status= filter, cursor pagination) |
| Show | GET /apps/:app_id/automations/runs/:run_id |
Get run details |
Design patterns
Event-driven onboarding
Trigger a workflow when a new user joins a thread to send a welcome message and configure agent behavior:
await client.automations.create(appId, {
name: "Onboarding Flow",
type: "trigger",
trigger: "thread.member_joined",
config_id: "cfg_onboarding_workflow",
});
Scheduled reporting
Run a daily workflow that aggregates activity and posts a summary to a team thread:
await client.automations.create(appId, {
name: "Daily Activity Report",
type: "scheduled",
schedule: "0 9 * * 1-5", // 9am UTC, weekdays
config_id: "cfg_daily_report",
run_as_user_id: "usr_reporter",
});
Context ingestion monitoring
React to context ingestion failures to alert the team or trigger a retry:
await client.automations.create(appId, {
name: "Ingestion Failure Alert",
type: "trigger",
trigger: "context.ingestion.failed",
config_id: "cfg_ingestion_alert",
});