Aura Bot

Aura Bot is the AuraBoot AI agent embedded in instant messaging channels. It runs in DMs, responds to @AI mentions in group chats, and supports the same streaming chat pipeline used by the web Copilot panel. Behind the scenes, every Aura Bot turn is a ConversationTurnService execution, so it inherits the same persistence, audit, and approval behavior as every other agent surface.

Concept

Aura Bot is not a separate AI runtime. It is a delivery surface for the shared agent runtime. The distinction matters: a message routed to Aura Bot is indistinguishable from a Copilot or ACP turn at the runtime level. Only the ResponseSink differs.

When To Use

• Users prefer to stay inside their IM client and not open the admin web.
• Teams want a shared, transcripted record of agent interactions in a channel.
• Operations want to be paged or queried about records from chat (e.g. "what's the status of order X").
• Group reply rules dispatch an agent on classification events.

Aura Bot is not the right surface for long-running batch agent work; that belongs to ACP.

Architecture

IM channel (DM or group)
        |
        v
+--------------------+      +---------------------------+
| Bot inbound adapter|----->| ConversationTurnService   |
| (DM | @mention |   |      |   runTurn / resumeTurn    |
|  group rule)       |      +-------------+-------------+
+--------------------+                    |
                                          v
                              +-----------+-----------+
                              |  Agent Runtime         |
                              |  - tool selection      |
                              |  - LLM call            |
                              |  - command pipeline    |
                              +-----------+-----------+
                                          |
                          +---------------v---------------+
                          |   BroadcastResponseSink       |
                          |   - chunked streaming         |
                          |   - final message persisted   |
                          +---------------+---------------+
                                          |
                                   IM channel reply

The inbound adapter normalizes the IM payload (sender, channel, thread, mention list) into the same input envelope used by web chat. From that point onward, there is one code path.

Chokepoint Rule

All conversational turns must go through ConversationTurnService.runTurn (or resumeTurn for resuming a paused approval). Do not write directly to the IM channel from inside a chat implementation; do not hand-craft SSE or WebSocket frames; do not persist messages outside the turn service. See the conversation turn chokepoint discipline for details.

A turn produces:

• A persisted user message and assistant message
• A trace span with prompt, tool calls, latency, cost
• Optional event publication for downstream listeners
• One or more streamed chunks to the chosen sink

Example: Group @AI Handler

@Component
public class GroupMentionHandler {

    private final ConversationTurnService turns;

    public void onMention(GroupMessageEvent event) {
        // TurnRequest is a record; construct it with positional args (no builder).
        TurnRequest req = new TurnRequest(
            event.tenantId(),
            event.senderUserId(),
            /*humanMemberId=*/ null,
            "im_group",                          // channel
            "aura-bot",                          // agentCode
            event.conversationId(),
            /*clientMsgId=*/ null,
            event.cleanedText(),                 // userMessage
            /*pageContext=*/ null,
            /*options=*/ null,
            InboundMode.EXISTING_MESSAGE_ID,     // the group message is already persisted
            /*precomputedBucket=*/ null,
            event.messageId(),                   // inboundMessageId
            /*parentTaskPid=*/ null,
            /*overrides=*/ null,
            /*legacyRequest=*/ null);

        ResponseSink sink = new BroadcastResponseSink(/* broadcaster, members, ... */);
        turns.runTurn(req, sink);
    }
}

A reply that needs approval (for example, "delete this customer") suspends the turn. When the approver confirms, the resume callback invokes turns.resumeTurn(pendingTurnId, decision, sink), and the same sink streams the continuation.

Permissions

Aura Bot runs as the IM user, not as a service account. The standard permission model applies:

• The user must have <module>.<resource>.<action> for every tool the agent calls.
• Tools the user cannot run manually cannot be invoked through the bot.
• Group rule auto-replies still resolve to a concrete user identity, typically the channel owner or a configured bot operator.

Verify Checklist

• Inbound adapter calls runTurn, never persists or broadcasts directly.
• The resume path calls resumeTurn, not a new runTurn.
• BroadcastResponseSink is used for IM, not SseResponseSink.
• Tool calls inherit the IM user's permissions.
• Trace spans are visible in the AI trace viewer for IM-originated turns.

Related

• AI Overview
• Agent System
• ACP Protocol
• MCP and Tools
• Permissions