> ## 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
> Deploy custom AI agents to Slack channels and triage flows to answer questions, classify tickets, and resolve common requests automatically.
Agents have been released to all organizations. For details about the rollout and migration from Ravenna AI, see the [release notes](/documentation/automate/agents/release-notes).
Deploy custom AI agents into your channels to automate support requests, answer questions, and route tickets. Configure agents using natural language prompts to define behavior, integrate with external tools, and access your knowledge base. Agents handle instant responses, intelligent ticket routing, and workflow automation across Slack, email, and integrated systems.
## What agents can do
Use your knowledge base to respond to questions with accurate, sourced answers
Create tickets with specific forms, collecting structured information from users
Hand off to multi-step workflows for provisioning, approvals, and backend processing
Run actions through integrated tools like Fleet, HubSpot, Okta, and Jamf
Route tickets to the right team and escalate complex requests to human agents
Work in Slack, email, and integrated systems like Jira, Linear, and GitHub
Automatically send passwords, API keys, and credentials as private DMs instead of in shared channels V3+
Detect where each message arrived from and avoid telling users to post in a channel they're already in V3+
## How agents learn
Define agent behavior through natural language rules, connect knowledge folders for accurate answers, configure escalation instructions for handling complex requests, and integrate external tools for specialized actions.
***
## Agents vs workflows
Agents and workflows both automate work, but they fit different situations.
| | Agents | Workflows |
| ---------------------- | ------------------------------- | -------------------------------------- |
| **How they run** | Conversational, real-time | Background automation |
| **What starts them** | User messages | Events, schedules, or manual triggers |
| **How you build them** | Natural language rules | Visual builder with steps and branches |
| **User interaction** | Interactive dialogue with users | No interaction during execution |
### Using both together
Agents and workflows work well in combination. A common pattern is to let the agent handle the conversation — collecting information and answering questions — and then trigger a workflow for the backend processing, such as provisioning access, creating issues in external systems, or running multi-step approval flows.
Reference workflows in agent rules using `@Workflow Name` to connect the two. The agent collects what it needs from the user, then hands off to the workflow.
Learn more about [workflows](/documentation/automate/workflows/overview) and how to [reference workflows in agent rules](/documentation/automate/agents/configure#rules)
***
## Getting started
Follow the step-by-step guide to create, configure, and deploy an AI agent
Create agents from the **Agents** page in your workspace. Each agent requires rules that define its behavior, knowledge sources for answering questions, and channels for deployment.
## System overview
An agent is a conversational AI assistant deployed to one or more channels. It processes user messages in real time and responds using four capability layers:
1. **Rules** define behavior for specific scenarios using natural language instructions. Each rule tells the agent when to activate and what to do, referencing Ravenna resources with `@` mentions.
2. **Knowledge** provides the agent with searchable documentation. The agent retrieves relevant articles to answer questions with sourced responses.
3. **Escalation instructions** define fallback behavior when the agent cannot resolve a request. Without custom instructions, the agent follows default escalation logic.
4. **Tools** extend the agent with actions from built-in Ravenna capabilities and third-party integrations (Fleet, HubSpot, Jamf, etc.).
These layers compose together: a single conversation may involve checking knowledge, executing a tool action, filling a form via a rule, and escalating if the result is insufficient.
***
## Agents vs workflows
| | Agents | Workflows |
| -------------------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
| **Execution** | Conversational, real-time, synchronous | Background, asynchronous |
| **State** | Stateless single-turn responses within a conversation thread | Multi-step with wait states, approvals, delays |
| **Triggers** | User messages in connected channels | Events, schedules, agent handoff |
| **Branching** | Linear rule matching based on user intent | Conditional paths, parallel execution, converging branches |
| **External systems** | Tool calls within conversation | Native integration actions, HTTP requests |
**Use agents when you need:** conversational information gathering, interactive dialogue, real-time question answering, simple ticket creation, single-action tool calls.
**Use workflows when you need:** approval gates, parallel execution across systems, scheduled automation, wait states (for messages, approvals, inactivity), multi-step orchestration with error handling.
***
## Agent-workflow integration
Agents trigger workflows using the Agent Trigger. Reference a workflow in agent rules with `@Workflow Name`. The agent handles the conversation (collecting information, confirming intent) and hands off to a workflow for backend processing (provisioning, approvals, multi-step orchestration).
Key behaviors:
* If the workflow's Agent Trigger has a form, the agent pre-fills fields from conversation context and presents the form for user review before submission.
* Without a form, the agent shows a confirmation button so the user can approve before the workflow runs. To skip confirmation, add explicit auto-trigger language to the rule.
* The agent must have explicit access to the workflow, granted by the `@` reference in a rule.
For the full integration model, form behavior details, and recommended patterns, see the workflow documentation's agent-workflow integration section.
***
## Common patterns
**IT support agent:**
Rules for password resets, software access requests, and hardware issues. Each rule references a specific form via `@Form Name`. Knowledge folders provide self-service answers. Tools like Fleet or Jamf enable device lookups during conversation. Escalation instructions route unresolvable issues to human agents.
**HR support agent:**
Rules for benefits questions, time-off requests, and onboarding. Knowledge folders cover policy documents. Forms collect structured request data. Workflows handle multi-step processes like onboarding provisioning.
**Multi-tool lookup:**
A single rule can chain multiple tool calls. For example: use `@Look up device with Fleet` to get device info, then `@Run query with Fleet` to check diagnostics, then analyze results and provide troubleshooting steps. The agent executes tools sequentially within the conversation.
**Agent-to-workflow handoff:**
The agent collects information conversationally (application name, business justification, manager name), then triggers `@Workflow - Software Access Request`. The workflow handles approval routing, provisioning, and notification steps that require background execution.
***
## Constraints and gotchas
* **One agent per channel.** Each channel can have at most one agent assigned. The same agent can be deployed to multiple channels.
* **Explicit resource access.** Agents do not automatically have access to all forms, workflows, or tools. Resources must be granted via `@` mentions in rules or through the knowledge configuration.
* **Single rule selection.** The agent selects only the single best matching rule per request, preferring the most specific match over broader ones. Keep rules distinct for predictable behavior.
* **Knowledge scope.** The agent only searches knowledge folders explicitly connected to it. It cannot access knowledge from other agents or unconnected folders.
* **Tool availability.** Integration tools require the corresponding integration to be installed and connected. If an integration is disconnected, its tools become unavailable.
* **Channel behavior modes.** Slack response behavior (all messages, mentions only, requests only) is configured per agent and applies to all channels that agent is deployed to.