> ## Documentation Index > Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt > Use this file to discover all available pages before exploring further. # Configure > Configure agent capabilities by writing rules, defining escalation instructions, granting knowledge access, and connecting integration tools. Define what your agent can do through escalation instructions, rules, knowledge access, and tool integrations. *** ## 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:** Before escalating, check `@IT Knowledge Base` one more time for any relevant articles. If still unable to resolve, create a ticket with `@Form - General Support` and inform the user that a specialist will follow up within 24 hours. **Example with workflow:** When you cannot resolve a user's access request, trigger `@Workflow - Escalated Access Review` to route the request through the proper approval chain. Inform the user that their request requires manager approval and they'll be notified within 1 business day. ### 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. When a user asks about password resets, account lockouts, or login issues... **Reference resources with @ mentions** Use `@` to link to specific Ravenna resources. Check `@IT Knowledge Base` for relevant articles before responding. Create a ticket with `@Form - Password Reset` if action is needed. **Define expected outcomes** Tell the agent what success looks like. Inform the user that their request has been logged and provide the ticket number. **Keep instructions focused** Each rule should handle one scenario. Create multiple rules for different use cases rather than one complex rule. **Knowledge-first response** When a user asks a question, first check `@IT Knowledge Base` for relevant articles. If you find an article that answers the question, provide a summary and link to the article. If no articles are found, create a support ticket with `@Form - General Inquiry` and inform the user that their request has been logged. **Password reset handling** When a user requests a password reset or reports being locked out of their account, create a ticket with `@Form - Password Reset`. Confirm to the user that their request has been submitted and that IT will process it shortly. **Software access requests** When a user requests access to software or applications, ask them to specify which application they need and their business justification. Then create a ticket with `@Form - Software Access Request` including the details they provided. **Workflow automation** When a user requests software access, ask which application they need and their business justification. Then trigger `@Workflow - Software Access Request` with the details provided. The workflow will handle provisioning and approvals automatically. **Hardware issues** When a user reports hardware problems (laptop, monitor, keyboard, mouse), first ask clarifying questions about the issue. Then create a ticket with `@Form - Hardware Support` and let them know an IT technician will follow up. **Multi-step process** When a new employee starts, trigger `@Workflow - Employee Onboarding` to automatically provision their accounts, assign equipment, and schedule orientation. Confirm with the manager that the onboarding process has begun. * 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+ When a user asks for their database credentials, look up the credentials in `@IT Credentials KB` and respond privately with the connection details. Never share credentials in the public channel. **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:** When a user requests approval on a ticket, use @Approve Ticket to mark the ticket as approved. Confirm to the user that the ticket has been approved and any automated workflows will proceed. **Example rule using Fleet device management tools:** When a user reports their device is slow or having performance issues, @Look up device with Fleet to get the device information, then @Run query with Fleet to check system diagnostics. Analyze the returned information and provide basic troubleshooting steps based on what you find. **Example rule using HubSpot CRM tools:** When a user asks about a customer's account status or deal information, @Search contacts with HubSpot to find the contact by email, then @List deals with HubSpot to retrieve their active deals. Summarize the account status and recent activity for the user. ### 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:** When a user requests that someone be added as an approver to a ticket, use @Add Approver to add the specified user as an approver. Confirm to the user that the approver has been added and will be notified. 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:** When a user who is an approver or workspace admin says they approve a ticket or request, use @Approve Ticket to mark the ticket as approved. Confirm to the user that the ticket has been approved and notify them that any automated workflows will proceed. 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:** When a user requests access to an application, first use @List Applications to find the application ID. Then use @List Access Levels with that application ID to determine available access levels. If the user specified an access level (like "Read Only" or "Admin"), match it to the available options. If only one access level exists, automatically use it. Create the access request ticket with the appropriate access level prefilled. 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:** When providing updates about a ticket, mention the ticket assignee using @Mention User so they're notified of the conversation. Include a summary of the update in your response. 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:** When a user submits a request that involves another person (like "my manager Sarah Chen" or "please add John to the project"), use @User Lookup to find the referenced user's Ravenna ID. Use this ID to populate any user selection fields in the form. 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:** When a user submits a request that involves a team or group (like "assign this to Team Falcon" or "the Engineering group needs access"), use @Group Lookup to find the group's ID. Use this ID to populate any user group selection fields in the form. 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:** When a user reports a hardware issue, use @Set Category to assign the "Hardware" category to the ticket. This ensures the ticket is routed to the correct team and triggers any hardware-specific workflows. Retrieves all available tags in the workspace. Returns tag names, IDs, and descriptions. Agents use this tool to discover valid tags before applying them to tickets. **Tool name:** `@List Tags` **Common use cases:** * Discover available tags before adding them to tickets * Validate tag names mentioned by users against the workspace tag list * Provide users with a list of available tags for categorization **Example rule:** When a user asks to tag a ticket, use @List Tags to find the matching tag. If the tag exists, apply it to the ticket. If no matching tag is found, let the user know and suggest similar available tags. Retrieves all available categories in the workspace. Returns category names, IDs, and descriptions. Agents use this tool to discover valid categories before assigning them. **Tool name:** `@List Categories` **Common use cases:** * Discover available categories before assigning one to a ticket * Validate category names mentioned by users * Help users understand the available categorization options **Example rule:** When a user asks about ticket categories or wants to categorize a ticket, use @List Categories to find available options. Present the relevant categories and use @Set Category to apply the user's choice. 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:** When a user asks to change a ticket's status, use @List Statuses to find the matching status. Update the ticket with the correct status and confirm the change to the user. 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:** When a user asks about their open tickets, use @List Tickets to search for tickets where the requestor is the current user and the status is open. Summarize the results and highlight any high-priority items. 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:** When a user asks about the status of a specific ticket, use @Get Ticket Info to retrieve the ticket details. Summarize the current status, assignee, and priority for the user. 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:** When a user asks what happened on a ticket or wants a summary of the discussion, use @Get Ticket Messages to retrieve the conversation history. Provide a concise summary of the key points and any actions taken. 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:** When a user asks where to submit a request or wants to know what channels are available, use @List Channels to retrieve the workspace channels. Help them identify the most appropriate channel for their request. 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:** When a user asks about a specific channel, use @Get Channel Info to retrieve the channel details. Share the channel name, prefix, and purpose with the user. 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:** When a user requests a new channel for their team, use @Create Channel to create it with the specified name and an appropriate emoji. Confirm the channel was created and share its details. 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:** When a user asks to rename a channel or change its emoji, use @List Channels to find the channel ID, then use @Update Channel to apply the changes. Confirm the update to the user. 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:** When a user is unsure which form to use for their request, use @List Forms to retrieve the available forms. Recommend the most appropriate form based on the user's description of their issue. 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:** Before creating a ticket with a specific form, use @List Custom Fields to get the form's fields. Ask the user for any required fields that haven't been provided, then create the ticket with the correct field values. 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:** When a user asks to assign a ticket to someone, use @List Users to search for the person by name. Then use @Update Ticket to set the assignee. Confirm the assignment to the user. 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:** When reviewing ticket details that include a user ID for the assignee or requester, use @Get User By ID to retrieve their name and email. Include this information when summarizing the ticket for the user. 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:** When a user asks about company policies, benefits, or internal procedures, use @Search Knowledge Base to find relevant documentation. Summarize the key points and cite the source document. If no results are found, let the user know and offer to create a support ticket. ### 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. When a user requests to be added to a Google Group, use `@List Google Groups` to find the matching group, then use `@Add member to Google Group` to add them. Confirm to the user that an approval request has been sent and they will be notified once it clears. 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 ## Configuration model An agent's behavior is determined by four configuration layers that work together: 1. **Escalation instructions** set the fallback strategy. They define what the agent does when it cannot resolve a request. This is the safety net. 2. **Rules** define scenario-specific behavior. Each rule describes a trigger condition and an action, referencing Ravenna resources with `@` mentions. 3. **Knowledge** provides searchable content for answering questions. The agent retrieves from connected knowledge folders. 4. **Tools** extend capabilities with actions from built-in Ravenna features and third-party integrations. Processing order: when a user sends a message, the agent evaluates rules to find the best match, checks connected knowledge for relevant content, and executes tool calls as needed. If it cannot resolve the request, it falls back to escalation instructions. *** ## Resource access model Agents operate on an explicit-access model. They do not have automatic access to all workspace resources. Access is granted through two mechanisms: * **`@` mentions in rules or escalation instructions** grant access to forms, workflows, tools, knowledge bases, and categories. If a form is not referenced in any rule, the agent cannot use it. * **Knowledge configuration** grants access to specific knowledge folders via the agent's settings. This means: * A form must be `@`-mentioned in at least one rule for the agent to create tickets of that type. * A workflow must be `@`-mentioned in at least one rule for the agent to trigger it. * Tools are referenced with `@` in rules to specify when they should be used. * Knowledge folders are selected in the agent's knowledge configuration. *** ## Rule-writing patterns ### Effective rule structure A well-written rule has three parts: 1. **Trigger condition** describes when the rule activates. Be specific about the scenarios, keywords, or request types. 2. **Action sequence** describes what the agent should do, referencing resources with `@` mentions. For multi-step processes, use numbered steps. 3. **Outcome definition** tells the agent what to communicate back to the user after completing the action. ### Multi-resource rules A single rule can reference multiple resources. Common combinations: * **Knowledge + form:** Check `@Knowledge Base` first. If the answer resolves the question, respond with it. If not, create a ticket with `@Form Name`. * **Tool + tool:** Use `@Look up device with Fleet` to get device info, then `@Run query with Fleet` to run diagnostics. Analyze results before responding. * **Form + workflow:** Collect information via `@Form Name`, then trigger `@Workflow Name` for backend processing. * **Application + access levels:** Use `@List Applications` to find the app, then `@List Access Levels` to determine available permission tiers before creating a request. ### Rule design recommendations * **One scenario per rule.** A rule that handles password resets, software access, and hardware issues is too broad. Split into three rules. * **Include fallback behavior.** Tell the agent what to do if the primary action fails or does not apply. For example: "If no matching article is found, create a support ticket." * **Specify user communication.** Tell the agent what to say to the user at each step: confirmation messages, expected timelines, next steps. * **Avoid overlapping triggers.** The agent selects only the single best matching rule per request. If two rules have similar triggers, the agent picks the most specific one. Distinct trigger conditions produce more predictable behavior. ### Channel awareness V3+ Each turn, the agent identifies which channel a message arrived on: a Slack channel, direct message, the Customer Portal, email, or an external ticketing integration such as Jira. This context is automatic and requires no rule configuration. When a workspace connects a published agent to its portal, that agent powers the portal chat: it answers from knowledge, creates tickets, and routes them to the right team. See the [requester portal](/documentation/platform/portal/requesters#chat-with-the-ai-agent). Channel awareness prevents **circular redirects**. If a rule or knowledge base article tells users to "post in `#it-help`" and the user is already messaging from `#it-help`, the agent recognizes the redirect points at their current location. Instead of echoing the instruction back, the agent reads the article as a script: it collects the inputs the human responder will need, then escalates the ticket. The full conversation becomes the handoff context for the assignee. For redirects to a **different** channel (for example, a user in `#general` who needs to post in `#it-help`), the agent relays the instruction verbatim so the user knows where to go next. The agent applies channel-aware self-reference handling when it can identify a specific end-user channel: * Slack channels (channel name known) * External ticketing integrations such as Jira, where the project or system is known Redirects from direct messages, the Customer Portal, email, and automated sources are always treated as legitimate cross-channel advice and relayed to the user. **Rule or KB article:** > For laptop replacements, post in `#it-help` with your asset tag, preferred model, and shipping address. **User messages from `#it-help`:** > My laptop screen is cracked, can I get a replacement? **Agent behavior:** Instead of repeating "post in `#it-help`," the agent asks for the asset tag, preferred model, and shipping address one item at a time, then publishes a ticket with the collected information for a human responder. When a ticket spans multiple channels (for example, a user opens a request in Slack and replies later by email), the agent treats follow-ups as continuations of the same ticket. It carries forward what the user already provided and does not redirect them back to the original channel. *** ## Escalation design Default escalation behavior (when no custom instructions are set): * Escalate only when knowledge and tools cannot resolve the request * Avoid excessive clarifying questions before escalating * Create a ticket and inform the user that a human agent will take over * Stop attempting to resolve the issue after escalation Custom escalation instructions override this default. They can: * Reference specific knowledge bases to check before escalating * Trigger specific workflows as part of the escalation process * Create tickets with specific forms when escalating * Define escalation criteria for specific request types * Name a specific person to assign the ticket to on handoff ### Assignment on escalation When the agent publishes a ticket for human handoff, Ravenna picks the new assignee in this order: 1. **A user named in your rule or escalation instructions.** If a rule says "after escalation, assign to @Jane," the agent passes that user as the assignee. Invalid or unknown user IDs are logged as warnings and ignored, then the agent falls through to the next step. 2. **The channel's first auto-assignee**, if one is configured. 3. **Unassigned**, ready for the team to pick up manually. The agent owner (the [Working on it](/documentation/tickets/roles#working-on-it-agent-owner) chip) is cleared automatically when the ticket publishes, so the human assignee always reflects the current owner. The agent does not mention who the ticket was assigned to in its handoff message to the requester. The user only sees confirmation that a human will follow up. **Example rule with a named assignee:** When a user asks for help with billing, collect the invoice number and any error message they're seeing, then escalate. After publishing the ticket, assign it to `@Jane Doe` so she can follow up with the requester. *** ## Tool selection guidance ### Built-in Ravenna tools | Tool | Purpose | When to use | | --------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | Create Ticket | Creates tickets with specified properties | Ticket creation from conversations, form-based requests | | Update Ticket | Modifies existing ticket properties | Adding context, changing priority, updating fields mid-conversation | | Add Approver | Adds approval requirement to a ticket | Setting up approval flows conversationally | | Approve Ticket | Approves a ticket on behalf of the requesting user | Conversational approvals (requires the user to be an approver or admin) | | List Applications | Retrieves available applications | Software access requests, application discovery | | List Access Levels | Retrieves permission tiers for an application | Populating access level fields, validating requested levels | | Mention User | Mentions a user with platform-correct formatting | Looping in team members, notifying specific users | | User Lookup | Searches for users by name or email | Resolving names to user IDs for form fields | | Group Lookup | Searches for user groups by name, description, and metadata | Resolving group names to IDs for user group selection fields, respecting workspace visibility and field constraints | | Web Search | Searches the web for current information | Questions not covered by the knowledge base | | Set Category | Assigns a category to the current ticket | Ticket triage, category-based routing and workflow triggers | | List Tags | Retrieves all available workspace tags | Discovering valid tags before applying them to tickets | | List Categories | Retrieves all available workspace categories | Discovering valid categories before assigning them | | List Statuses | Retrieves all available ticket statuses | Discovering valid statuses before updating tickets | | List Tickets | Searches and filters tickets by text and properties | Finding tickets by criteria, reporting, triage | | Get Ticket Info | Retrieves detailed information about a specific ticket | Looking up ticket status, details, and context | | Get Ticket Messages | Retrieves conversation history for a ticket | Reviewing discussion threads, summarizing ticket activity | | List Channels | Retrieves all channels in the workspace | Discovering channels, finding channel IDs for routing | | Get Channel Info | Retrieves details about a specific channel | Looking up channel configuration and metadata | | Create Channel | Creates a new channel in the workspace | Setting up channels for teams or projects | | Update Channel | Updates a channel's name or emoji | Renaming channels, updating channel icons | | List Forms | Retrieves all forms in the workspace | Finding the right form for a request | | List Custom Fields | Retrieves custom fields for a specific form | Discovering required fields before creating tickets | | List Users | Lists and searches workspace users | Finding user IDs for assignment, requester fields | | Get User By ID | Retrieves user details by ID | Resolving user IDs to names and emails | | Search Knowledge Base | Searches internal knowledge base documents | Answering questions about company policies and procedures | ### Tool chaining patterns Tools can be chained within a single rule to build multi-step flows: * **Application access request:** List Applications, then List Access Levels, then Create Ticket with pre-filled fields. * **Ticket creation with forms:** List Forms to find the form, List Custom Fields to get required fields, then Create Ticket with custom field values. * **Ticket investigation:** Get Ticket Info for details, then Get Ticket Messages for conversation history, then summarize findings. * **Ticket reassignment:** List Users to find the target user, then Update Ticket to set the assignee. * **Group-based requests:** Group Lookup to resolve a team name (with form and field context for allowlist-aware results), then Create Ticket with the group ID in user group selection fields. * **Knowledge-first resolution:** Search Knowledge Base for answers. If no results, create a support ticket. * **Device troubleshooting:** Look up device with Fleet, then Run query with Fleet, then analyze and respond. * **CRM lookup:** Search contacts with HubSpot, then List deals with HubSpot, then summarize findings. ### User Lookup behavior * Fuzzy matches against first name, last name, and email. * Not needed when the user is `@`-mentioned in Slack, because Slack metadata already includes the Ravenna user ID. * Required when a user is referenced by name only (e.g., "my manager Sarah Chen"). ### Group Lookup behavior * Searches across group name, description, email, and other metadata fields from integrations. Each word in the query must match somewhere across the group's searchable fields. * Scoped to the current workspace. Only groups that are visible in the workspace appear in results. * When the agent calls Group Lookup for a form field, it passes the form ID and field ID so results automatically respect any [allowlist or source constraints](/documentation/platform/groups) configured on the field. * When exactly one group matches, the agent uses the group ID to prefill the user group selection field. * When multiple groups match, the agent presents the options and asks the user to choose. * When no groups match, the agent asks the user to try a different search term. *** ## Tool execution policies Tools referenced in a rule can be wrapped in an **execution policy** that defines what happens before the tool runs in that rule's context. Policies are stored on the rule (under `definition.toolExecutionPolicies`, keyed by tool key), so the same tool can have different gating behavior in different rules. ### Modes | Mode | Runtime behavior | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Auto-execute | The tool runs as soon as the LLM emits a call. | | Requires confirmation | The agent posts a description of the pending action to the requester and waits for an in-conversation confirmation before executing. No approval round is created. | | Requires approval | The agent buffers the call instead of running it. After the LLM loop completes, all buffered calls are partitioned by approver set and a parallel approval round is opened for each partition. The agent only re-runs and executes the buffered calls once every round clears. | ### Defaults * Read-classified tools default to **Auto-execute**. * Write- and delete-classified tools default to **Requires confirmation**. Admins can override either default per rule. ### Approver selection When **Requires approval** is set, approvers are sourced from one of two places: * **Workspace admins (default).** No approval template is attached. Any workspace admin can approve. * **An [approval template](/documentation/tickets/approvals/templates).** The template's rounds, policies (any-of / all-of), user lists, group lists, and role-based approvers (for example, the requester's manager) are used to create the approval round. ### Batch approval gate The approval gate is plan-level, not call-level. When the LLM produces a plan that contains multiple approval-gated tool calls, those calls are accumulated in a tool execution buffer. After the loop ends, a single batch gate fires: calls are grouped by `approvalTemplateId`, and one parallel approval round is created per group. The agent re-triggers and replays the buffered inputs only when every round has cleared. This collapses what would otherwise be several sequential approval cycles into a single parallel one. ### Confirmation vs approval * **Confirmation** is an in-conversation prompt to the requester. Use it as a soft guardrail when the requester is also the person authorized to take the action. * **Approval** opens a formal approval round with separate approvers. Use it when someone other than the requester must authorize the action. The two modes are mutually exclusive on a given tool within a given rule. *** ## Workspace vs agent-level rules | Aspect | Workspace-level | Agent-specific | | -------- | ----------------------------------------------------- | -------------------------------------------------------- | | Scope | Shared across multiple agents | Single agent only | | Editing | Centralized. Changes propagate to all attached agents | Edited per agent | | Best for | Common scenarios (password resets, software access) | Agent-specific behavior for a particular channel or team | A workspace-level rule cannot be deleted while it is attached to any agent. Remove it from all agents first. ### Duplicating vs attaching * **Attach** a workspace-level rule when multiple agents should share identical behavior. Edits propagate to all agents using that rule. * **Duplicate** a rule when you need an independent variation. The copy can be modified without affecting the original, and changes to the original do not propagate to the copy. *** ## Constraints * **Form access requires rule reference.** The agent cannot use a form unless it is `@`-mentioned in at least one rule. * **Only Published forms are surfaced.** Draft and Archived forms are filtered out at runtime, even if they are `@`-mentioned in a rule. The agent treats them as unavailable and continues with other rules or escalates. Publish the form to make it usable. * **Workflow access requires rule reference.** The agent cannot trigger a workflow unless it is `@`-mentioned in at least one rule. * **Tool availability depends on integrations.** Integration tools require the corresponding integration to be installed and connected. Disconnected integrations make their tools unavailable. * **Explicit tool opt-in bypasses context-presence gates.** Tools attached to the agent or `@`-mentioned in a matched rule are surfaced even when supporting context (forms, categories, workflows) is empty. Knowledge lookup is the exception — it remains scoped to attached knowledge folders or `@`-mentioned knowledge resources. See [Tool availability and explicit opt-in](#tool-availability-and-explicit-opt-in). * **Single rule selection.** The agent selects only the single best matching rule per request, preferring the most specific match. Predictability improves when rules have distinct, non-overlapping trigger conditions. * **Knowledge is scoped to connected folders.** The agent cannot search knowledge folders that are not explicitly connected to it. * **Workspace-level rule deletion is blocked** while the rule is attached to any agent.