Rehaul escalations → alerts docs (TSP-1058)

build/agents/build-your-agent/alerts.mdx

@@ -0,0 +1,110 @@
+---
+title: 'Alerts'
+sidebarTitle: 'Alerts'
+description: 'Set up rules to get notified when your agent encounters an issue, reaches a threshold, or gets updated.'
+---
+
+Set up rules to get notified when your agent encounters an issue, reaches a threshold, or gets updated.
+
+<Note>
+Alerts are available on paid plans only.
+</Note>
+
+## Alert rules
+
+Stay on top of agent issues by creating alert rules that notify you automatically when specific events occur. Each rule has a **trigger condition** (what happened) and one or more **notification channels** (where to send it).
+
+### Alert types
+
+<CardGroup cols={3}>
+  <Card title="Status change" icon="rotate">
+    Triggers when an agent task enters one or more specific statuses you select.
+  </Card>
+  <Card title="Tool error" icon="wrench">
+    Triggers when a tool fails during execution, optionally scoped to specific tools.
+  </Card>
+  <Card title="Agent published" icon="rocket">
+    Triggers when the agent is published. No additional configuration needed.
+  </Card>
+</CardGroup>
+
+#### Status change
+
+Triggers when an agent task enters one or more specific statuses. Select which statuses you want to be alerted on from the multi-select dropdown.
+
+<Accordion title="Available statuses">
+Starting up, Waiting for capacity, Pending approval, Running, Cancelled, Idle, Timed out, Escalated, Unrecoverable error, Paused, Completed, Exhausted retries, Queued for approval, and Queued for rerun.
+</Accordion>
+
+<Tip>
+A common configuration is to alert on failure states like **Timed out**, **Unrecoverable error**, and **Exhausted retries** so your team can respond quickly when something goes wrong.
+</Tip>
+
+#### Tool error
+
+Triggers when a tool fails during execution. You can optionally scope this to specific tools — leave the selection empty to watch all tools, or pick individual tools to monitor. This is useful for critical integrations where a tool failure could block your agent's workflow.
+
+#### Agent published
+
+Triggers when the agent is published. No additional configuration is needed — select a notification channel and you'll be alerted whenever a new version goes live.
+
+### Notification channels
+
+Each alert rule can send notifications to one or more channels:
+
+<CardGroup cols={3}>
+  <Card title="Email" icon="envelope">
+    Add one or more email addresses. No OAuth connection required.
+  </Card>
+  <Card title="Slack" icon="slack" iconType="brand">
+    Connect your Slack workspace via OAuth, then select a channel.
+  </Card>
+  <Card title="Microsoft Teams" icon="microsoft" iconType="brand">
+    Connect your Microsoft Teams account via OAuth, then select a team and channel.
+  </Card>
+</CardGroup>
+
+For Slack setup details, see [Slack integration](/integrations/popular-integrations/slack). For Teams, see [Microsoft Teams integration](/integrations/popular-integrations/microsoft-teams).
+
+### Setting up an alert rule
+
+1. Navigate to your agent and open the **Alerts** tab
+2. Click **Create alert rule**
+3. Select a trigger type from the left panel
+4. Configure the trigger conditions (if applicable)
+5. Preview how the notification will look
+6. Add at least one notification channel
+7. Click **Save**
+
+You can create multiple alert rules, each with different triggers and channels. Existing rules appear as cards showing the trigger description, active channels, and controls to edit, delete, or toggle them on/off.
+
+---
+
+## Agent escalations
+
+When your agent encounters a situation it cannot handle, it can escalate the conversation to a human manager using the built-in **Escalate to Manager** tool.
+
+This is different from alert rules — escalation is an in-conversation handoff where the agent actively routes a conversation to a human, rather than a background notification about an event.
+
+### Enabling the escalation tool
+
+In the **Agent escalations** section at the bottom of the Alerts page, click **Enable escalation tool**. This adds the "Escalate to Manager" tool to your agent's available tools.
+
+Once enabled, you can reference the tool in your agent's prompt using the **/** command to give the agent guidance on when to escalate. Click **Edit prompt** to go directly to the prompt editor.
+
+### When to use escalation
+
+<CardGroup cols={2}>
+  <Card title="Complex technical support" icon="headset">
+    Issues requiring specialized knowledge beyond the agent's training.
+  </Card>
+  <Card title="Sensitive situations" icon="hand-holding-heart">
+    Customer service scenarios that need human empathy and judgment.
+  </Card>
+  <Card title="Product feedback" icon="comment">
+    Detailed feedback that should reach product managers directly.
+  </Card>
+  <Card title="High-value sales" icon="handshake">
+    Opportunities requiring personalized human attention.
+  </Card>
+</CardGroup>

build/agents/build-your-agent/build-overview.mdx

@@ -16,10 +16,10 @@
 2. **Tools**: Connect the actions your Agent can take, such as sending emails, posting to Slack, or retrieving data.
 3. **Knowledge**: Add sources of knowledge to your Agent to help it answer questions and complete tasks.
 4. **Triggers**: Define when and how your Agent should take action automatically.
-5. **Escalations**: Set up backup workflows if tasks can't be completed successfully.
+5. **Alerts**: Get notified when your agent needs attention, and escalate conversations to a human when needed.
 6. **Memory**: Add important labels, tags, and additional information to organize and enhance your Agent.
 7. **Variables**: Create dynamic placeholders that let your Agent personalize its actions based on different inputs.
 8. **Advanced**: Tweak advanced settings like connecting subagents, temperature, etc. 
 
 <Tip>You can learn about these settings in any order, but we recommend starting with the Prompt since it’s the foundation of how your Agent will behave.</Tip>
 

build/agents/build-your-agent/tools.mdx

@@ -68,4 +68,44 @@
 - **Integration**: Connecting with external systems and APIs
 - **Content Creation**: Generating text, images, or other media
 
-By thoughtfully selecting and configuring the right tools for your agent, you can create a powerful assistant that delivers exceptional value to your users through both conversation and action.
+By thoughtfully selecting and configuring the right tools for your agent, you can create a powerful assistant that delivers exceptional value to your users through both conversation and action.
+
+## Tool Approvals
+
+Control whether your agent needs permission before running a tool. You can set the approval mode individually for each tool.
+
+### Auto Run
+
+The tool runs automatically whenever the agent determines it should be used. The agent incorporates tool functionality without interrupting the conversation flow.
+
+**Best for:** Tools that are low-risk, frequently used, or where immediate action is beneficial.
+
+### Approval Required
+
+The agent will ask for explicit permission before using the tool. When the agent determines a tool would be helpful, it will first explain what it wants to do and why, then wait for user confirmation before proceeding.
+
+**Best for:** Tools that perform sensitive actions, have potential costs associated with them, or where user oversight is important.
+
+### Let Agent Decide
+
+This balanced approach gives your agent the flexibility to determine when approval is necessary based on context. The agent will use its judgment about when to ask for permission versus when to proceed automatically.
+
+**Best for:** A mix of tool types where you want to balance convenience with appropriate caution.
+
+## Tool Settings
+
+### Failure policy
+
+Define what your agent should do when a tool errors. Open the **Tool Settings** on the Tools page to configure the failure policy.
+
+#### Always retry errored tool
+
+When on, forces the agent to retry errored tools until success or max retries (at which point the task will fail). When off, the agent decides on its own whether it's worth retrying. For most users, enabling retries is a safe way to handle occasional hiccups without manual intervention.
+
+#### Maximum number of tool retries
+
+The number of times the agent will retry a tool that errors before marking the task as failed. A few retries (like 3) usually strikes a good balance — it gives your agent a second chance without risking long loops or extra costs. Increasing this may raise credit usage.
+
+#### Behavior after max tool retries
+
+Decide what should happen when the maximum number of retries is reached: either **Terminate task** immediately or **Escalate** it to a human for help. Terminating is faster and simpler, but escalation gives you a chance to fix things manually when it matters most.

build/agents/create-an-agent.mdx

@@ -86,5 +86,5 @@ Once you've created an Agent, explore the rest of the build guides to refine it:
 - [Prompt](/build/agents/build-your-agent/prompt) — write instructions that define your Agent's behavior
 - [Tools](/build/agents/build-your-agent/tools) — give your Agent the actions it needs
 - [Triggers](/build/agents/build-your-agent/triggers) — run your Agent automatically on a schedule, from a webhook, or from an integration
-- [Escalations](/build/agents/build-your-agent/escalations) — define when your Agent should loop in a human
+- [Alerts](/build/agents/build-your-agent/alerts) — get notified when your Agent needs attention, and define when it should loop in a human
 - [Memory](/build/agents/build-your-agent/memory) — configure how your Agent retains context across conversations

docs.json

@@ -94,7 +94,7 @@
                   "build/agents/build-your-agent/prompt",
                   "build/agents/build-your-agent/tools",
                   "build/agents/build-your-agent/triggers",
-                  "build/agents/build-your-agent/escalations",
+                  "build/agents/build-your-agent/alerts",
                   "build/agents/build-your-agent/memory",
                   "build/agents/build-your-agent/variables",
                   "build/agents/build-your-agent/evals",
@@ -630,6 +630,10 @@
     }
   },
   "redirects": [
+    {
+      "source": "/build/agents/build-your-agent/escalations",
+      "destination": "/build/agents/build-your-agent/alerts"
+    },
     {
       "source": "/get-started/system_limits",
       "destination": "/admin/system-limits"

get-started/quick-start-guide.mdx

@@ -109,7 +109,7 @@
 - Use [Relevance Chat](/get-started/chat/introduction) to give your team instant access to your agents
 - Set up [triggers](/build/agents/build-your-agent/triggers) to run it automatically — on a schedule, from a webhook, or when something happens in your CRM
 - Use [bulk schedule](/build/agents/give-your-agent-tasks/bulk-schedule) to run it across a list of inputs
-- Add [escalations](/build/agents/build-your-agent/escalations) so the agent knows when to loop in a human
+- Add [alerts](/build/agents/build-your-agent/alerts) so you get notified when something needs attention, and the agent knows when to loop in a human
 
 ## Beyond building
 
@@ -119,7 +119,7 @@
 
 ![Relevance Chat — @ mention any Agent and interact with it directly.](/images/quickstart-chat.png)
 
 [Relevance Chat](/get-started/chat/introduction) is a conversational interface where you and your team interact with your agents directly. Type a message, @ mention any agent in your project, and it will handle the task using the tools and knowledge you've configured. You can switch between LLMs, combine multiple agents in a single conversation, and save prompts your team uses often. Chat also comes with built-in agents for things like building websites, generating images, deep research, and creating presentations.
 
 Visit [chat.relevanceai.com](https://chat.relevanceai.com) to get started — it works on desktop and mobile.