Workflows: Run agents and chat

Pick an agent, start a chat, replay history, recover from mid-stream errors.

Prerequisites

• agents:<name>:run for at least one agent. Agents the connection cannot run are hidden from /agents; a direct GET /v1/agents/{name} returns 404 rather than 403 to avoid leaking existence.

See available agents

Open /agents. The page calls GET /v1/agents and renders one card per agent the connection can run. Each card shows the agent's name, declared model, system prompt summary, and the list of tools.

Start a chat

Click an agent to open its detail page. Click New chat. The first message you submit triggers three things:

1. The server creates a dh_chats row with user_id = the bound user and agent_name = the agent.
2. The console opens an SSE stream against POST /v1/agents/{name}/stream with Authorization: Bearer <session> and the new chat_id passed through.
3. Tokens stream into the message view in real time. Tool-call events render as inline collapsible cards (name, args, result).

When the agent finishes its turn, the chat appears in your Recent chats list with the assigned chat_id.

Replay history

Close the tab, reopen the agent, click the chat in Recent chats. The console calls GET /v1/chats/{chat_id}/messages?limit=50 and renders the conversation in chronological order, including the tool-call cards. Scrolling up paginates older history via the opaque cursor returned in next_cursor.

Tip: Live streaming and replay share one rendering component. A turn replayed from history looks identical to one streaming in for the first time.

See another user's chat

If your connection holds conversations:read_others, the /chats list exposes a user-id filter. Pick a user from the dropdown to see their chats; opening one fetches and renders the messages normally.

Without conversations:read_others, navigating directly to /chats/<someone-elses-id> returns 404 from GET /v1/chats/{chat_id} and the page renders the "Chat not found" empty state. This is intentional.

Mid-stream session expiry

If your session expires mid-stream, the next SSE chunk returns 401. The in-flight stream surfaces an inline error banner, the console redirects to /connect with the current connection pre-filled, and a banner explains the session expired. After re-exchange the console returns you to the same chat with history reloaded.

LangGraph state is intact, so the conversation continues from where it left off when you send the next message.

Tab close mid-stream

Closing the tab while a turn is mid-stream drops the client-side connection. Server-side cleanup is best-effort; the agent's LangGraph state reflects whatever turn completed last. You may need to nudge the agent on the next reconnect.