*** Escalation instructions Escalation instructions guide your agent on handling situations it cannot resolve independently. Without custom instructions, agents use default behavior: * Escalate to a human agent only when you cannot solve the problem using knowledge base lookups or available workflows * Avoid unnecessary back-and-forth with the requester. If clarifying questions don’t help, proceed with escalation * When escalating, create a ticket and inform the user that a human agent will take over * Once escalated, do not attempt to further solve the issue Configure escalation instructions Open your agent’s settings page. Locate the **Escalation Instructions** section under Capabilities. Click **Add** (or **Edit** if instructions already exist). Write your escalation guidelines using natural language and `@` mentions. Save your escalation instructions. Use mentions in escalation instructions Reference resources using `@` mentions: * **Knowledge bases**: Direct the agent to check specific knowledge sources before escalating * **Workflows**: Trigger specific workflows as part of the escalation process * **Forms**: Create tickets with specific forms when escalating **Example with knowledge and form:** **Example with workflow:** Best practices * Be specific about escalation triggers with clear conditions * Include user communication telling the agent what to say when escalating * Set expectations with information about response times or next steps * Reference resources using `@` mentions to connect escalation to specific workflows or forms *** Rules Rules are natural language instructions that define how your agent handles specific scenarios. Each rule teaches your agent a capability using prompts that reference Ravenna resources like forms, knowledge folders, and workflows. Rule structure Each rule contains: * **Title**: Descriptive name for the rule (for example, “Password reset handler”) * **Instruction**: Natural language prompt telling the agent what to do and when * **Enabled/disabled toggle**: Control whether the rule is active When to use rules Create rules when you want your agent to: * Handle specific request types consistently * Route requests to the correct form * Reference specific knowledge sources for answers * Follow defined processes for common scenarios * Provide specialized responses for particular topics Writing effective rules **Be specific about triggers** Clearly define when the rule should activate. **Reference resources with @ mentions** Use `@` to link to specific Ravenna resources. **Define expected outcomes** Tell the agent what success looks like. **Keep instructions focused** Each rule should handle one scenario. Create multiple rules for different use cases rather than one complex rule. **Knowledge-first response** **Password reset handling** **Software access requests** **Workflow automation** **Hardware issues** **Multi-step process** * Use clear, conversational language as if explaining to a colleague * Break complex logic into numbered steps for multi-part processes * Include fallback behavior telling the agent what to do if the primary action isn’t possible * Specify tone when needed, adding guidance like “respond empathetically” for sensitive topics When you type `@` in a rule, escalation instruction, or skill, the resource picker groups suggestions by resource type. If your workspace organizes resources into folders or collections, you can drill into them to find a specific item without scrolling through a flat list. Drilldown is available for resources that support nested hierarchies: * Knowledge folders and their subfolders * Form folders (request type collections) and their subfolders * Workflow collections and their nested collections **How drilldown works** * Folder entries show the total number of items they contain, including items in nested subfolders. * Press **Tab** or **→** on a folder to open it and see its contents. Press **←** or **Backspace** to go back up one level. * Press **Enter** on a folder to grant the agent access to the entire folder, including everything nested inside. * Press **Enter** on an individual document, form, or workflow to grant access to just that item. **Selecting a whole folder vs. a specific item** Selecting a folder is a quick way to give the agent broad access to a topic. For example, mentioning `@IT Knowledge Base` grants access to every document inside that folder and its subfolders. If you want the agent to use only a specific article, drill in and select that document directly. **Mention chip display** Once you select an item, the mention chip shows the top-level resource category followed by the item name (for example, `IT Knowledge Base / VPN Setup`). Intermediate subfolder names are omitted to keep rules readable. Documents whose parent folder has been deleted or archived still appear at the root of the picker so you can reference them. Re-organize or archive these items in the source view if you want to clean them up. You can write rules that instruct the agent to send responses privately. When a rule involves sharing credentials, API keys, or other sensitive information, the agent automatically sends that content as a private DM to the requester. You can also explicitly instruct the agent to respond privately in a rule. V3+ **Form access** You must reference forms within rules for the agent to create tickets of that type. Your agent does not have access to all forms by default. The agent only uses forms that are **Published**. If a referenced form is in **Draft** or **Archived** status, the agent skips it and falls back to other matching rules or escalates. Publish a form before referencing it in a rule to ensure the agent can present it to users. **Workflow access** You must reference workflows within rules for the agent to trigger them. Your agent does not have access to all workflows by default. **Rule selection** The agent selects the single best matching rule for each request. When multiple rules could apply, it picks the most specific one. Keep rules distinct for predictable behavior. Manage rules at workspace level Create reusable rules at the workspace level from the **Rules** tab on the Agents page. Workspace-level rules can be shared across multiple agents for consistent behavior. Navigate to **Agents** in your workspace and click the **Rules** tab. Click **New Rule** and enter a descriptive title. Write the instruction using natural language and `@` mentions to reference forms, knowledge folders, workflows, and tools. Click **Save** to create the rule. **Workspace-level vs agent-specific rules** | Aspect | Workspace-level rules | Agent-specific rules | | --------------- | --------------------------------------------------- | --------------------------------------- | | **Location** | Rules tab on Agents page | Individual agent’s Capabilities section | | **Reusability** | Can be attached to multiple agents | Only available to that specific agent | | **Management** | Centralized editing with changes applied everywhere | Edited per agent | | **Best for** | Common scenarios shared across teams | Agent-specific behavior | Create workspace-level rules for common scenarios like password resets or software access requests that multiple agents should handle consistently. Use agent-specific rules for behavior unique to a particular agent or channel. **Reuse rules across agents** Attach workspace-level rules to multiple agents: 1. Create a rule in the **Rules** tab 2. Open any agent and navigate to **Capabilities** > **Rules** 3. Click **Add Rule** and select from your workspace rules 4. Add the same rule to as many agents as needed When you update a workspace-level rule, changes automatically propagate to all agents using that rule. You cannot delete a rule currently attached to one or more agents. Remove it from all agents before deletion. **Duplicate rules** Create an independent copy of a rule and attach it to any compatible agent: 1. Open an agent and navigate to **Capabilities** > **Rules** 2. Click the action menu on the rule you want to copy 3. Select **Duplicate** 4. Enter a title for the new rule (defaults to the original title with “Copy” appended) and choose a target agent 5. Click **Duplicate** to create the copy The duplicate is fully independent. Editing the original rule does not affect the copy, and vice versa. Use duplicate when you want to create an independent variation of a rule for a different agent. Use attach when you want multiple agents to share the same rule. **Delete a rule** To delete a workspace rule, open it in the editor and click **Delete**. Rules that are currently attached to one or more agents must be detached first. Deletion is permanent and cannot be undone. **Customize the rules table view** The **Rules** tab on the Agents page displays all workspace-level rules in a sortable table. Use the **View** menu above the table to control which columns are visible. Hide columns you do not need to focus on the information that matters for your workflow. On the **Rules** tab, click the **View** button above the rules table. Select or clear the checkbox next to each column to show or hide it. Your selection is remembered for the next time you open the table. **Bulk delete rules** Delete multiple workspace-level rules at once from the **Rules** tab. Use bulk delete to clean up unused or outdated rules in one action instead of removing them individually. On the **Rules** tab, use the checkbox at the start of each row to select the rules you want to delete. Use the checkbox in the table header to select every rule on the current page. Click the **Delete** button that appears in the bulk actions bar above the table. Review the list of rules in the confirmation dialog and click **Delete** to remove them. You cannot bulk delete rules that are currently attached to one or more agents. Detach a rule from every agent before including it in a bulk delete. If your selection includes attached rules, the delete action skips them and reports which rules were not deleted. Bulk delete is permanent. Deleted rules cannot be restored, and any agents that previously used them lose those instructions. *** Knowledge Select specific knowledge folders for your agent to access when answering user questions. This ensures the agent provides accurate information based on your organization’s knowledge base. Learn how to [set up and manage knowledge sources](/documentation/automate/knowledge/overview) *** Tools Tools extend your agent’s capabilities to query data, execute commands, and automate tasks. Agents have access to built-in Ravenna tools for ticket management and web search, plus additional tools from installed integrations like device management systems and CRM platforms. How tools work Tools are referenced in rules using @ mentions. When you write a rule, use @ mentions to specify which tool actions the agent should use and when to use them. Tool availability and explicit opt-in By default, some built-in tools only appear to the agent when the workspace has matching context. For example, the agent hides `@Set Category` when the workspace has no categories, and hides form-related tools when no forms are attached to a matched rule. This keeps the tool surface focused so the agent never sees an action with nothing to act on. Attaching a tool to the agent, or `@`-mentioning it in a rule, counts as an explicit opt-in and bypasses those context-presence checks for that turn. Use this when you want a tool surfaced even if the supporting context is sparse or builds up over the conversation. * **Admin opt-in:** Tools attached to the agent under **Capabilities** > **Tools** are always available to the agent. * **Rule opt-in:** Tools `@`-mentioned in a matched rule are available for that turn, even if other context (forms, categories, workflows) is empty. * **Knowledge lookup stays scoped.** `@Search Knowledge Base` is a data boundary, not just an affordance. It only appears when the agent has at least one knowledge folder attached, or a matched rule mentions a `@Knowledge folder` or `@Knowledge document`. Explicit tool opt-in does not unlock knowledge search on its own — you must also point the agent at the knowledge to search. * **Integration availability still applies.** Disconnected integrations make their tools unavailable regardless of opt-in. The **Tools** picker in the agent editor mirrors what the agent will actually see at runtime. Tools that depend on workspace context — such as `@Search Knowledge Base` when no knowledge folders are attached — are hidden from the picker so you do not advertise an action the agent would silently drop. **Example rule using Ravenna tools:** **Example rule using Fleet device management tools:** **Example rule using HubSpot CRM tools:** Ravenna tools Built-in tools available to all agents for ticket management, application lookup, and information retrieval. Creates new tickets with specified properties like title, description, channel, priority, and custom fields. Agents can create tickets based on conversation context, automatically routing requests to the appropriate channels with pre-filled information. **Common use cases:** * Create support tickets from Slack conversations * Generate tickets with pre-filled form data * Route requests to specific channels * Automate ticket creation for common request types Updates existing ticket properties including title, description, priority, tags, assignees, requester, and custom fields. Agents can modify tickets based on new information gathered during conversations. **Common use cases:** * Add context to existing tickets * Update priority based on urgency * Modify ticket properties from conversation * Add tags for categorization Adds a user as an approver to a ticket. Agents can manage approval workflows by adding approvers based on conversation context or request type. **Common use cases:** * Add managers as approvers for access requests * Route approvals to specific team members * Manage multi-step approval processes * Dynamically assign approvers based on request type **Example rule:** Approves a ticket on behalf of the user. The user must be an approver on the ticket or a workspace admin. Enables conversational approval workflows where authorized users can approve requests through natural language. **Authorization:** * User must be listed as an approver on the ticket, OR * User must be a workspace admin **Common use cases:** * Enable conversational approvals in Slack * Streamline approval workflows * Allow admins to approve any ticket * Reduce approval friction for authorized users **Example rule:** Retrieves the list of applications available in the workspace. Agents can reference this list when helping users request access to software and tools. **Common use cases:** * Help users discover available applications * Validate application names in access requests * Provide information about available software * Guide users through application access processes Retrieves all access levels for a specific application. Access levels define permission tiers for applications (for example, Read Only, Editor, Admin). Agents use this tool to populate access level fields in forms and workflows accurately. **Tool name:** `@List Access Levels` **Input:** Requires an application ID **Automatic prefilling:** When only one access level exists for an application, agents automatically prefill it in forms even if the user didn’t explicitly mention it. **Common use cases:** * Populate access level fields in access request forms * Validate user-requested access levels against available options * Determine available permission tiers for applications * Auto-fill forms when only one access level exists **Example rule:** Mentions a user in the agent’s response with proper platform-specific formatting. The tool automatically handles platform differences, using Slack user IDs for Slack conversations and display names for other channels like email and web. **Tool name:** `@Mention User` **Common use cases:** * Include multiple people in collaborative responses * Notify specific users about actions or updates * Facilitate multi-user conversations * Loop in relevant team members **Example rule:** Searches the web for current information not available in your knowledge base. Agents can research topics, find documentation, and provide up-to-date answers requiring external information. **Common use cases:** * Find current information not in knowledge base * Research technical questions * Look up external documentation * Provide real-time information Searches for users by name or email within your organization. Returns matching user records with their Ravenna user IDs. Use this tool when the agent needs to identify a specific user, for example to populate user selection fields in forms or resolve a name mentioned in a request. **Tool name:** `@User Lookup` **Search behavior:** * Matches against first name, last name, and email address, even with partial or approximate input * Supports multi-word queries (searches each word across all fields) * Returns users ordered by relevance * Scoped to your organization only **Common use cases:** * Resolve user names to Ravenna user IDs for user selection fields * Look up team members when processing requests that reference people * Find users when the requester mentions someone by name * Populate manager or approver fields in access request forms When users are @mentioned in Slack, the Ravenna user ID is already included in the message metadata. The agent only needs User Lookup when the user is referenced by name without an @mention. **Example rule:** Searches for user groups within your workspace. Returns matching group records with their IDs, names, descriptions, and source (for example, RAVENNA, OKTA, GOOGLE\_WORKSPACE, or SLACK). Use this tool when the agent needs to resolve a group name to populate user group selection fields in forms. **Tool name:** `@Group Lookup` **Search behavior:** * Searches across group name, description, email, and other metadata fields registered by integrations * Supports multi-word queries (each word must match somewhere across the group’s searchable fields) * Scoped to the current workspace. Only groups visible in that workspace are returned * When called with a form ID and field ID, results respect the field’s allowlist and source constraints (for example, only native groups or only groups from a specific integration) **Common use cases:** * Resolve group names to IDs for user group selection fields in forms * Look up teams or departments when processing requests that reference a group * Find groups when the requester mentions a team by name or email **Example rule:** Assigns a category to the current ticket. Categories are workspace-wide classification labels that help organize and route tickets. **Tool name:** `@Set Category` **Common use cases:** * Automatically categorize tickets based on conversation content * Apply categories as part of triage rules * Set categories to trigger category-based workflows **Example rule:** Retrieves all available ticket statuses in the workspace. Returns status labels, IDs, and status groups. Agents use this tool to discover valid statuses when updating tickets. **Tool name:** `@List Statuses` **Common use cases:** * Discover available statuses before updating a ticket’s status * Validate status names mentioned by users * Help users understand the ticket lifecycle stages **Example rule:** Searches and filters tickets using text search and property-based filters. Supports hybrid search combining keyword and semantic matching on ticket titles and ticket numbers. **Tool name:** `@List Tickets` **Search and filter options:** * **Text search**: Searches ticket titles and ticket numbers * **Filters**: Priority, assignee, status, queue, form, requestor, source, tags, created date, updated date, resolved date, and due date **Common use cases:** * Find tickets matching specific criteria for reporting or triage * Look up tickets assigned to a particular user or team * Search for tickets by keyword across a workspace * Filter tickets by status, priority, or date range **Example rule:** Retrieves detailed information about a specific ticket including title, description, priority, status, assignee, requester, tags, and timestamps. Accepts full ticket IDs, 8-character short IDs, or PREFIX-NUMBER format (for example, TICK-1234). **Tool name:** `@Get Ticket Info` **Supported ID formats:** * Full CUID (for example, `clx123...`) * 8-character short ID (for example, `abc12345`) * PREFIX-NUMBER (for example, `TICK-1234`) **Common use cases:** * Look up the current status and details of a specific ticket * Check who is assigned to or requested a ticket * Retrieve ticket context before making updates * Answer user questions about a specific request **Example rule:** Retrieves the conversation history for a ticket in chronological order. Returns message content, author information, and timestamps. Accepts the same ID formats as Get Ticket Info. **Tool name:** `@Get Ticket Messages` **Common use cases:** * Review the conversation history on a ticket * Understand what has been discussed or resolved * Provide context when escalating or reassigning tickets * Summarize a ticket’s communication thread **Example rule:** Retrieves all channels in the workspace. Returns channel names, IDs, prefixes, and emoji icons. Use this to find channel IDs for filtering tickets or routing new tickets to the correct channel. **Tool name:** `@List Channels` **Common use cases:** * Help users discover available channels for submitting requests * Find channel IDs for ticket filtering or creation * Provide an overview of how the workspace is organized **Example rule:** Retrieves detailed information about a specific channel by ID, including its name, prefix, emoji, and creation date. **Tool name:** `@Get Channel Info` **Common use cases:** * Look up details about a specific channel * Verify channel configuration before routing tickets * Provide channel context when helping users navigate the workspace **Example rule:** Creates a new channel in the workspace with a specified name and emoji. The channel prefix is generated automatically by the system. **Tool name:** `@Create Channel` **Common use cases:** * Set up new channels for teams or projects * Create channels as part of workspace onboarding * Add channels for new request categories **Example rule:** Updates an existing channel’s name or emoji. **Tool name:** `@Update Channel` **Common use cases:** * Rename channels to reflect updated team or project names * Change a channel’s emoji icon **Example rule:** Retrieves all forms available in the workspace. Returns form names, IDs, descriptions, and whether they have custom fields enabled. Supports optional text search to filter by name or description. **Tool name:** `@List Forms` **Common use cases:** * Help users find the right form for their request * Look up form IDs before creating tickets * Provide an overview of available forms **Example rule:** Retrieves the custom fields defined on a specific form, including field labels, types, required status, and available options for select fields. Use this before creating tickets with custom field values. **Tool name:** `@List Custom Fields` **Input:** Requires a form ID **Common use cases:** * Discover what fields a form requires before creating a ticket * Validate user-provided values against available options for select fields * Understand form structure to collect the right information from users **Example rule:** Retrieves users in the workspace with optional search filtering by name or email. Returns user IDs, names, and email addresses. Use this to find user IDs for assigning tickets, setting requesters, or adding followers. **Tool name:** `@List Users` **Common use cases:** * Find user IDs for ticket assignment or requester fields * Search for team members by name or email * Discover workspace members for collaboration **Example rule:** Retrieves a specific user’s details by their ID, including first name, last name, and email address. **Tool name:** `@Get User By ID` **Common use cases:** * Look up user details when you have a user ID from another tool’s output * Resolve user IDs from ticket data into readable names and emails * Verify user information before taking actions on their behalf **Example rule:** Searches your organization’s internal knowledge base documents using hybrid retrieval (semantic and keyword matching). Returns relevant document chunks from HR policies, IT procedures, benefits information, onboarding guides, and other ingested content. **Tool name:** `@Search Knowledge Base` **Access scoping:** Results are scoped based on the user’s workspace role. Admins and members see all knowledge bases, while guests see only global knowledge bases and those linked to their associated channels. **Common use cases:** * Answer questions about internal company policies and procedures * Find IT documentation and troubleshooting guides * Look up HR benefits, leave policies, or onboarding information * Search for internal process documentation before escalating **Example rule:** Third-party integration tools Additional tools become available when you install and connect integrations to your workspace. Each integration provides specialized tools for its platform. Integration tools require the corresponding integration to be installed and connected to your workspace. If an integration is disconnected, tools for that integration will show a warning indicator. **Integrations with agent tool support:** * [Fleet](/integrations/fleet/agent-tools) * [HubSpot](/integrations/hubspot/agent-tools) * [Iru](/integrations/iru/agent-tools) * [Jamf Pro](/integrations/jamf/agent-tools) * [Microsoft Intune](/integrations/intune/agent-tools) Review the [Integrations page](/integrations/overview) to see all available integrations Tool execution policies Each tool referenced in a rule can be gated with an **execution policy** that controls what happens before the agent invokes it. Policies are scoped per rule, so the same tool can run automatically in one rule and require approval in another. Set the policy from a rule’s tool list. Each tool shows an **Execution Policy** row with three modes: | Mode | Behavior | Best for | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Auto-execute | The tool runs immediately when the agent invokes it. No approval or confirmation step. | Read-only lookups and low-risk actions where speed matters. | | Requires confirmation | The agent describes the action it intends to take and waits for the requester to confirm before running the tool. No approval round is created. | A safety net for admins self-servicing write actions, where you want a final “Should I proceed?” prompt before the change happens. | | Requires approval | The agent buffers the tool call, opens an approval round on the ticket, and only runs the tool after every required approval is granted. | High-impact actions like provisioning access, creating groups, or modifying production data. | **Defaults:** * Read tools (such as lookups and searches) default to **Auto-execute**. * Write and delete tools (such as create, update, add member, deactivate) default to **Requires confirmation** so admins are prompted before changes are made. Choose approvers When you select **Requires approval**, an **Approvers** field appears for that tool. Pick one of: * **Workspace Admins (default)** — any workspace admin can approve. No template needed. * **An [approval template](/documentation/tickets/approvals/templates)** — uses the template’s rounds, policies (any-of / all-of), and approver lists. Choose this when you need named approvers, user groups, role-based approvers like the requester’s manager, or multiple sequential rounds. * **Create approval template** — opens the template editor in-place. The new template is selected on the tool as soon as you save it. Approvers are notified by Slack DM when an approval round opens. The agent will not execute the gated tool — or any other approval-gated tool it batched alongside it in the same plan — until the round clears. Batched approvals When a single agent run plans multiple approval-gated tool calls, Ravenna does not open one approval round per tool. Instead, after the agent finishes reasoning it groups buffered calls by approver set and opens **one parallel approval round per group**. Once every round clears, the agent re-runs and executes the buffered calls with the originally planned inputs. This avoids forcing approvers through several sequential prompts for a single user request. Example: gate a sensitive write tool The rule below uses Google Workspace tools to add a user to a group. Configure the rule’s tool list so that `List Google Groups` stays on **Auto-execute** (it only reads) while `Add member to Google Group` is set to **Requires approval** with an “IT leads” approval template. With this configuration, the lookup runs immediately, but the membership change waits for an approval round. If the same `Add member to Google Group` tool is used in a different rule (for example, a self-service onboarding rule for direct reports of a manager), you can set a different policy on that rule without affecting this one. Execution policies are set per rule, not per tool globally. If a tool is referenced in multiple rules, configure the policy in each rule based on the risk of that specific scenario. Best practices * Reference tools in rules using @ mentions to define when and how the agent should use them * Provide context about what to do with tool results (analyze, summarize, troubleshoot) * Combine multiple tool actions for complex multi-step processes * Use Ravenna tools for ticket management and approval workflows * Use integration tools for platform-specific data retrieval and actions * Test tool-based rules thoroughly to ensure correct data retrieval and analysis * Monitor agent logs to identify tool usage patterns and opportunities for optimization

Documentation Index