Modes

Modes control how actions execute. Choose based on risk and frequency.

The three modes

Autonomous mode

The workflow executes all actions immediately without asking for approval.


{
  "defaultMode": "autonomous"
}

Behavior:

Read actions execute immediately
Write actions execute immediately
No approval requests sent
Fastest execution

Best for:

Well-tested, trusted workflows
Low-risk actions (labeling, archiving)
High-frequency triggers (incoming email)
Workflows that only report to you

Autonomous mode can affect many emails quickly. Use it for low-risk actions and well-tested workflows.

Approval-required mode (HITL)

The workflow proposes write actions but waits for your approval before executing.


{
  "defaultMode": "hitl"
}

Behavior:

Read actions execute immediately
Write actions create approval requests
You receive notifications with approve/reject links
Actions execute only after approval

Best for:

New or untested workflows
Workflows that send emails
High-stakes automations
Workflows with access to sensitive tools

Read-only mode

The workflow can only read and analyze — it cannot modify anything.


{
  "defaultMode": "read-only"
}

Behavior:

Read actions execute normally
Write actions are blocked entirely
Cannot label, archive, or send
Can still send reports to you via send_email_to_user

Even in read-only mode, send_email_to_user typically works since it’s sending to you, not modifying emails.

Best for:

Analytics and reporting workflows
Research workflows
Testing new configurations
Workflows that only gather information

Which actions require approval?

In approval-required mode, write actions require approval:

Action	Requires Approval?
Reading an email	No
Searching emails	No
Listing calendar events	No
Adding a label	Yes
Archiving an email	Yes
Sending an email	Yes
Creating a draft	Yes
Deleting/trashing	Yes

Per-tool mode override

You can set different modes for specific tools:


{
  "defaultMode": "autonomous",
  "tools": [
    { "toolId": "read_email" },
    { "toolId": "archive_email" },
    { "toolId": "send_email_to_user", "mode": "hitl" }
  ]
}

This workflow is autonomous for most actions, but sending emails still requires approval.

Mode selection guide

Situation	Recommended Mode
Brand new workflow	Approval-required or Read-only
Workflow sends emails	Approval-required (at least initially)
Simple labeling/archiving	Autonomous (if tested)
Research/analysis only	Read-only
Processing every incoming email	Autonomous (for speed)
Weekly summary workflow	Approval-required (review before sending)
Mission-critical automation	Approval-required (even when trusted)

Progressive rollout

A common pattern is to start restrictive and loosen over time:

Start with Read-Only — Workflow can analyze but not act
Move to Approval-Required — Workflow can propose actions for review
Autonomous — When behavior is stable and low-risk

Best practices

Default to approval-required for new workflows. Move to autonomous only after test runs and a review period.

Keep email-sending workflows on approval-required. Sent emails can’t be unsent. Review before sending.

Use read-only for experimentation. When testing prompts or configurations, read-only mode prevents accidents.

Check your approvals regularly. Approval-required only works if you actually review the requests. Don’t let them pile up.