Automations

Overview

Automations handle work that should happen for a whole project, not just for one agent.

Use them when you want to:

• run a daily or hourly job
• react to important events in one place
• keep cross-cutting workflows out of individual agents
• coordinate work across agents, users, teams, or data sources

Automations are the background jobs of your ArchAstro project.

Use them when the work belongs to the project as a whole, not to one specific agent identity.

Manage them through the CLI and developer portal.

---

A concrete example

Imagine you want a daily activity summary for the whole project.

That job does not belong to one support agent or one delivery agent. It belongs to the project itself.

An automation can:

1. run every morning
2. gather the activity data you care about
3. call a workflow that formats the summary
4. send the result to the right thread or destination

The main distinction:

• routines shape one agent's behavior
• automations run shared project-wide work

---

Automation types

Trigger automations

Trigger automations run when a matching event happens.

Examples:

• someone joins a thread
• a message is created
• a connector is linked
• an incoming email arrives

These are useful when you want one shared reaction to an event without tying that reaction to a single agent.

Scheduled automations

Scheduled automations run on a timetable you define.

Examples:

• send a daily summary every morning
• run a cleanup job every night
• check for stuck work every hour

These are useful when you want a heartbeat, cleanup, report, audit, or periodic sync.

---

Available event types

Inspect the full event list from the CLI or developer portal. The most useful categories are:

Thread events

Event	Description
thread.created	A new thread was created
message.created	A message was added to a thread
thread.member_joined	A member joined a thread
thread.member_left	A member left a thread

Connector events

Event	Description
connector.connected	An OAuth connector was connected

Context events

Event	Description
context.ingestion.succeeded	A context ingestion job completed
context.ingestion.failed	A context ingestion job failed

Email events

Event	Description
email.received	An inbound email was received
email.processed	An email was processed

---

Status states

Automations move through three simple states:

Status	Behavior
draft	Saved, but not running yet
running	Active and ready to react
paused	Temporarily stopped

That lifecycle is intentionally simple. You only need to know whether an automation is ready, active, or temporarily stopped.

---

Automation runs

Each time an automation runs, ArchAstro records what happened so you can review it later.

That run history is what makes automations operationally usable. When background work misbehaves, you need to see what ran and why instead of treating it like invisible magic.

Run statuses

Status	Meaning
pending	Queued, awaiting execution
running	Work is in progress
completed	Finished successfully
failed	The run ended with an error
cancelled	The run was cancelled

Viewing runs

archastro list automationruns --automation aut_abc123
archastro list automationruns --automation aut_abc123 --status failed
archastro describe automationrun atr_abc123

Automations vs. routines

Both automations and routines react to events, but they solve different problems:

	Automations	Routines
Scope	Whole project	One agent
Best for	Shared jobs and scheduled work	Agent behavior
Typical example	Daily digest or event pipeline	Replying to new messages

Use automations for shared background work. Use routines for how a specific agent behaves.

Another quick way to choose:

• if the work belongs to one named agent, start with a routine
• if the work belongs to the project, start with an automation

---

Agent routines with LLM execution (do_task)

The do_task preset is the most powerful routine type. It triggers a full LLM execution session where the agent can think and act using all of its configured tools.

Use it when you want an agent to reason about a task on a schedule or in response to an event — not just run a deterministic script.

Example: weekly report routine

routines:
  - name: weekly-report
    description: Generate weekly activity summary
    handler_type: preset
    preset_name: do_task
    preset_config:
      instructions: |
        Review all activity from the past week.
        Summarize key findings and send a Slack message to #reports.
    schedule: "0 9 * * 1"
    event_type: schedule.cron
    status: active

Key fields

• preset_name: do_task — tells the platform to run a full agent session with LLM reasoning.
• preset_config.instructions — the task the agent should perform. Write this like you would write a prompt.
• schedule — a cron expression for when to run (e.g. "0 9 * * 1" means every Monday at 9 AM).
• The agent gets access to all its configured tools during execution — search, knowledge, integrations, memory, and anything else you have wired up.

do_task vs. script routines

Script routines run deterministic code. They always do the same thing the same way.

do_task routines run the LLM with full tool access. The agent reasons about the instructions, decides what tools to call, and adapts to whatever it finds. Use do_task when the work requires judgment, not just execution.

---

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 state
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

---

Design patterns

Event-driven onboarding

Trigger shared onboarding work when a new user joins a thread:

archastro create automation -n "Onboarding Flow" \
  -t trigger \
  --trigger thread.member_joined \
  --config-id cfg_onboarding_workflow

Scheduled reporting

Run a daily job that gathers activity and posts a summary:

archastro create automation -n "Daily Activity Report" \
  -t scheduled \
  --schedule "0 9 * * *" \
  --config-id cfg_daily_activity

Context ingestion monitoring

React to ingestion failures so a team can retry or investigate:

archastro create automation -n "Ingestion Failure Alert" \
  -t trigger \
  --trigger context.ingestion.failed \
  --config-id cfg_ingestion_alert