Documentation

How the Agent Acts

Vigil agents don't just read email. They make decisions and take action. Every email that arrives triggers a decision: should I alert the user? Should I track this silently? Should I fire a webhook? Should I remember something for later? The agent decides based on your prompt, your reactivity level, and the tools you've enabled.

The Decision Flow

When an email arrives, the agent goes through this process:

Read and understand. The agent reads the full email, identifies the sender, extracts dates, amounts, names, and determines what the sender wants.
Check memory. The agent loads relevant memories from previous emails. Has this sender written before? Is there an ongoing conversation? Are there related deadlines?
Check threads. The agent looks at active threads. Is this a reply to something already being tracked? Is this a new conversation?
Decide. Based on your prompt, reactivity level, and the email content, the agent decides what to do. Most emails get triaged silently. Some trigger actions.
Act. The agent uses its enabled tools to take action. Every action is logged with the reasoning behind it.

Tools

Tools are the actions your agent can take. You enable them in your watcher settings. The agent decides when to use each tool based on your prompt and the email content. You don't need to write tool logic into your prompt — just describe what you care about, and the agent figures out which tool to use.

Built-in Tools

Send Alert — sends you an email notification when something needs your attention. The agent writes a concise summary of what happened and why it matters. Alerts are the most visible action and are governed by your reactivity level.
Update Thread — changes the status of a conversation thread. The agent uses this to mark threads as active (needs monitoring), watching (tracking but not urgent), resolved (handled), or ignored (noise). Thread status determines whether the agent checks for silence.
Ignore Thread — marks a thread as noise. The agent stops monitoring it entirely. Used for marketing emails, newsletters, and anything that doesn't need tracking.
Webhook — sends structured data to any URL you configure. This is how Vigil connects to external systems. When the agent decides to fire a webhook, it sends the email context, extracted data, and its analysis to your endpoint.

Custom Tools

Define your own tools to connect Vigil to any external system. Each custom tool has a name, a description (which the agent reads to know when to use it), a webhook URL, and a parameter schema that tells the agent what data to extract from the email.

Create custom tools in the dashboard (Settings → Tools) or via the API:

Slack notification — fire a webhook to Slack when a client emails
Jira ticket — create a ticket when the agent identifies a support request
Notion database — log invoice details into a Notion table
PagerDuty alert — escalate urgent infrastructure emails
Custom API — POST to any endpoint you control

The agent sees your custom tools alongside built-in tools. When it decides to use one, it extracts the parameters you defined from the email content and POSTs them to your webhook URL with full email context. Every execution is logged.

Prompts vs Tools

Your prompt tells the agent what to care about. Tools give it the ability to act. You don't need to mention tools in your prompt.

For example, if your prompt says:

"Monitor client emails. Alert me when someone is waiting for a response or when a deadline is approaching."

The agent automatically knows to use Send Alert when it detects urgency, Update Thread to track the conversation, and its memory to remember the deadline. You describe the intent. The agent picks the right tool.

However, you can add specific instructions to your prompt to fine-tune behavior:

"Never alert me about receipts or payment confirmations"
"Always mark emails from support@company.com as active"
"Fire the Slack webhook whenever a client mentions a deadline"

These override the agent's default judgment for specific cases.

Reactivity

Reactivity controls how aggressively the agent uses the Send Alert tool. At low reactivity, almost nothing triggers an alert. At high reactivity, the agent surfaces more. Other tools (thread updates, memory, webhooks) are not affected by reactivity.

Level 1 (Minimum) — only active security breaches and fraud
Level 2 (Low) — security events, money at risk, deadlines within 24 hours
Level 3 (Balanced) — financial events, deadlines within 48 hours, direct requests from real people
Level 4 (High) — all financial transactions, deadlines within a week, any personal email expecting a response
Level 5 (Maximum) — surfaces almost everything including subscribed content

Scheduled Reviews

The agent doesn't only react to incoming email. On a regular schedule (configured by the tick interval), the agent wakes up and proactively reviews all active threads. It checks:

Has any thread gone quiet beyond the silence threshold?
Are any deadlines in memory approaching?
Is someone waiting for a response that hasn't arrived?
Should any threads be upgraded or downgraded?

This is how Vigil catches things you might miss — not just reacting to what arrives, but noticing what didn't arrive.

Chat Control

You can talk to your agent through the dashboard chat. The agent has full context of your inbox and can take any action you ask for:

"Ignore all emails from LinkedIn" — ignores existing threads and adds a persistent rule
"What needs my attention?" — summarizes obligations across all threads
"Be more aggressive about deadline alerts" — modifies the agent's behavior permanently
"Resolve the payment thread" — finds and closes the thread

Chat commands can modify your agent's prompt, add rules to its memory, and take immediate action on threads. It's the fastest way to control your agent without touching settings.

Audit Trail

Every decision the agent makes is logged. You can see exactly what tool was used, why, what the agent was thinking, which model processed it, how much it cost, and how long it took. The Activity tab in the dashboard shows the full history.