AgentWorks documentation

Bot Connector System

A platform-agnostic bot framework that allows users to interact with the agent system from messaging platforms (Slack, Discord, Telegram, WhatsApp) and the built-in web simulator. Users @mention the bot (or type in the simulator), the system starts a multi-agent session with the user's pre-configured MCP servers, skills, and tool search mode, and streams progress back to the thread.

Architecture Overview

Slack / Discord / Web Simulator / ...
        |
        v
  BotConnector interface (per-platform)
        |
        v
  BotConversationManager (platform-agnostic orchestrator)
        |
        +-> buildQueryRequest() (uses user-configured servers/skills from DB)
        +-> startSessionInternal() (reuses handleQuery)
        +-> BotEventFilter -> streams progress, plan approval, human feedback to thread
        +-> User responds to blocking events via text in thread

Key Components

BotConnector Interface

type BotConnector interface {
    NotificationConnector // embeds: Name(), IsEnabled(), SendNotification()

    SupportsThreads() bool // true for Slack, false for WhatsApp/Telegram/web_simulator
    StartListening(ctx context.Context) error
    StopListening()
    SendThreadMessage(ctx context.Context, threadID ThreadID, message string) (string, error)
    SendThreadMessageWithBlocks(ctx context.Context, threadID ThreadID, message string, blocks []MessageBlock) (string, error)
    UpdateMessage(ctx context.Context, threadID ThreadID, messageID string, newText string) error
    GetThreadHistory(ctx context.Context, threadID ThreadID) ([]ThreadMessage, error)
    SetMessageHandler(handler BotMessageHandler)
    SetInteractionHandler(handler BotInteractionHandler)
    GetFormatter() MessageFormatter
}

Each platform implements this interface. The WebSimulatorConnector stores messages in-memory for the frontend to poll.

Session Start (Direct — No Analysis)

When a user sends a message, the system starts a multi-agent session directly using the user's pre-configured capabilities. There is no intermediate analysis LLM step.

buildQueryRequest() constructs the session from the _global bot connector config stored in the DB:

• MCP Servers: from default_servers in the _global config
• Skills: from default_skills, falling back to all discovered skills
• Tool search mode: enabled automatically when >2 servers are configured
• Delegation mode: always "plan" (multi-agent chat)
• Workspace access: always enabled
• Provider/model: high tier from delegation_tier_config (DB → env → defaults)
• API keys: from provider_api_keys in the _global config
• User secrets: loaded from server-side encrypted storage

End-to-End Flows

Flow 1: Web Simulator

1. User types "list my google sheets" in simulator
2. HandleMessageSync():
   a) No active session → buildQueryRequest(query)
   b) Create bot_session (status: "running")
   c) Start multi-agent session in background
   d) Return: { type: "follow_up", thread_offset: N }
3. Frontend polls for messages, sees progress:
   "[Sub-agent] Planning task..."
   "**Plan ready for review:** ..."
4. User types "approve"
5. HandleMessageSync():
   a) Session running, awaitingUserInput = true, blockingEventType = "plan_approval"
   b) isPlanApprovalResponse("approve") → true
   c) Inject follow-up: "Approved. Execute the plan."
6. Plan executes, sub-agents run, progress streams to thread
7. Session completes: "Session completed."

Flow 2: Slack @mention

1. User @mentions bot in #general
2. HandleIncomingMessage() → startNewSessionDirect()
3. Posts "Starting session... (tag me to follow up in this thread)" to thread
4. buildQueryRequest() → startSessionInternal()
5. Events stream to thread via BotEventFilter
6. Blocking events (plan approval, human feedback) shown in thread
7. User @mentions bot in thread → follow-up injected
8. Session completes → removed from active sessions map
9. User @mentions bot again → starts a fresh session (with thread history for context)

@Mention Requirement

The bot only responds to @mentions — plain thread replies are ignored unless the session is in a blocking state (plan approval, human feedback). This prevents:

• Other users chatting in the thread from accidentally triggering the bot
• Duplicate message processing (Slack sends both a MessageEvent and AppMentionEvent for @mentions in threads)

handleSocketModeMessage skips messages containing the bot's <@BOT_ID> to avoid double-processing with handleAppMentionEvent. The IsMention flag on BotIncomingMessage controls whether handleExistingSession allows follow-up injection.

Follow-Up Architecture

Each user message (initial or follow-up) creates a new agent via handleQuery — the same pattern as the regular chat UI. Conversation history from the DB provides continuity between turns.

Follow-ups use buildQueryRequest(query) to construct the full config, ensuring identical settings (servers, skills, delegation mode, API keys, secrets) as the initial session. The SessionFollowUpFunc accepts the complete reqMap and sendFollowUpInternal simply marshals and forwards it to handleQuery.

Session Cleanup

When runSession completes (event filter signals done or context cancelled), the session is:

1. Marked as completed in DB
2. Removed from the in-memory m.sessions map

This ensures subsequent messages don't find a stale entry with a dead event filter. Instead, the next @mention triggers a DB lookup, finds the completed session, and starts a fresh session via startNewSessionDirect — which creates a new event filter that properly forwards responses to the thread.

Flow 3: Blocking Events (Generic)

All blocking events follow the same pattern:

Agent emits blocking event → BotEventFilter:
  1. Format event as thread message
  2. Set active.awaitingUserInput = true
  3. Set active.blockingEventType = event type

User responds in thread → HandleMessageSync / handleExistingSession:
  1. Check blockingEventType
  2. For plan_approval: translate "approve" → "Approved. Execute the plan."
  3. For human_feedback: forward user's text as follow-up
  4. buildQueryRequest(response) → sendFollowUpInternal(reqMap)
  5. Clear awaitingUserInput

SyncMessageResult (Web Simulator)

The HandleMessageSync method returns a synchronous result for the web simulator:

type SyncMessageResult struct {
    Type         string `json:"type"`                     // "conversation" or "follow_up"
    Response     string `json:"response,omitempty"`       // text reply (conversation only)
    ThreadID     string `json:"thread_id"`
    SessionID    string `json:"session_id,omitempty"`     // internal chat session ID
    BotSessionID string `json:"bot_session_id,omitempty"` // set when awaiting confirmation
    ThreadOffset int    `json:"thread_offset,omitempty"`  // message count for polling init
}

• follow_up: Session is running. Frontend polls /api/simulator/messages?thread_id=X&since_index=N for updates.

Event Filter

File: agent_go/cmd/server/services/bot_event_filter.go

The event filter subscribes to session events and forwards filtered updates to the thread. It also manages session lifecycle by tracking blocking events and delegations.

Events Handled

Sub-Agent Name Tracking

trackDelegationName() extracts the instruction from delegation_start events and stores a short name (first line, capped at 60 characters) keyed by correlation_id. This name is used later in unified_completion formatting to label sub-agent results instead of showing the full instruction text.

Session Lifecycle

The event filter tracks:

• Pending delegations: increment on delegation_start, decrement on delegation_end
• Blocking state: set on any blocking event, cleared when user responds
• Completion received: set when a main-level (HierarchyLevel 0) unified_completion, agent_end, or conversation_end arrives

The session is "done" when all three conditions are met: completion received, no pending delegations, and no blocking state. The sessionDone flag ensures the callback fires at most once. This triggers "Session completed." and DB status update.

Message Formatting

delegation_start:
  "**Starting:** Sub-agent (model-name)"

llm_generation_end (main agent only, level 0):
  "**Agent:** {full LLM text content}"

unified_completion — Main agent (HierarchyLevel 0):
  "**Result:**
   {full final_result}
   _N turns, Xs_"

unified_completion — Sub-agent (HierarchyLevel > 0):
  "**[{short name from trackDelegationName}]**
   {full final_result}
   _N turns, Xs_"

Note: Full response text is shown without truncation. Meta stats (turns/duration) are only shown when they have meaningful values.

Workspace Path → Shareable URL

The event filter automatically converts workspace file paths in outgoing messages to clickable shareable URLs. This works in two passes:

1. Markdown links: a relative report link is converted to https://app.example.com/file?path=<base64>&uid=default.
2. Bare paths: Chats/xxx/report.md is converted to a shareable link with the same file endpoint.

Matches paths starting with Chats/ or Downloads/ that contain at least one subfolder and a file extension.

Requires: PUBLIC_URL environment variable set to the app's public base URL. Without it, paths are left as-is.

Bot Session Status Flow

running ←→ awaiting_user_input → completed
  |                                   |
  +→ failed ←————————————————————————+

Bot Configuration (Global)

Files: frontend/src/components/settings/BotConfigModal.tsx, frontend/src/components/sidebar/HumanFeedbackConnectorsSection.tsx

Bot capabilities (MCP servers and skills) are configured globally via a standalone Bot Configuration modal, accessible from the sidebar's Human Feedback Connectors section. This configuration applies to all bot interfaces (Slack, Web Simulator, etc.), not just the simulator.

UI

• Sidebar: Top-level "Bot Configuration" card with a "Configure" button — separate from individual connector cards
• Modal: Reuses the same ServerSelectionDropdown and SkillSelectionDropdown components used in the chat input area
• Tier display: Read-only bar showing delegation tier models (fetched from DB config, falls back to LLM store)
• Save: Persists selected servers/skills to DB via POST /api/bot/simulate/config (default_servers, default_skills)

Data Flow

1. On open: fetches saved config from GET /api/bot/simulate/config, available servers from useMCPStore
2. User selects servers/skills using the standard dropdowns
3. On save: POST /api/bot/simulate/config with { default_servers, default_skills }
4. When any bot session starts, buildQueryRequest() uses default_servers/default_skills from the _global config
5. Tool search mode is auto-enabled when >2 servers are configured

Web Simulator

Files: agent_go/cmd/server/services/web_simulator_connector.go, bot_simulator_routes.go, frontend/src/components/settings/BotSimulatorModal.tsx

The web simulator provides a chat-like UI for testing the bot flow without a Slack workspace. It uses the global bot configuration for server/skill selection.

Architecture

• WebSimulatorConnector implements BotConnector with in-memory thread storage
• Messages stored per-thread in []SimulatorMessage
• Frontend polls /api/simulator/messages for new messages using a setTimeout chain (not setInterval) to prevent overlapping polls when API calls are slow
• Message ID deduplication in the frontend prevents duplicate messages from race conditions
• threadOffsetRef tracks where polling starts to avoid re-fetching

REST API

Delegation Tier Config Sync

On modal open, the frontend syncs its delegationTierConfig (from useLLMStore) to the DB via PUT /api/bot/connectors/_global. This includes:

• delegation_tier_config: high/medium/low tier provider/model
• provider_api_keys: API keys per provider

The agent session uses the high tier as the main provider.

Session Configuration

Query Request Building

buildQueryRequest() constructs the session config from the _global bot connector config:

User Secrets

Bot sessions load server-side stored secrets via UserSecretsLoaderFunc. These are encrypted in the DB and decrypted at session start, injected as decrypted_secrets in the query request.

Text-Based Response Detection

Plan Approval Responses

// Approve: approve, approved, execute, go, yes, y, ok, proceed, do it, run it, start, lgtm
// Reject: reject, rejected, no, n, cancel, stop, nope, nah, abort
// Other text: forwarded as feedback to the agent

Session End Commands (thread-less platforms)

// End: done, end, stop, reset, new session, quit, exit

Database Schema

Migration: pkg/database/migrations/019_add_bot_connector_tables.sql

bot_connector_config

bot_sessions

bot_messages

Import Cycle Avoidance

The services package cannot import internal/events. Solved with:

1. BotEventSubscriber interface (agent_go/cmd/server/services/bot_connector.go): abstracts SubscribeBot(sessionID) -> (chan, unsubscribe)
2. BotEventSubscriberAdapter (bot_event_adapter.go): bridges EventStore to BotEventSubscriber
3. SessionStartFunc: callback for starting new agent sessions
4. SessionFollowUpFunc: callback for injecting follow-ups — accepts full reqMap map[string]interface{} (built by buildQueryRequest()) so follow-ups get identical config (servers, skills, delegation mode, API keys, secrets) as initial sessions
5. UserSecretsLoaderFunc: callback for loading decrypted user secrets

All wired in server.go during startup.

Adding a New Platform

1. Create services/{platform}_connector.go implementing BotConnector
2. Implement MessageFormatter for the platform's markup
3. Register in server.go:

   botManager.RegisterConnector(platformService)
   

4. Add bot_connector_config row for the platform

The BotConversationManager handles session management, event filtering, and blocking event routing identically across all platforms.

Access Control

allowed_emails

The _global bot connector config supports an allowed_emails array. When set, only users whose email matches (case-insensitive) can use the bot. Rejected users receive a message: "Sorry, you don't have access to use this bot. Please contact your administrator to get access."

Email resolution is platform-specific (e.g., Slack's users.info API via resolveUserEmail).