> ## 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. ## 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, tools, knowledge bases, categories, tags, and statuses. 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. * Tools are referenced with `@` in rules to specify when they should be used. * Knowledge folders are selected in the agent's knowledge configuration. Agents cannot trigger workflows. Hand off to a workflow through ticket state instead — for example, submit a form, set a category, or change a tag or status, and configure a workflow to fire on that ticket event. *** ## 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 handoff:** Collect information via `@Form Name` and submit it on the ticket. A workflow triggered by that form submission handles the 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 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 [Portal](/documentation/platform/portal#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 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 * Create tickets with specific forms when escalating * Set a category, tag, or status so a downstream workflow can pick up the ticket * 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. * **Agents cannot trigger workflows.** Hand off through ticket state (form submitted, category assigned, tags changed, status changed) and let a workflow fire on that event. * **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) 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.