Skip to main content

Flow as chat

Flow as chat turns any flow into a conversational runtime. When enabled, the flow exposes a chat interface instead of (or in addition to) the traditional input form — users send messages, the flow runs once per turn, and each run's output is rendered as an assistant reply in the thread.

This is different from AI Flow Chat (the editor-side assistant that helps you build flows). Flow as chat is a runtime feature: it turns the finished flow itself into a chatbot that end-users interact with.

Enabling chat on a flow​

Open the flow in the editor and toggle Chat input on the flow's Input settings. Enabling chat sets chat_input_enabled: true on the flow definition (part of the OpenFlow spec).

When chat is enabled, a chat-input virtual node is rendered on the flow graph to make it clear that the flow's main input comes from the chat interface rather than a form. The runtime passes two extra fields to the flow on every turn:

  • The user's latest chat message (as the flow's chat input argument)
  • A memory_id identifying the current conversation

AI agent steps with managed memory inherit this memory_id by default, so each conversation keeps its own agent history.

Conversations​

Every chat session is a conversation. Conversations are persisted server-side (tables flow_conversation and flow_conversation_message), so users can reopen past chats, resume where they left off, and browse history from the conversations sidebar.

Each turn adds at least two messages to the conversation: the user's prompt and the assistant's reply. Tool usage steps, when shown, appear as additional messages threaded into the turn.

Running a flow as chat​

When a chat-enabled flow is opened in the runner, the form is replaced (or augmented) by a chat interface with:

  • A message list showing the conversation so far
  • A text input at the bottom
  • A sidebar listing past conversations, with the ability to create a new one, rename, or delete

Sending a message starts a new flow run with the message as input. The assistant's reply is the flow's output, streamed or polled as it arrives.

Cancel button​

While a turn is in-flight, the Send button is replaced by a Stop button. Clicking Stop cancels the underlying queued job (via JobService.cancelQueuedJob) so a long-running flow doesn't block the conversation. Cancel works in both polling and streaming modes.

Customizing the assistant reply​

When the final step of a chat flow is not an AI agent, the flow's output is persisted as the assistant message. By default, the whole result is pretty-printed as JSON into the chat transcript. If the result is a plain string, that string is shown as-is.

To control exactly what the user sees, return a windmill_chat_answer key from the final step:

  • windmill_chat_answer: "<string>" — the string is used as the assistant message; other keys in the result are ignored in the transcript (they are still part of the flow output).
  • windmill_chat_answer: null — no assistant message is appended for this turn. Use this when your flow has already written its own messages to the conversation, or when the turn should stay silent.
  • Key absent — the default behavior applies (full pretty-printed JSON, or the string itself if the result is a string).
export async function main(prompt: string) {
const answer = await computeAnswer(prompt);
return {
windmill_chat_answer: answer,
// any other keys remain in the flow's output but are not shown in chat
debug: { prompt, timestamp: Date.now() }
};
}

Image outputs​

If the flow's output contains image data (data URLs, base64-encoded images, or S3 objects resolving to images), the chat renders them inline in the assistant's reply. This lets chat flows return generated charts, screenshots, or AI-generated images without any extra configuration.

Tool usage display​

When a chat flow uses AI agent steps that call tools, each tool invocation is displayed inline in the conversation as a collapsible message. Tool messages show:

  • The tool name (and flow step name)
  • A success indicator (green check or red cross)
  • The tool's arguments and result (expandable)

This makes it easy for end-users to see what the agent did on their behalf, and for developers to debug multi-step agent runs.

Chat SDK for your own frontend​

The chat interface above lives in Windmill. To put the same chat in your own product, the @windmill-labs/chat-sdk npm package runs a deployed chat flow from any frontend, including a full-code app. It is headless: it starts a run per message, follows the answer as it streams, keeps the conversation history, and hands you state to render with your own components.

npm install @windmill-labs/chat-sdk

The package was published as windmill-chat up to version 1.812.0. That name no longer receives releases: replace it with @windmill-labs/chat-sdk in your dependencies and imports.

The package has no runtime dependencies and one entry point per UI stack:

You build the UI withImportYou get
Vercel AI SDK useChat, AI Elements@windmill-labs/chat-sdk/ai-sdkA ChatTransport to pass to useChat({ transport })
assistant-ui@windmill-labs/chat-sdk/assistant-uiA runtime for AssistantRuntimeProvider, with conversations as threads
Your own React components@windmill-labs/chat-sdk/reactThe useWindmillChat hook, with messages, status and actions
Another framework@windmill-labs/chat-sdkcreateChat, a store you subscribe to (it follows the Svelte store contract)

With the React hook, a minimal chat looks like this:

import { useState } from 'react';
import { useWindmillChat } from '@windmill-labs/chat-sdk/react';

export function Support() {
const chat = useWindmillChat({
baseUrl: 'https://app.windmill.dev',
workspace: 'acme',
flowPath: 'f/support/assistant',
// called before every request, so your backend can return a short-lived token
token: () => fetch('/api/windmill-token').then((r) => r.text())
});
const [draft, setDraft] = useState('');

return (
<div>
{chat.messages.map((m) => (
<p key={m.id} data-role={m.role} data-pending={m.pending}>
{m.content}
</p>
))}
<form
onSubmit={(e) => {
e.preventDefault();
chat.sendMessage(draft);
setDraft('');
}}
>
<input value={draft} onChange={(e) => setDraft(e.target.value)} />
<button disabled={chat.status !== 'idle' && chat.status !== 'error'}>Send</button>
{chat.status === 'streaming' && (
<button type="button" onClick={chat.stop}>
Stop
</button>
)}
</form>
</div>
);
}

Messages have a role of user, assistant, tool or system. Tool calls of an AI agent step arrive as tool messages whose status moves from running to success or error. A flow that fails still completes the turn, with its error as an assistant message marked success: false.

The package README is the full reference for the options, the state and the methods of each entry point.

Inside a full-code app​

In a full-code app, pass flowPath: the chat runs as the viewer, against the Windmill instance the app is served from.

const chat = useWindmillChat({ flowPath: 'f/support/assistant' });

Viewers need permission to run the flow. With sandbox isolation on, turn on "Run scripts and flows" in the app's frontend API access, plus "Manage your flow chats" for server-side history. Under wmill app dev there is no viewer session, so pass baseUrl, workspace and token explicitly during development.

A chat-mode flow or a saved AI agent can also be a backend runnable: pass { wmill, runnable } instead of flowPath, and the chat runs as the app with no frontend API access. "Build chat app" on the flow's page generates such an app.

Tokens and conversation history​

Outside Windmill, the chat authenticates with a user token. Anything a browser holds can be read by its user, so scope the token to what the chat needs. The history option decides where conversations are kept, and the right value depends on who the token belongs to:

SetupToken scopesHistory
Public site, one token shared by every visitorjobs:run:flows:f/support/assistantlocal (the default with a token): conversations stay in the browser's localStorage
One token per user, minted by your backendThe above plus flow_conversations:writeserver: the conversations Windmill stores for that user
Full-code app, or another page served by WindmillNone, the viewer's session is usedserver (the default without a token)

Server history is keyed by the Windmill user, so do not combine it with a shared token: every visitor would see the others' conversations. history: 'none' keeps nothing beyond the page.

The token's user must be allowed to run the flow. Anyone holding the token can run the flow with inputs of their choosing, so treat the message and the other flow inputs as untrusted in a flow exposed this way.