Envelope

Proactive agents

Most AI workflows are reactive: a user presses a button, the team runs, results come back. Proactive agents flip this. The team decides when to run — observing external signals, checking conditions, and acting (or alerting you) without being asked.

This guide covers what proactive agents are, how to choose between trigger types, and what to think about before deploying one.

The shift: from reactive to proactive

| Reactive (today's default) | Proactive | |---|---| | You trigger the run | The system triggers the run | | You decide when | The team decides when | | You check the results | The team surfaces what matters |

The team itself — agents, prompts, tool connections, pipeline steps — is identical in both models. The difference is entirely at the trigger layer: what fires the run, and when.

When to use each trigger type

Event trigger — react to external signals

Use when something in another system should immediately kick off your team. The classic pattern: a new Zendesk ticket arrives → the triage team runs. A PR is merged → the review team runs. A deal stage changes in HubSpot → the follow-up team runs.

Any system that can POST to a URL can be the event source. Envelope generates a webhook URL and HMAC-SHA256 signing secret; you paste both into the source system.

Good fit for:

  • Support ticket triage on new ticket creation
  • Code review or CI commentary on PR merge
  • CRM follow-up on deal stage change
  • Alerting on monitoring webhook (PagerDuty, Datadog, etc.)

Not ideal for:

  • Conditions that require checking your own data (use condition trigger instead)
  • High-frequency event streams where you only want to act on some events (consider a condition trigger or a gate)

Condition trigger — act when something is true

Use when you want the team to monitor a state and act only when something changes or crosses a threshold. Rather than reacting to an external push, the team polls your connected tools on a schedule and runs a quick AI check before firing the full team.

Good fit for:

  • "Run this only if there are deals idle for more than 7 days"
  • "Fire the digest only if there is new significant activity to report"
  • "Alert me when the error rate exceeds the baseline"
  • Any pattern where most polls should produce no action

The condition prompt is plain English. Write it as a yes/no question: "Are there any open support tickets with priority 'urgent' that haven't been updated in 4 hours?"

Not ideal for:

  • Immediate response to external events (use event trigger — polling has inherent latency)
  • Conditions that are almost always true (you'd be running the full team every poll — consider a cron schedule instead)

Document-backed condition trigger — act when a row reaches a state

Teams that use workspace documents can declare condition triggers directly in the document schema, targeting row state rather than polling an external tool. When any unblocked row in the document has a status value that matches the trigger's declared condition, the team fires automatically.

{
  "workspace": [
    {
      "name": "outreach-list",
      "triggers": [
        { "column": "email-status", "status": "unverified", "action": "run" }
      ]
    }
  ]
}

This is cheaper and more reliable than a freeform condition prompt — the trigger evaluates a lightweight status index rather than calling a model. Rows with a non-empty blocked-by field are excluded from trigger evaluation regardless of their status value. The trigger does not fire on empty documents.

Good fit for:

  • Contact enrichment: fire the enrichment agent when new unverified rows appear
  • Outreach sequences: fire the send agent when rows reach verified status
  • Triage queues: fire the triage agent when rows reach needs-review
  • Any multi-step workflow where the document is the shared state layer

Setting up a proactive trigger

In the room thread (recommended)

Describe what you want in the thread and the assistant configures it:

  • "Trigger this when a new GitHub issue is opened" → event trigger
  • "Run this every hour, but only if there are unresolved tickets older than 24 hours" → condition trigger with 1h interval
  • "Fire this whenever our Zapier zap sends a signal" → event trigger

The assistant generates the webhook URL and secret, or configures the condition prompt and interval, and shows you what to configure in the source system.

In the team editor

Open the Schedule tab in the team editor. The trigger type selector shows three options: Scheduled, Event, and Condition. Each selection shows the relevant configuration fields.

Autonomy and human gates

Proactive triggers do not change what the agent is allowed to do. Action authority is still controlled entirely by human gate configuration — the same as any other team.

| Configuration | What happens | |---|---| | Proactive trigger + no gates | Fully autonomous — observes and acts without any human checkpoint | | Proactive trigger + gate before action | Observes autonomously, pauses for human approval before acting | | Cron + no gates | Same as proactive + no gates — fully autonomous on a time-based trigger |

A proactive team with no gates is a fully autonomous agent. It will observe, decide, and act on its own. For low-risk, reversible actions (posting a Slack message, logging a record, sending an internal alert) this is often exactly right. For higher-stakes actions — sending external emails, modifying customer records, making payments — add a gate before the action step.

The team editor shows a reminder when saving a proactive team with no gates. It is not a blocker.

Human gates guide →

Run provenance

When a proactive team fires, the run appears in your room thread with a badge showing how it was triggered:

  • EVENT badge (blue) — fired by an inbound webhook
  • CONDITION badge (green) — fired because the condition check returned yes

This makes it clear why a run appeared without you initiating it. The triggerSource field is also stored on every run record for audit and observability purposes.

What Envelope Local adds

On Envelope Managed cloud, proactive agents work via polling (condition) or inbound webhooks (event). Both require the cloud to be the entry point.

Envelope Local adds:

  • Near-realtime event response — the local daemon reacts to local events immediately without cloud polling overhead
  • Local data sources — local files, databases, and network resources the cloud cannot reach
  • Continuous trigger (future) — a persistent observation loop always watching a data stream

For most use cases on Managed cloud, event and condition triggers are sufficient. Local is the upgrade for teams that need to watch local systems or respond in milliseconds rather than seconds.

Envelope Local documentation is coming soon.

Checklist before deploying a proactive team

  • [ ] The team has run successfully at least once in test mode
  • [ ] You understand what action the team takes when it fires
  • [ ] If the action is irreversible, a human gate is configured before that step
  • [ ] The condition prompt (if using condition trigger) has been reviewed — make sure "yes" means "run the full team now"
  • [ ] The webhook secret (if using event trigger) is stored securely in the source system
  • [ ] You know what the polling interval costs in tokens at your expected positive rate (condition trigger)
‹ All guidesDocs ›