Skip to main content

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.

Agents have been released to all organizations, replacing the legacy Ravenna AI system. Migrate to Agents to unlock new features including rules-based behavior, explicit resource access, and customizable personalities. Once you assign an agent to a , the legacy AI system for that channel automatically deactivates.

What changed

Agents replace legacy Ravenna AI with explicit rules-based configuration. Request Types renamed to Forms. Categories released as workspace-wide ticket classification.
Agents provide rules-based behavior control, explicit resource access via @ mentions, customizable personality, and advanced capabilities like escalation instructions and tool integrations.
Legacy Ravenna AI remains active on existing channels until you assign an agent. Once migrated, the legacy system for that channel deactivates. New channels must use Agents.

​
What’s new in this release

Agents

A dedicated Agents tab now appears in the left sidebar for workspace configuration. Configure AI assistants with rules-based behavior, explicit resource access, customizable personality, and tool integrations. Each can have one agent assigned.
Throughout the platform, “Request types” have been renamed to . This better reflects their purpose as structured intake forms for capturing ticket information with .
now apply to all tickets as a workspace-wide classification system, accessible via workspace settings. Previously, categorization was embedded within Request Types. This separation makes Forms and Categories distinct, independent systems for ticket organization.
Agents can now read files that users share in Slack as part of a conversation. The agent extracts text from PDFs, images, and other supported documents, and uses the contents to answer questions, prefill forms, and route tickets. The agent briefly defers its response while Slack finishes processing the upload so the file contents are available when it replies. See file handling in agents.
Tools referenced in a rule can now be gated with a per-rule execution policy: Auto-execute, Requires confirmation, or Requires approval. Approval-gated tools route through an approval template, or workspace admins by default, before the agent executes them. When the agent plans multiple gated calls in the same run, they open as a single batch of parallel approval rounds. Write and delete tools default to confirmation; read tools default to auto-execute. See tool execution policies.
Learn more about Forms and Categories

​
Backward compatibility

Your existing legacy Ravenna AI settings remain active on configured channels until you assign an agent to those channels. This allows seamless migration without disrupting current operations.
Newly created channels cannot use the legacy Ravenna AI system. You must configure an agent for any new channels.
Once you assign an agent to a channel, the legacy Ravenna AI system for that channel automatically deactivates and is removed from the channel settings.

​
Why migrate to Agents

Agents unlock new capabilities that legacy Ravenna AI cannot provide. Migrate to gain explicit control over AI behavior, resource access, and customization.

​
Legacy Ravenna AI

The legacy Ravenna AI system operated with limited configuration spread across and settings. The AI would:
  • Automatically infer how to respond based on channel context
  • Select 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

Explicit resource access

Use @ mentions to grant agents access to specific , , and

Customizable personality

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

Advanced capabilities

Access to , tool integrations, and fine-grained Slack behavior controls
Learn more about configuring agents and customizing agent behavior

​
Migration guide

Follow these steps to migrate from legacy Ravenna AI to Agents. Once you assign an agent to a , the legacy system for that channel automatically deactivates.
1

Review current configuration

Before migrating, review and understand your existing legacy Ravenna AI setup:
  • Which have AI enabled
  • What are connected
  • Which (previously Request Types) are available for automatic selection
  • Any custom personality or tone settings
2

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 as you understand the rules-based system.
You can create multiple agents with different configurations for different teams or use cases. Each channel can have one agent assigned.
3

Configure agent rules

Agents require explicit to know which 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 @Password Reset to create a ticket. Inform the user that IT will process their request within 2 hours.

Learn more about writing effective rules
4

Connect knowledge bases

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

Customize agent personality

Configure how your agent communicates through personality settings:
  • Response length (concise, balanced, verbose)
  • Tone (business, casual, humorous)
  • Emoji usage (none, minimal, moderate, high)
  • Custom prompts for specific communication styles
Learn more about customizing agents
6

Assign agent to channels

Navigate to the Connections section in your agent’s settings and select which should use this agent.
Once you assign an agent to a channel, the legacy Ravenna AI system for that channel automatically deactivates and is removed from the channel settings.
7

Test and refine

Send test messages to your channels to verify:
  • Agent responds appropriately to different request types
  • Correct are selected and populated
  • retrieval returns relevant information
  • behavior works as expected
Iterate on your based on test results. Review conversation logs to identify improvements.
Learn more about monitoring agent performance

​
After migration

Once you assign an agent to a , the legacy Ravenna AI system for that channel automatically deactivates and is removed from the channel settings. You cannot revert to the legacy system.

Legacy system removal

The legacy Ravenna AI configuration disappears from channel settings once an agent is assigned. All AI functionality for that channel now operates through the agent’s rules-based system.
You can create multiple agents with different configurations for different teams, use cases, or channels. Each channel can have one agent assigned, but agents can be deployed to multiple channels.
Monitor agent performance through conversation logs and feedback tracking. Continuously refine , , and based on actual usage patterns.

​
Important considerations

Explicit resource access

Agents do not automatically have access to all resources in your workspace. You must explicitly grant access to:
  • via @ mentions in
  • via the knowledge configuration
  • for ticket classification
  • and integrations via @ mentions in rules
The 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
Each can have one agent assigned, but you can create multiple agents for different teams or use cases. Deploy the same agent to multiple channels or use different agents for specialized teams.
Learn more about configuring agents, customizing agents, and monitoring performance

​
Getting help

If you need assistance with your migration: