Skip to content

Latest commit

 

History

History
113 lines (91 loc) · 8.02 KB

plan.md

File metadata and controls

113 lines (91 loc) · 8.02 KB

Slack Agent → Open WebUI Bridge: Project Plan

1. Research findings

Slack "agent" model. A Slack agent follows a response loop: receive input → reason → call tools → render output [2]. You build it on the Bolt framework (Python or JS): enable the agent feature (grants assistant:write), subscribe to events (message.im, app_context_changed, agent_session_stopped, agent_session_title_changed), send a welcome message + suggested prompts on thread start, then on each message.im call agents.sessions.setStatus with "processing" to show the loading UX, do the work, post the reply with chat.postMessage, and finally set status "active" [2]. For long-running tasks Slack recommends posting/updating a message (optionally a plan block) rather than streaming, since a stream auto-finalizes after 10 minutes [2]. Processing sessions time out after 1 hour (re-send "processing" to reset the timer) [2]. Note: some AI features require a paid Slack plan; the Developer Program gives you a free fully-featured sandbox [2]. Conceptually, your agent is "goal-oriented" with Open WebUI as an execution tool it invokes [3].

Open WebUI side. Auth is a Bearer API key (Settings → Account) [4]. The flow you want — create a real chat, wait, read the answer — is documented as the "Backend-Controlled API Flow" [5]:

  1. POST /api/v1/chats/new — create the chat with the user message and an empty assistant placeholder in one payload. Message IDs are caller-generated UUIDs, and the tree must use childrenIds/parentId plus camelCase currentId in history, or the frontend won't render it [5].
  2. POST /api/chat/completions — pass chat_id, the assistant message id, the user_message object, messages, model, and stream: true. Omitting user_message or the placeholder are the two most common failures [5].
  3. Wait — consume the stream, or poll GET /api/v1/chats/{chatId} until the assistant message has content [5].
  4. GET /api/v1/chats/{chatId} — fetch the final completed chat [5].
  5. Multi-turn: POST /api/v1/chats/{chatId} to append the next user/assistant pair, then repeat step 2 with full history [5].

(There's also a Server-Side Tool Calling API guide that covers tool execution with and without saving the chat [1][4], but for your use case the chat-creation flow above is the right one — the chat will appear in the Open WebUI UI exactly like a normal conversation [5].)

2. Architecture

Slack user ⇄ DM/thread
      │  (WebSocket events)
      ▼
Bolt app (Python)
  - message.im handler → sets status "processing"
  - background job:
      1. map Slack thread_ts ⇄ Open WebUI chat_id (SQLite/Postgres)
      2. POST /api/v1/chats/new (or append if thread already mapped)
      3. POST /api/chat/completions, wait (stream or poll)
      4. GET /api/v1/chats/{id}
      5. chat.postMessage (thread_ts) + optional plan-block progress updates
  - sets status "active"
      ▼
Open WebUI instance (API key, chosen model, optional RAG collections)

3. Phased plan

Phase 0 — Prerequisites (½–1 day)

  • Slack workspace with paid plan, or join the Developer Program sandbox [2]
  • Create Slack app, enable agent feature, add scopes (assistant:write etc.) and event subscriptions listed above [2]
  • Running Open WebUI instance, API key generated, target model ID identified (GET /api/models) [4]
  • Decide auth model: one service-account API key (all chats appear under that user) vs. per-Slack-user API keys — this is a key design decision

Phase 1 — Open WebUI client library (1–2 days)

  • Wrap the 4 calls in a small Python client: create_chat(prompt), complete(chat_id, ...) (with user_message), wait_for_completion (stream recommended, polling fallback with backoff), append_turn, get_final_chat [5]
  • Handle the pitfalls explicitly: UUIDs generated by caller, childrenIds on every message, currentId camelCase, assistant placeholder in both messages[] and history.messages{}, user_message in the completions call [5]
  • Verify standalone with curl before wiring Slack [5]

Phase 2 — Slack agent skeleton (1 day)

  • Bolt app with thread_started → welcome message + setSuggestedPrompts [2]
  • message.im handler → immediately setStatus("processing") with loading messages (gives the loading indicator + stop button) [2]
  • Echo-test reply + setStatus("active") end-to-end

Phase 3 — Wire the loop together (1–2 days)

  • On message.im: look up thread_ts in the mapping DB. If new → create Open WebUI chat; if existing → append turn (Phase 4 item)
  • Run the completion in a background task (don't block the event handler); post a "working on it" message with a plan block, update it as steps finish [2]
  • On completion: chat.postMessage into thread_ts with the answer; set status "active" [2]
  • Truncate long answers (Slack message limit) and append a link to the Open WebUI chat so users can see the full conversation
  • Error paths: post a friendly error, still set "active"

Phase 4 — Multi-turn follow-ups (1 day)

  • Append new user/assistant message pair via POST /api/v1/chats/{chatId} and re-trigger completion with full message history, so Slack threads map 1:1 to Open WebUI chats [5]
  • Optional: agents.sessions.rename for thread titles; listen to agent_session_title_changed to stay in sync [2]

Phase 5 — UX polish (1–2 days)

  • Feedback buttons block (context_actions / feedback_buttons) on responses [2]
  • Use app_context in message.im to tailor behavior when invoked from a channel context [2]
  • Handle the stop button (agent_session_stopped subscription) [2]

Phase 6 — Hardening (1–2 days)

  • Timeouts (model can hang): max wait, then post partial/error; remember 1-hour processing timeout and 10-min stream cap [2]
  • Retries with backoff for 429/provider errors (Open WebUI passes Retry-After through) [4]
  • Rate-limit Slack chat.update calls for progress updates [2]
  • Logging, secrets management, API key never on the frontend

Phase 7 — Test & ship (1 day)

  • Test matrix: first message, follow-up, long answer, timeout, model error, concurrent users
  • Distribute internally (or Marketplace if generalizable) [3]

4. Sketch of the core handler

assistant = Assistant()

@assistant.user_me
def respond(say, setStatus, get_thread_context, ...):
    setStatus(status="processing", loading_messages=["Asking Open WebUI…"])
    thread_ts, channel, text = payload["thread_ts"], payload["channel"], payload["text"]
    run_job.defer(handle_turn, channel, thread_ts, text)  # background, don't block

def handle_turn(channel, thread_ts, text):
    chat_id = db.get_chat_for_thread(thread_ts)
    try:
        if chat_id is None:
            chat_id = owui.create_chat(text)          # POST /api/v1/chats/new
            db.set(thread_ts, chat_id)
        else:
            chat_id = owui.append_turn(chat_id, text) # POST /api/v1/chats/{id}
        answer = owui.wait_for_completion(chat_id)    # stream or poll
        client.chat.postMessage(channel=channel, thread_ts=thread_ts,
                                text=truncate(answer, 3500))
        client.agents.sessions.setStatus(channel_id=channel,
                                         thread_ts=thread_ts, status="active")
    except Exception as e:
        client.chat.postMessage(channel=channel, thread_ts=thread_ts,
                                text=f":warning: {e}")
        client.agents.sessions.setStatus(channel_id=channel,
                                         thread_ts=thread_ts, status="active")

Total estimate: ~7–10 working days to a hardened internal release. The riskiest parts are the Open WebUI message-tree format (Phase 1 — validate with curl early, per the docs' own testing advice [5]) and Slack's agent session lifecycle rules (status must be explicitly set to "active", or the session sits in processing until the 1-hour timeout) [2].

Want me to expand any phase into a more detailed task list, or draft the full Phase 1 Open WebUI client code?