Agent DocsDeveloper documentation
Consumer Guide

Chat & Conversations

How chat works — SSE streaming, attachments, history, tool calls

Chat and Conversations

This guide covers how end users interact with agents through the Agent Portal chat interface, including message streaming, tool calls, attachments, conversation history, and error handling.

Starting a Chat

  1. Navigate to the Agent Portal (port 3000) and select an agent from the agent catalog or sidebar.
  2. The chat page loads at /chat/{agentId} and displays:
    • The agent name, status badge, runtime badge, and model info in the header bar.
    • A welcome screen with the agent description, suggested prompts, and capability tags.
  3. Click a suggested prompt or type a message in the input bar and press Enter.

Suggested Prompts

Agents can configure suggested prompts in two ways:

  • Builder-configured prompts — set via suggestedPrompts in the agent config (up to 3 shown).
  • Capability-based fallback — if no prompts are configured, the platform generates suggestions based on the agent's declared capabilities (e.g., "knowledge-base" maps to "Search the knowledge base for recent updates").

OAuth Prerequisites

Some agents use tools that require OAuth connections (GitHub, Slack, Jira, etc.). If required connections are missing, a warning banner appears above the chat area with a link to the Integrations page. You can still send messages, but tool calls requiring those connections will fail gracefully.

SSE Streaming

When you send a message, the portal opens a Server-Sent Events (SSE) connection to POST /api/chat/{agentId}/message. The response streams back in real time:

  1. Handshake — the server emits an AG-UI run_started event with the run ID and thread (conversation) ID.
  2. Text tokens — arrive as text_message_content_delta events. The UI appends each token to the current message, creating a typewriter effect.
  3. Tool call events — emitted as tool_call_start, tool_call_args, and tool_call_end events (see Tool Calls below).
  4. Thinking segments — if the model supports extended thinking (e.g., Claude with thinking enabled), thinking tokens are streamed separately and displayed in a collapsible "Thinking" section.
  5. Done — a run_finished event signals the end of the response. The streaming indicator disappears and the message is finalized.

Auto-Scroll Behavior

The chat area automatically scrolls to the bottom as new tokens arrive. If you scroll up to read earlier messages, auto-scroll pauses. It resumes when you scroll back near the bottom (within 100px of the end).

Tool Calls

When an agent invokes a tool during a conversation, the UI displays tool calls as expandable cards within the message stream:

  • Tool name — shown as a badge (e.g., "web_search", "create_ticket").
  • Arguments — displayed as key-value pairs inside the expandable card.
  • Result — the tool output appears after execution, formatted as text or structured data.
  • Status indicators — a spinner shows during execution; a checkmark or error icon appears on completion.

Tool calls are rendered inline in the conversation flow. Each tool call has a unique ID, and the agent's final response typically references or summarizes the tool results.

HITL (Human-in-the-Loop) for Tool Calls

If a tool call exceeds the risk threshold or has HITL conditions configured, an approval request is created instead of executing the tool immediately. See the Approvals and HITL guide for details.

Attachments

The chat input supports file uploads when the agent's defaultInputModes includes file MIME types beyond text/plain.

Uploading Files

  • Click the attachment icon in the chat input bar or drag and drop a file.
  • Accepted MIME types are determined by the agent configuration.
  • Text-based files (code, markdown, CSV) are inlined into the message context.
  • Images are shown as thumbnails in the message and sent as vision inputs to multimodal models.

How Attachments Are Processed

  1. Files are uploaded to the server with the message.
  2. Text-based attachments (text/*, application/json, etc.) have their content extracted and included in the LLM context.
  3. Image attachments are passed as vision inputs to models that support multimodal inference (e.g., Qwen2.5-VL-72B-Instruct, gemini-2.5-pro).
  4. The attachment metadata (filename, size, type) is displayed in the message bubble.

Conversation History

Sidebar

A collapsible Conversation Sidebar on the left shows all previous conversations with the current agent:

  • Each entry displays the conversation title (derived from the first message), a preview of the last message, timestamp, and message count.
  • Conversations are sorted by recency (most recent first).
  • Click a conversation to load its full message history.
  • The sidebar can be collapsed on desktop to maximize the chat area.
  • On mobile, the sidebar is an overlay that slides in from the left.

Loading Previous Conversations

When you select a conversation from the sidebar:

  1. The current chat is cleared.
  2. The selected conversation's messages are loaded from the server via GET /api/conversations/{id}.
  3. If the conversation has an active Temporal workflow (still running), the chat automatically reconnects to the live SSE stream via the reconnect endpoint.

Creating New Conversations

  • Click "New Chat" in the sidebar to start a fresh conversation.
  • When you send the first message in a new chat, a conversation is created server-side and automatically added to the sidebar.

Deleting Conversations

  • Conversations support soft-delete. Click the delete action on a conversation in the sidebar.
  • The conversation is removed from the sidebar and marked as deleted on the server. It does not appear in future queries.
  • If you delete the currently active conversation, the chat area is cleared.

Thinking and Reasoning

When using models that support extended thinking (e.g., Claude models with thinking enabled, o3, o4-mini), the chat displays reasoning content:

  • Thinking segments — shown in a collapsible section above the main response, with a "Thinking" label. These represent the model's internal chain-of-thought reasoning.
  • Live thinking — during streaming, thinking tokens appear in real time in the collapsible section before the final answer begins.
  • Thinking content is visually distinct from the main response (typically styled with a lighter background or italic text).

Workflow Progress

For agents running as Temporal durable workflows, a Workflow Steps component appears below the messages showing:

  • The current workflow step and its status (pending, running, completed, failed).
  • A progress indicator across all steps.
  • If the workflow fails, a "Restart" button allows you to retry from the failed step.

A2UI Protocol Surfaces

Agents can render interactive UI surfaces during conversations via the A2UI protocol. These appear as embedded components below the message stream and support:

  • Selection surfaces — checkboxes or radio buttons for the user to select from options.
  • Plan selection — the agent proposes a plan and the user can approve, modify, or cancel selected steps.
  • Submit/Cancel actions — user interactions are sent back to the agent as HITL responses.

Error Handling

Chat Errors

Errors during chat are displayed in a banner below the message area:

  • Connection errors — shown with an amber background and a "Connect now" link if the error relates to missing OAuth connections.
  • Tool failures — if a tool call fails, the error is displayed inline in the tool call card. The agent typically acknowledges the failure and offers alternatives.
  • LLM errors — if the model request fails (rate limit, timeout), the error banner shows the issue. The backend automatically attempts a fallback model if one is configured.

Agent Not Found

If the agent ID is invalid or the agent is not accessible, a full-page error state is shown with a "Back to agents" button.

Feedback

Each agent message supports thumbs-up/thumbs-down feedback:

  • Click the feedback icons on any agent message.
  • Optionally provide a text correction.
  • Feedback is submitted to POST /api/feedback and linked to the specific agent, conversation, and message.

Related Guides