Open WebUI

Open WebUI is a self-hosted chat front end for any OpenAI-compatible API. Add Console as an OpenAI connection and your published agents show up in its model picker next to your models. A person chats with an agent the same way they chat with a model, and the agent still uses its own tools, knowledge, guardrails, budgets and approvals.

When to use it: you want a ready-made chat UI for staff without building one, and the agents already live in Console. For a branded UI with identity mapping, use a portal instead.

Connect

You need three values: the base URL, an API token with the agents service, and a project that has at least one active agent.

export CONSOLE_URL="https://console.example.com"
export COGNIPEER_API_TOKEN="cpeer_..."

# Agents are listed as agent:<key>, owned_by "cognipeer-agent".
curl -s "$CONSOLE_URL/api/client/v1/models" \
  -H "Authorization: Bearer $COGNIPEER_API_TOKEN" \
  | jq -r '.data[] | select(.id | startswith("agent:")) | .id'

At start-up:

docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL="https://console.example.com/api/client/v1" \
  -e OPENAI_API_KEY="cpeer_..." \
  -v open-webui:/app/backend/data \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

Or in Open WebUI's own interface (the labels are Open WebUI's and change between releases; these are the ones of 0.12.x):

1. Open Settings. In 0.12.x it opens as a modal with a Connections tab; the same page is also in the Admin sidebar for connections shared by everyone.
2. Add a connection with the + button. In the dialog choose API Type: Chat Completions.
3. URL = https://console.example.com/api/client/v1. No trailing slash and no extra /v1.
4. API Key = the cpeer_ token.
5. Verify the connection, save, and reload.

A default connection to api.openai.com exists out of the box. Keep it if you also use OpenAI models through Open WebUI, or remove it so the model picker lists only Console.

The model list now contains your agents as agent:<key> (for example agent:support-bot) with the agent's name and description. Give the entry a friendlier name under Admin Panel → Settings → Models if you like. The list also contains the project's models; hide the ones you do not want in the picker.

Which token

The token decides which project's agents Open WebUI sees, and what they may do. Use a token of a dedicated service user, not a personal one. It sees only agents the token may read, because agents are listed only when the token has read access to the agents service.

What works

Open WebUI feature	What happens in Console
Chat	Each message becomes a turn of the agent on its published version. The agent's tools, knowledge and guardrails run as configured.
Streaming	Answers stream token by token. The first chunk carries delta.role: "assistant", and a keep-alive comment every 15 s keeps proxies from closing a slow turn.
Stop button	Open WebUI closes the connection. Console treats that as a stop: the run is cancelled at its next checkpoint and the partial answer is discarded. Nothing keeps running (or spending) behind the scenes.
Conversation continuity	See below. Follow-up messages continue the same Console session.
Images and files	Image attachments and files travel as image_url and file content parts and become session files of the agent. See below.
Usage and tracing	Every turn is a recorded run (channel: chat_completions) and appears in Sessions and Tracing like any other.
Regenerate, edit a message	Open WebUI resends an earlier conversation. Because it no longer matches the stored transcript, it starts a new session. That is the expected behaviour of the transcript match, not an error.

Session continuity

Open WebUI resends the whole conversation with every message, and the OpenAI protocol has no session id. Console resolves the Console session like this, in order:

1. conversation_id in the body, if the client sends one.
2. The X-Cognipeer-Session-Id request header, if the client sends one.
3. Transcript match: after every turn Console stores a hash of the conversation (all non-system messages plus the agent's answer) on the session. When the next request's earlier messages hash to a stored value, the request continues that session. The match is scoped to the same agent, project and user, so two people with identical histories never share a session.
4. Otherwise, a new session.

Every response carries X-Cognipeer-Session-Id (and a conversation_id field in the body; on a stream, in the first and the last chunk), so a client that can keep the id should send it back. Open WebUI does not need to: the transcript match works with its default behaviour.

System prompts are ignored

Open WebUI lets you set a system prompt per model or per chat. An agent has its own instructions, so system and developer messages are ignored for agents, and so are temperature, top_p, max_tokens and tools. The response header X-Cognipeer-Ignored-Params lists what was dropped. Change the agent's prompt in Studio instead.

Images and files

Attachments need attachments enabled on the agent (Configure → Files, with a bucket). Without it the request is refused with 403 in the OpenAI error envelope, naming the problem.

• Pasted or uploaded images arrive as image_url parts (a data: URL or an http(s) URL) and need an agent whose model reads images.
• Open WebUI's document upload extracts text and RAG chunks on the Open WebUI side by default and sends them as text. That works, and uses nothing in Console beyond the text. To hand the original file to the agent, use an Open WebUI feature that sends it as a file part (file_data or file_id); Console stores it as a session file.
• An image-only message is valid: the agent answers the picture without a text prompt.

Files the agent creates (a CSV, a Markdown report) come back as output_files metadata on the response; Open WebUI's standard UI shows text only, so for file outputs prefer the runs API or a portal.

Structured output

Open WebUI does not send response_format. If the agent has structured output configured (Configure → Output), the answer is the JSON string of the validated object, which Open WebUI shows as text. For a typed result from a script, call the agent with response_format through the OpenAI SDK instead.

Variables

Open WebUI sends only the person's text, so it cannot fill an agent's variables (the named, typed values a program sends next to the message). An agent that declares variables works in Open WebUI only while every variable is optional or has a default. A required variable without a default makes every message fail with 400 invalid_variables, shown by Open WebUI as an error. Defaults are applied for you and added to the message as a Variables block. If a value has to be filled in, call the agent from a script, n8n or a trigger instead.

Background tasks: set a Task Model

Open WebUI does more than answer the message. After a reply it asks the chat's own model to write the chat title, the tags and the follow-up suggestions. With an agent selected, each of those requests is a full agent turn. A single new chat therefore runs the agent about three extra times: extra sessions in Sessions and Tracing, extra tokens on the budget, and, if the agent has tools, possibly extra tool calls.

Pick a plain model for these tasks:

1. Open Admin → Settings → Interface.
2. Set Task Model (local) and Task Model (external) to an ordinary model from the picker (not an agent: entry).
3. Or switch off Title Generation, Tags Generation and Follow Up Generation in the same page.

Do this once per Open WebUI installation. Otherwise the extra turns are indistinguishable from real ones except by their content.

Tools that need approval

An agent tool that is set to ask for approval cannot show an approval card in Open WebUI, which is a plain chat. What the person sees follows the agent's unattended setting:

• Deny. The tool does not run. The agent tells the person in its answer that the action needs approval.
• Pause. The chat shows a short "waiting for approval" message, and the session waits in Console. An approver answers it there (Sessions, or the approval inbox); the request then continues in that session. The chat does not update on its own, so the person asks again or sends a new message afterwards.

If a tool must run without a person in the loop, use Allow for it on the agent, or call the agent from a trigger or the runs API.

Long turns

A chat turn that is still running when the wait window ends (10 minutes by default) is answered with 202 and a run; a chat front end cannot render that. Streaming turns are not subject to the window (a stream is bounded only by the run ceiling of 30 minutes). Keep Open WebUI agents interactive and fast; put long jobs behind the runs API and triggers.

Troubleshooting

The agent is not in the model list. The agent must be active, the token must have read access to the agents service, and Open WebUI caches the list: reload the page after adding the connection.

404 model_not_found. Use the exact id from /models (agent:<key>). A bare key works when no model has the same key, but the explicit form never collides.

403 mentioning attachments. Switch on files for the agent, or remove the attachment.

Every message fails with 400 invalid_variables. The agent has a required variable without a default, and Open WebUI cannot send it. Make the variable optional or give it a default under the agent's Build → Variables.

Each message starts a fresh conversation. The transcript match only works when Open WebUI resends the full earlier conversation and the same user calls with the same token. A proxy that rewrites messages, or a connection shared by several users with a single user-less token and different histories, defeats it. Send X-Cognipeer-Session-Id from your own client when you can.

Related. OpenAI-compatible gateway for models, Agent models to let people pick the model an agent uses, Stopping a turn.