Skip to main content
Define what your agent can do through rules, escalation instructions, knowledge access, and tool integrations.

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

​
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

​
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

​
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