Skip to main content
Agents have been released to all organizations, replacing the previous Ravenna AI system. This guide explains what’s changed and how to migrate your existing setup.

​
What changed

A dedicated Agents tab now appears in the left sidebar for workspace configuration, making it easier to manage all your AI agents in one place.
Throughout the platform, “Request types” have been renamed to Forms. This better reflects their purpose as structured intake forms for capturing ticket information.
Categories now apply to all tickets as a top-level classification system, accessible via workspace settings. Previously, categorization was handled via Request Types. We’ve separated this functionality now so that Forms & Categories are distinct.

​
Backward compatibility

Your existing Ravenna AI settings will remain active until you replace them with an agent. This allows you to migrate seamlessly without disrupting current operations.
Newly created channels cannot use the legacy Ravenna AI system. You must configure an agent for any new channels.

​
Understanding the differences

​
Legacy Ravenna AI

The previous Ravenna AI system operated with limited configuration spread across channel and knowledge settings. The AI would:
  • Automatically infer how to respond based on channel context
  • Select forms based on implicit patterns in user requests
  • Pull answers directly from knowledge bases without explicit routing rules
  • Provide minimal control over decision-making logic

​
New Agents

Agents introduce explicit control through rules-based configuration:

Rules-based behavior

Define exactly when and how your agent should respond to specific scenarios using natural language rules

Explicit resource access

Use @ mentions to grant agents access to specific forms, knowledge bases, and tools

Customizable personality

Configure tone, response length, emoji usage, and communication style

Advanced capabilities

Access to escalation instructions, tool integrations, and fine-grained channel behavior controls

​
Migration steps

Review current Ravenna AI configuration

Before migrating, review and understand your existing Ravenna AI setup:
  • Which channels have AI enabled
  • What knowledge bases are connected
  • Which forms are available for automatic selection
  • Any custom personality or tone settings

Create an agent

Navigate to the Agents tab in your workspace settings and create a new agent. Start with basic settings and gradually add complexity.

Configure agent rules

Agents require explicit rules to know which forms to use. For each form you want the agent to access:
  1. Create a new rule in the agent’s configuration
  2. Describe when this form should be used
  3. Use @Form Name to reference the specific form
  4. Add any context-specific instructions
Example rule for a password reset form:
When a user requests a password reset or reports being locked out,
use @Form - Password Reset to create a ticket. Inform the user
that IT will process their request within 2 hours.

Connect knowledge bases

Select which knowledge folders your agent should access. Unlike Ravenna AI, agents only have access to knowledge you explicitly grant.You can also reference specific knowledge bases in rules using @Knowledge Base Name for targeted retrieval.

Assign agent to channels

Go to each channel’s settings and associate your agent. Remember that each channel can only have one agent assigned.

Test and refine

Send test messages to your channels to verify:
  • Agent responds appropriately to different request types
  • Correct forms are selected and populated
  • Knowledge retrieval returns relevant information
  • Escalation behavior works as expected
Iterate on your rules based on test results.

​
Key considerations

​
Explicit context requirements

Agents do not automatically have access to all resources in your workspace. You must explicitly grant access to:
  • Forms via @ mentions in rules
  • Knowledge bases via the knowledge configuration
  • Categories for ticket classification
  • Tools and integrations via @ mentions in Rules

​
Rules are powerful

The rules system allows you to define sophisticated behavior patterns. Each rule can:
  • Reference multiple resources using @ mentions
  • Include conditional logic using natural language
  • Specify exact workflows for different scenarios
  • Define escalation criteria and processes
For detailed guidance on writing effective rules, see the agents documentation.

​
Getting help

If you need assistance with your migration: