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

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
  • 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 , , 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.

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
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.Workflow accessYou must reference workflows within rules for the agent to trigger them. Your agent does not have access to all workflows by default.Rule conflictsIf multiple rules could apply to a request, the agent uses its judgment to select the most appropriate one. Keep rules distinct to avoid ambiguity.

​
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, workflows, and tools.
4

Save rule

Click Save to create the rule.
Workspace-level vs agent-specific rules
AspectWorkspace-level rulesAgent-specific rules
LocationRules tab on Agents pageIndividual agent’s Capabilities section
ReusabilityCan be attached to multiple agentsOnly available to that specific agent
ManagementCentralized editing with changes applied everywhereEdited per agent
Best forCommon scenarios shared across teamsAgent-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.

​
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. 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, 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 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:
  • Fuzzy matches against first name, last name, and email address
  • 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.

​
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

​
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