Automations

Declare automations in agent.md. Each automation has one trigger and may target the agent, a Skill, a subagent, or a playbook.

Scheduled work

timezone: America/Chicago
automations:
  morning-brief:
    schedule: daily at 08:00
    message: Prepare the morning brief.
    skill: morning-brief
    idempotency: starter-agent:morning-brief

The compiler accepts the documented plain-language schedule forms, validates them, and writes cron plus timezone into the manifest. Cron remains available for schedules that the plain-language grammar cannot express:

automations:
  monthly-review:
    schedule:
      cron: "0 9 1 * *"
      timezone: America/Chicago

The runtime never parses schedule prose. It reserves a durable idempotency key before dispatch and records one run for each occurrence. If the automation has no explicit route, it uses the latest valid route for the default channel selected by channels:.

Automations declared in a nested subagents/<name>/agent.md are compiled into the same durable scheduler with a surface-qualified name and idempotency key. When one fires, the runtime executes that child's model, instructions, capabilities, lifecycle contribution, hooks, and surface-scoped outbound route.

Plugin events

A connection plugin authenticates its webhook or listener and emits a normalized event. An automation decides whether that event starts a run:

capabilities:
  - mirror

automations:
  review-training:
    trigger: mirror.source.changed
    connection: mirror
    filter:
      provider: strava
    skill: daily-performance-review
    delivery: silent

Filters use recursive JSON-subset matching. Every filter key must have the same value in the event payload; the payload may contain extra keys. An unmatched event starts no run and retains no payload.

Lifecycle code

Preparation and finalization code belongs to a local or published plugin. The automation names that contribution:

automations:
  review-training:
    trigger: mirror.source.changed
    lifecycle: coachgpt.training-review

export default {
  lifecycle: {
    "training-review": {
      definition: "./ai.assemblyline/training-review.ts",
      phases: ["prepare", "finalize"]
    }
  }
};

Lifecycle code receives the existing durable context: trigger identity, principal, memory, resources, blob storage, environment access, routine-run bookkeeping, events, idempotency keys, and replayable steps. It does not become a model-callable tool.

Runtime-created automations

Set the authoring ceiling in agent.md:

mutability:
  automations: approval

Use autonomous when the agent may create schedules without approval, or disabled to turn the capability off. Runtime-created automations remain durable overlays under the stable agent ID. The compiler does not rewrite agent.md.

Omitted mapping keys keep the baseline independently. Skills remain autonomous and external connections remain disabled. See Mutability.

Delivery and reliability

• Provider event IDs and schedule occurrence IDs are reserved durably.
• Capacity is checked before an event consumes its idempotency key.
• External delivery is at least once. Use application-level idempotency for side effects.
• [SILENT] output completes without delivery. A leading [SEND] marker is removed before delivery.
• Channels own conversational ingress. Automations own operational ingress.

Related docs

• MD-First Agents
• Declarative Reference: Automations
• Plugins
• Runtime and deployment