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

# AI Assistant

> Chat with Ravenna's AI Assistant in Microsoft Teams via 1:1 chat with the bot or by @-mentioning it in a channel to get answers, create tickets, and resolve requests.

The Ravenna AI Assistant brings <Tooltip headline="Agents" tip="AI Agents with custom prompts and tool integrations that automate Teams support" cta="Learn about Agents" href="/documentation/automate/agents/overview">Agent</Tooltip>-powered support into Microsoft Teams. Post a message in a connected request channel to start a conversation with Ravenna, get instant answers, create tickets, and resolve requests without leaving Teams.

<Note>
  1:1 chats with the Ravenna bot are not yet supported in the Teams beta. DMs sent directly to the bot are ignored. Use a connected request channel instead. DM support is on the roadmap.
</Note>

<View title="Human" icon="user">
  ## Where you can chat with Ravenna

  <CardGroup cols={2}>
    <Card title="Connected request channels" icon="hash">
      Post a message in any channel that's connected to a Ravenna request channel. The Agent picks the message up automatically and replies in the thread.
    </Card>

    <Card title="Channel @-mentions" icon="at-sign">
      @-mention **@Ravenna** to summon the Agent explicitly. The bot mention is stripped before the message is processed so it doesn't appear in your ticket.
    </Card>
  </CardGroup>

  ***

  ## Set up the AI Assistant

  <Steps>
    <Step title="Connect Microsoft Teams">
      Complete the [Microsoft Teams setup](/integrations/microsoft-teams/setup) so the Ravenna bot is installed in your tenant.
    </Step>

    <Step title="Attach an Agent to a channel">
      Open the [Ravenna channel](/documentation/platform/channels) you want the Assistant to operate in and attach an [Agent](/documentation/automate/agents/overview). The Agent's prompt, tools, and knowledge configuration determine how Ravenna responds in Teams.
    </Step>

    <Step title="Connect a request channel">
      Connect the Teams channel where you want the Agent to be available by @-mentioning **@Ravenna** and completing the connect flow. See [Setup](/integrations/microsoft-teams/setup#connect-channels).
    </Step>
  </Steps>

  ***

  ## Conversation patterns

  <AccordionGroup>
    <Accordion title="Ask a question" icon="circle-help" defaultOpen>
      Send a message in a connected request channel. The Agent responds in the same thread using its configured knowledge.
    </Accordion>

    <Accordion title="Create a ticket from a chat" icon="ticket">
      If the Agent can't answer, it will offer to create a ticket. Confirm via the card action and the ticket is created and routed to the right Channel.
    </Accordion>

    <Accordion title="Attach files or screenshots" icon="paperclip">
      Drag and drop files into your message before sending. The Agent reads supported attachments (PDFs, images, text files) and uses their contents to answer or to prefill form fields when creating a ticket.
    </Accordion>

    <Accordion title="Working-on-it signal" icon="loader">
      While the Agent is composing a response, Ravenna posts a temporary "thinking" Adaptive Card so users know work is in progress. The card is replaced once the final response is sent.
    </Accordion>
  </AccordionGroup>
</View>

<View title="Agent" icon="bot">
  ## Mental model

  The Microsoft Teams AI Assistant is the same Ravenna Agents runtime used in the web portal, surfaced through the Bot Framework. Conversations in Teams are first-class chat conversations: a `ChatConversation` row backs the channel thread or 1:1 chat, and messages flow through the standard ticket lifecycle.

  Behavior in connected channels:

  * The first inbound message in a connected request channel creates a ticket and a `TicketMessage`. `MESSAGE_CREATED` triggers the Agent.
  * Subsequent messages in the same thread sync as additional `TicketMessage`s on the same ticket.
  * The Agent's response is rendered via the outbound pipeline (mention translation, Teams markdown conversion, authored-message wrapping for human authors, Adaptive Cards for forms).

  ***

  ## Conversation types

  | Conversation type             | Behavior                                                                                                                                                                            |
  | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `channel` (team channel)      | Primary entry point. Messages create tickets only in channels with a `ChatChannel` mapping. Unmapped channels surface the connect-flow card on @-mention and ignore other messages. |
  | `personal` (1:1 with the bot) | Not processed in the beta. Approval cards and similar outbound DMs still send, but inbound messages from the user are not routed to a ticket or the Agent.                          |
  | `groupChat`                   | Same as `personal`; not yet routed to tickets.                                                                                                                                      |

  ***

  ## Agent runtime hooks

  * `stampAgentForInboundChat(queue)` assigns the V3 Agent to the ticket on creation so the working-on-it signal and `AGENT_ASSIGN` event fire. Returns no-op for V2 / no-agent queues.
  * The ticket's `title` and `description` are intentionally left blank on creation so the AI title/description generator fills them in during `TICKET_PUBLISHED`. Pre-filling either short-circuits the generator.
  * Outbound `MESSAGE_CREATED` events route through `TeamsOutboundRenderer.formatMessage`, which dispatches by agent response type (form → Adaptive Card, text → converted Teams markdown).

  ***

  ## Constraints and gotchas

  * Auto-create on every message in a channel does **not** apply on Teams. Tickets are only created from channels with a `ChatChannel` mapping and a configured queue.
  * The Agent runs whether or not the bot was explicitly @-mentioned in the message, as long as the channel is connected. Bot mention tokens (`<at>Ravenna</at>`) are stripped from the message before processing.
  * Bot Framework cannot post on behalf of an arbitrary user, so human Ravenna users replying to Teams chats are surfaced via authored-message Adaptive Cards (avatar + name header) rather than impersonated. Avatar URLs occasionally fail to load if the user's Microsoft 365 photo isn't accessible to the bot.
  * 1:1 DMs to the Ravenna bot are dropped in the beta. A DM-initiated ticket flow and DM assistant classifier are on the roadmap.
  * DM and 1:1 conversations do not have a Teams deep-link format, so Ravenna omits the conversation link on tickets created from chats.
  * Conversational form-fill via the Agent is in development on Teams. The Agent may escalate without rendering the configured request-type form. Use the explicit form card flow described in [Forms](/integrations/microsoft-teams/forms) until this is finalized.
</View>