Skip to main content
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 tools
  • 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

1

Navigate to agent settings

Open your agent’s settings page.
2

Find escalation instructions

Locate the Escalation Instructions section under Capabilities.
3

Add or edit instructions

Click Add (or Edit if instructions already exist).
4

Write custom guidelines

Write your escalation guidelines using natural language and @ mentions.
5

Save changes

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
  • Forms: Create tickets with specific forms when escalating
  • Categories, tags, and statuses: Classify or update the ticket so downstream workflows can pick it up
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 form and category (hands off to a workflow via ticket state):

When you cannot resolve a user's access request, create a ticket with @Form - Escalated Access Review and set @Category - Access Review. 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 forms, categories, or knowledge bases

​
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 and .

​
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

Best practices

Be specific about triggersClearly define when the rule should activate.

When a user asks about password resets, account lockouts, or login issues...

Reference resources with @ mentionsUse @ 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 outcomesTell the agent what success looks like.

Inform the user that their request has been logged and provide the ticket number.

Keep instructions focusedEach 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.

Hand off to a workflow via a form

When a user requests software access, ask which application they need and their business justification. Then create a ticket with @Form - Software Access Request including the details they provided. A workflow triggered by the form submission 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, create a ticket with @Form - Employee Onboarding capturing the new hire's details. A workflow triggered by the form submission will 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
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 accessYou 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.Rule selectionThe 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.
1

Access rules tab

Navigate to Agents in your workspace and click the Rules tab.
2

Create new rule

Click New Rule and enter a descriptive title.
3

Write instruction

Write the instruction using natural language and @ mentions to reference forms, knowledge folders, and tools.
4

Save rule

Click Save to create the rule.
Workspace-level vs agent-specific rules
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 agentsAttach 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 rulesCreate 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 ruleTo 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 viewThe 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.
1

Open the View menu

On the Rules tab, click the View button above the rules table.
2

Toggle columns

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 rulesDelete 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.
1

Select rules

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.
2

Open bulk actions

Click the Delete button that appears in the bulk actions bar above the table.
3

Confirm

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

​
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 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) 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.

Create Ticket

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 LevelsInput: Requires an application IDAutomatic 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 UserCommon 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 . 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 LookupSearch 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 LookupSearch 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 CategoryCommon 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 TagsCommon 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 CategoriesCommon 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 StatusesCommon 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 TicketsSearch 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 InfoSupported 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 MessagesCommon 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 ChannelsCommon 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 InfoCommon 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 ChannelCommon 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 ChannelCommon 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 FormsCommon 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 FieldsInput: Requires a form IDCommon 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 UsersCommon 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 IDCommon 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 BaseAccess 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:
Review the Integrations page 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: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 — 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 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
Last modified on July 27, 2026