The .Worker file

A .Worker file defines an agentic worker: an AI agent with a recurring job, the accounts it acts through, limits on what it may do, what starts each run, and a person who answers for its results.

The format is YAML. A file can describe three things, each as its own document:

• Worker: the definition. It contains no account ids and no machine settings, so the same worker can be deployed for many clients.
• Assignment: one deployment of a worker. It says whose accounts fill each connection, who approves risky actions, and the budget.
• Box: the machine that runs one or more assignments.

The smallest useful worker has an id, a job, the connections it needs, what it may do with them, and a trigger. Copy this into the viewer to see it checked.

apiVersion: agenticworkers.com/v1
kind: Worker
id: inbox-triage
name: Inbox Triage
 
job:
  summary: Label new support email and draft a reply for a person to approve.
  done_when: Every new email has a label and a draft reply.
 
connections:
  - id: mail
    provider: gmail
    via: composio
    auth: oauth
    required: true
    tools: { allow: [GMAIL_FETCH_EMAILS, GMAIL_ADD_LABEL_TO_EMAIL, GMAIL_CREATE_EMAIL_DRAFT] }
 
policy:
  default: deny
  rules:
    - allow: [mail.GMAIL_FETCH_EMAILS, mail.GMAIL_ADD_LABEL_TO_EMAIL]
    - require_approval: [mail.GMAIL_CREATE_EMAIL_DRAFT]
 
triggers:
  - id: every-15-minutes
    every: 15m
    run: { prompt: Triage new email since the last run. }
    deliver: chat

The worker can read and label email on its own, but a person approves every draft before it’s created. It can’t touch anything outside the mail connection, because policy.default is deny.

Name files with the .Worker extension. A file holds one or more YAML documents separated by a line containing only ---. Every document starts with the same three fields:

# One worker and the client deployment that uses it.
apiVersion: agenticworkers.com/v1
kind: Worker
id: inbox-triage
# ...
 
---
apiVersion: agenticworkers.com/v1
kind: Assignment
id: inbox-triage-acme
worker: ./inbox-triage.Worker
# ...

The definition of the worker. It describes what the worker needs and is allowed to do, never whose accounts it uses.

A worker that looks healthy but has no connected accounts fails on its first tool call. Connections are declared in two halves so that never happens silently:

• The Worker lists what it needs: a provider, how it signs in, which tools it may call, and whether it can run without it.
• The Assignment binds each need to a real account.

Skills, policy rules and triggers refer to a connection by its id, never by a vendor or an account.

connections:
  - id: crm                          # the name skills, policy and triggers use
    provider: hubspot                # Composio toolkit or MCP registry name
    via: composio
    auth: oauth
    scopes: [crm.objects.deals.read]
    tools: { allow: [HUBSPOT_LIST_DEALS, HUBSPOT_GET_DEAL] }
    required: true
    on_missing: block
    on_expired: pause_and_notify
 
  - id: github                       # a CLI credential
    via: env
    env: GH_TOKEN
    check: gh auth status            # readiness probe
    required: true

Binding accounts

In an Assignment, bind maps each connection id to an account. Every required connection must be bound, and only connections the worker declares may be.

bind:
  crm:
    owner: client
    invite: { email: ops@acme.com, expires: 7d }
  github:
    secret: vault://box/ACME_GH_TOKEN

Current limits, enforced by the linter:

• A worker’s Composio connections use either your team’s accounts (org) or its own (agent and client), not both.
• Each provider has one account per worker. Two Gmail accounts on one worker aren’t supported yet.
• An invite requires owner: client or owner: agent.

Policy is enforced; job.stop_and_ask is only advice to the model. default is allow or deny. Each rule has exactly one of allow, require_approval, forbid, require. Tools are written as connection.TOOL, and * matches any characters.

policy:
  default: deny
  rules:
    - allow: [crm.HUBSPOT_LIST_DEALS, crm.HUBSPOT_GET_DEAL]
    - require_approval: [crm.HUBSPOT_UPDATE_DEAL]
    - forbid: [mail.GMAIL_SEND_EMAIL]
    - require: { tools: [mailchimp.schedule], lead_time: ">= 12h" }

When rules overlap, forbid wins over require_approval, which wins over allow. Approvals go to the Assignment’s identity.sponsor. unattended: same applies the same rules to scheduled runs, where nobody is watching.

Each trigger has a stable id and exactly one of cron, every, event, webhook. run has exactly one of prompt, skill, script. deliver sends the result to chat, telegram, chat_and_telegram, none.

triggers:
  - id: monday-summary
    cron: "0 8 * * 1"
    run: { skill: crm-weekly-summary }
    deliver: chat
  - id: board-check
    every: 5m
    run: { script: ./probes/board.py }
  - id: deal-won
    event: { connection: crm, type: HUBSPOT_DEAL_STAGE_CHANGED }
    run: { prompt: Add this deal to the current summary draft. }

• cron takes five fields: minute, hour, day of month, month, day of week.
• every takes a number and a unit: 30s, 5m, 1h, 1d.
• event names a declared connection and an event type from that provider.
• A trigger can set its own model, for example a cheaper model for a frequent check.
• Schedules don’t run while the box is asleep. Check the Box’s sleep windows.

One deployment of a worker for one client or team. Use one Assignment per client, so each client has separate accounts, approvals, spend and backups.

apiVersion: agenticworkers.com/v1
kind: Assignment
id: weekly-pipeline-acme
worker: agenticworkers/weekly-pipeline:2.1.0
team: acme-client
box: provider-us-east
 
identity: { sponsor: ops@acme.com, billing: provider }
 
bind:
  crm: { owner: client, invite: { email: ops@acme.com, expires: 7d } }
 
secrets:
  HUBSPOT_PORTAL_ID: vault://box/ACME_HUBSPOT_PORTAL_ID
 
budget: { usd_per_day: 15, on_exceed: pause }
storage:
  backups: { cadence: daily, hour_utc: 3, keep: { count: 7, days: 30 } }

The machine that runs assignments. One Box can run several workers; each gets its own process, files and schedules.

apiVersion: agenticworkers.com/v1
kind: Box
id: provider-us-east
team: northwind-ai
image: agw/hermes:fcd5e2c
region: iad
machine: { cpus: 4, memory: 8Gi }
volume: { size: 40Gi }
availability: always-on
assignments:
  - ./acme.Worker
  - ./globex.Worker

Secret values never go in a .Worker file. Store them in your workspace vault and reference them as vault://box/NAME. That way a file can be committed, shared and reviewed safely.

• Names use uppercase letters, digits and underscores.
• Names can’t start with a reserved prefix: AGW_, HERMES_, COMPOSIO, GATEWAY_, API_SERVER_, BOX_GATEWAY.
• The linter flags values that look like tokens or keys, such as sk-…, ghp_…, Slack tokens, AWS keys and JWTs.

The formatter produces one canonical form, so diffs show real changes only. Format in the viewer with the Format button or Cmd+S.

• Two-space indentation, and one --- between documents.
• Top-level keys in a fixed order per kind. For a Worker: apiVersion, kind, id, name, version, from, hosted, scope, description, and so on.
• Every comment is kept. Trailing comments in a block are aligned to one column.
• Lines wrap at 100 characters. Formatting an already formatted file changes nothing.

The viewer runs these checks as you type. Errors must be fixed before a file can be applied. Warnings point at things that work today but are likely mistakes or not fully supported yet.

The agw command line tool is in development. These are the planned commands: