Automations

Overview

An automation is a job that belongs to your project, not to any one agent. It can run on a schedule (every morning at 8) or on an event (every time a thread is created), and it can call workflows, scripts, or other automations to do the actual work.

Reach for one when:

• the work needs to happen for the whole project, not for one agent identity
• you want to react to an event in a single, reviewable place rather than scattering routines across agents
• the job has a clock attached: daily digests, hourly retries, weekly backfills
• you want to coordinate across agents, users, teams, or data sources

Manage them from the CLI or ArchAgents 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 ArchAgents Portal. The most useful categories are:

Thread events

Event	Description
thread.created	A new thread was created
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

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, ArchAgents 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

archagent list automationruns --automation aut_abc123
archagent list automationruns --automation aut_abc123 --status failed
archagent 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 capable 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 UTC. All schedules run in UTC, convert from your local timezone before writing the cron expression).
• 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.

Chain routines (multi-step, linear)

When a single handler isn't enough and a full workflow graph is overkill, use handler_type: chain: a linear sequence of preset / script / workflow_graph steps, each one's output addressable by name by the next. Steps share an input envelope so downstream steps can read upstream outputs:

routines:
 - name: classify-then-notify
 handler_type: chain
 event_type: agentroutine.invoked
 steps:
 - name: classify
 handler_type: preset
 preset_name: do_task
 preset_config:
 instructions: "Classify the inbound message."
 - name: log
 handler_type: script
 script: |
 println($.inputs.classify.output)
 $.inputs.classify.output

Scripts and workflows inside chain steps receive a wrapped input shape: {trigger: <event>, inputs: {<step_name>: <output>,...}}. They address the trigger event via $.trigger.<field> and upstream outputs via $.inputs.<step_name>, not $.<field> directly. Single-handler script routines are unaffected. See Scripts → Chain-step input shape for details.

---

CLI commands

# List automations
archagent list automations
archagent list automations --type trigger

# Create from a workflow config
archagent create automation -n "Nightly Report" -t scheduled --schedule "0 0 * * *" --config-id cfg_abc123

# Create from an AutomationTemplate
archagent create automation -n "Customer Digest" --template tmpl_digest

# Run scheduled work as a specific user
archagent create automation -n "Account Cleanup" -t scheduled --schedule "0 4 * * *" \
 --config-id cfg_cleanup --run-as-user usr_abc123

# Manage state
archagent activate automation aut_abc123
archagent pause automation aut_abc123

# Update
archagent update automation aut_abc123 -n "Updated Name" --config-id cfg_def456

# Delete
archagent delete automation aut_abc123

# View runs
archagent list automationruns --automation aut_abc123
archagent describe automationrun atr_abc123

Templates

--template <id> creates the automation from an AutomationTemplate config: a reusable definition you can deploy across projects or environments. Templates are managed like other configs (archagent describe configsamples automation_template, archagent deploy configs). Use templates when you have an automation pattern you want to reproduce in more than one place.

Run as

By default, scheduled automations run with platform-level access scoped to the project. Pass --run-as-user <id> to bind the schedule to a specific user: every run uses that user's identity, which controls what knowledge sources, integrations, and team memberships the work can reach.

This is useful when:

• the daily report should only see what one operator can see
• the cleanup job should only touch resources owned by a specific team member
• the audit trail should attribute the activity to a real user

Use it deliberately: a scheduled run keeps working long after you set it up, so the user identity should be one that will keep the access it needs.

---

Design patterns

Event-driven onboarding

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

archagent 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:

archagent 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:

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