Chat Interface
The chat panel is the primary way you communicate with the Studio AI agent. This page describes all controls, interaction patterns, and states you will encounter.
Sending a Message
- Click the chat input area at the bottom of the center panel (placeholder: "Describe your business question...").
- Press / from anywhere in the application to focus the chat input immediately.
- Type your message.
- Press Enter to send, or click the send button (arrow-up icon, blue).
- Use Shift+Enter to add a new line without sending.
The chat input auto-expands up to 200px as you type, then scrolls internally.
Attaching Files to a Message
You can send supported text, image, and Excel workbook files with a message, or send files without typing any text.
- Click Upload file and choose one or more files. Studio accepts
.txt,.md,.markdown,.json,.xlsx, PNG, JPEG, GIF, WebP, and AVIF files. - To attach a supported file from the clipboard, paste it into the chat input. Pasted images appear with a preview; text, Markdown, JSON, and Excel files appear as filename chips.
- Review the attachment chips above the input. Use the remove button on a chip if you do not want to send that file.
- Add message text if needed, then click Send message. While a Turn is running, the button shows Stop when the box is empty and toggles to Send message as soon as you type; sending adds the message and files to that Turn, which the agent picks up before the Turn finishes.
Studio uploads the complete attachment batch before sending the message. If a file is unsupported, malformed, or cannot be uploaded, Studio sends no message and keeps the text and attachment chips available so you can remove a file or retry. Studio does not impose its own file-size or attachment-count limit, but browser, deployment, and agent-runtime limits can still cause an upload to fail.
If a message fails to send after its files upload, Studio removes it from the queued list above the composer and shows a Message could not be sent — try again. notification. Retype the message and send it again when you are ready.
Attachments belong only to the AgentSession that receives them. Sleeping, restarting, replacing, or reaping that AgentSession removes the files. Conversation replay continues to show the filenames, but those names are not download links and a later AgentSession cannot read the earlier files.
For an .xlsx workbook, the agent can list its worksheets, inspect a worksheet's workbook-recorded bounds, and read an exact inclusive A1 range that you or the agent supplies, such as A2:F100. Each valid workbook action pauses at an Approval Request; select Approve to allow that batch, or Always allow to let future matching actions proceed without another prompt. Recorded bounds are a discovery hint and may include formatted empty cells, so you can provide a more precise range. Every data read requires both a worksheet name and a range. A request over 1,000 rows or 50 columns is rejected instead of truncated; the agent can make additional bounded calls when needed. Range data is normally staged in temporary CSV files to keep it out of the agent's immediate context. The agent can request inline data when the combined serialized values and formulas do not exceed 256 KiB; larger inline results are rejected without truncation and can be retried as CSV. Formula cells include the literal formula and the last value cached by the application that saved the workbook. Studio does not evaluate formulas, macros, external links, or external data.
Empty States
There are two empty states depending on whether an intent is selected.
Welcome Screen (no intent selected)
When no intent is selected and there are no messages, the WelcomeScreen appears with the heading "What would you like to build?" and six suggestion cards:
| Card | Description |
|---|---|
| Quarterly Revenue by Region | Build a revenue breakdown with QoQ growth from Salesforce data |
| AR Aging Report | Create 30/60/90 day aging buckets from QuickBooks invoices |
| Pipeline Velocity | Analyze sales pipeline speed and conversion rates by stage |
| Customer Churn Analysis | Segment customers by churn risk using behavioral signals |
| Order Trends | Analyze order volume and trends over the last 12 months |
| Custom Analysis | Placeholder card — clicking it does nothing (empty prompt string, no handler wired) |
Clicking any card except Custom Analysis pre-fills the input with a starter prompt.
New Intent Empty State (intent selected, no messages)
When an intent is selected but has no messages yet, the NewIntentEmptyState appears with the heading "Ready when you are" and three quick-start pill buttons:
- "Build a revenue report from Salesforce data"
- "Create staging models for my raw tables"
- "Analyze customer churn patterns"
Clicking any pill pre-fills the chat input with that prompt.
Agent and Model Selection
The primary agent is selected when an Intent is created. The LLM Profile picker in the chat input bar controls the model and provider credentials used by the next turn.
New Intents inherit the instance default profile unless a profile is selected explicitly. For an existing Intent, selecting another profile updates its binding for the next turn. If the bound profile is deleted, the Intent remains available but Send stays disabled until you select a replacement.
When an agent successfully switches profiles during a turn, the picker updates to that profile and later turns use it.
Stopping a Running Task
While the agent is streaming:
- Press Escape at any time to stop generation.
- Click the Stop button (red square icon) in the chat input bar.
Both actions cancel the current agent task immediately. Messages already generated are retained.
Autonomous Goals
Use a Goal when you want OpenHands to keep working, audit the result, and continue until the objective is accepted, reaches its iteration cap, or you intervene.
| Command | Result |
|---|---|
/goal <objective> | Starts a Goal in an idle Conversation. If work is already active, Studio leaves it unchanged and reports a conflict. |
/goal stop | Asks OpenHands to stop the outer Goal loop. An in-flight worker may finish before the Goal appears Paused. |
/goal resume | Resumes the latest paused Goal from retained OpenHands state. |
Goal status, objective, progress, and the latest audit verdict appear at the top of the Right Panel. Worker messages and tool activity remain in the transcript; OpenHands' internal continuation and resume prompts are hidden.
Sending an ordinary message or using Stop pauses a running Goal, then follows the ordinary Conversation behavior for that action. A paused Goal never resumes automatically. After a stopped or crashed runtime is opened again, use /goal resume explicitly to continue retained Goal work.
To start a different Goal, stop the current Goal and wait for any in-flight worker to settle, or wait for existing work to finish naturally. Studio does not replace active Goal or Conversation work.
Queuing a Follow-Up Message
If you have a follow-up message ready while the agent is still running:
- Type your message in the chat input.
- Click the Queue button (list-plus icon) — it appears next to the Stop button during streaming.
Your message will be sent automatically as soon as the current task finishes. Only one message can be queued at a time.
Persistent Sessions
The agent uses persistent streaming sessions — after your first message, subsequent messages in the same intent resume the existing session rather than starting from scratch. This means:
- Faster responses on follow-up messages (no cold restart per turn).
- The agent retains full context from earlier turns without re-processing.
MCP Servers When Opening an Intent
If Studio cannot attach one or more of your configured MCP servers while opening an Intent or restarting its AgentSession, the Conversation remains usable.
- Opened with some MCP servers unavailable lists the servers Studio skipped, such as GitHub or Linear.
- Opened without some MCP servers appears when Studio cannot identify the skipped servers.
Neither notice appears when you have no MCP servers linked or when the installation has no MCP integration set up. In those cases the Intent opens normally with Studio's built-in tools and nothing to repair.
To restore those MCP servers:
- Open User Settings.
- Select MCP Servers.
- Complete or retry the affected server's setup.
- Pause the Intent, then open it again.
Reopening a persistent Conversation by itself does not start a new AgentSession. Pause the Intent, then open it again, after changing MCP setup so Studio offers the updated server configuration to the replacement AgentSession.
Named deployments of the same MCP server remain distinct in the agent runtime. Unique names become readable tool prefixes, so deployments such as Workspace A and Workspace B expose separate obot-workspace-a and obot-workspace-b tool groups. Studio still assigns distinct tool prefixes if names would otherwise collide. Renaming, adding, removing, connecting, or disconnecting a deployment does not change the tool set of an AgentSession that is already active. Pause the Intent, then open it again, to use the updated MCP tool set.
Background Streaming
When you switch away from an Intent that is actively streaming, the agent continues running on the server. When you return, Studio uses the Intent's current status to attach to its existing agent session or restore that session first, then replays the complete Conversation so you do not miss output that arrived while you were away.
If the browser event connection is interrupted, Studio retries the same connection for a bounded period and resumes from the last durable event it received. This network recovery does not reconnect or restart the agent session. If Studio cannot restore the connection, it leaves the Intent workspace and shows Connection to this conversation was lost with Select the Intent again to reconnect. Select the Intent again when you are ready; Studio then uses its current status to choose whether to attach or restore the session.
The Edit Lease is renewed separately while you drive the Intent. If Studio can no longer confirm that authority, a persistent banner identifies the reason, such as The edit lease is no longer available, You no longer have permission to drive this Intent, This Intent is no longer available, or The edit lease expired. Send and Pause remain unavailable while the banner is shown. Return to the Domain and select the Intent again after resolving the cause. This is different from Connection to this conversation was lost: losing the browser event connection does not by itself change the Edit Lease or restart the agent session.
The spinning teal streaming icon inside the Intent's status pill shows that the Intent is producing live output in the background. Its tooltip reads Streaming live output…
Toast notifications
Studio uses distinct colors and icons to show toast notification severity.
- Toast warnings describe degraded or recoverable conditions. They disappear automatically after a short time.
- Toast errors mean an operation failed or an outcome is blocked. They remain visible so you can read the cause and recovery guidance. Select Close toast to dismiss an error.
Conversation Errors
If a Turn ends with a runtime error, Studio keeps a Conversation error entry in the transcript. The available error detail appears in the entry. Select Technical details to inspect diagnostic fields reported by the runtime.
The entry remains in the Conversation when you leave and reopen the Intent. Diagnostic fields do not add Retry, Settings, or other action controls; they are technical evidence about the failed Turn.
Multi-Question Wizard (QuestionCard)
When the agent needs clarification before proceeding, it presents a QuestionCard — a structured wizard that walks you through multiple questions one at a time.
How it works
- The card displays one question at a time with a progress counter (e.g. "1/3") in the top-right corner.
- Each question shows predefined options as clickable cards numbered 1–N. Selecting an option auto-advances to the next question after a brief highlight.
- Below the options, a "Type something else..." button opens a free-text input where you can write a custom answer. Press Enter to submit or Escape to cancel.
- Dot indicators at the bottom show your position in the question sequence: the current question dot is blue, answered questions are green, and unanswered questions are gray.
- Use the left/right chevron buttons (or Arrow Left / Arrow Right keys) to navigate between questions and revise previous answers.
- The footer shows an answered count (e.g. "2/3 answered").
Actions
| Button | Behavior |
|---|---|
| Skip all | Skips all remaining questions and lets the agent proceed with defaults |
| Submit | Sends all answers to the agent. Only enabled when every question has been answered. |
Keyboard shortcuts
| Key | Action |
|---|---|
| 1–N | Select the corresponding option (number keys match option numbers) |
| Arrow Left | Go to previous question |
| Arrow Right | Go to next question |
| Enter | Submit custom text answer (when typing) |
| Escape | Cancel custom text input |
For technical details on how the agent decides to ask questions, see Agent Behavior.
Sub-Agent Task Cards
When the agent delegates work to a sub-agent, a SubagentItem card appears in the chat timeline. Each card shows:
| Element | Description |
|---|---|
| Label | The sub-agent name and type (e.g. "team-name/agent") with a bot icon |
| Status | Running (animated) or completed (check icon) |
| Badges | Optional metadata: "parallel" if running in parallel, the model name, and parent context token count |
| Child items | Nested tool calls, thinking blocks, and further sub-agent cards (up to 3 levels deep) |
| Result | A "Result" block with the sub-agent's conclusion once it completes |
Sub-agent cards are collapsed by default. Click the card header to expand and see the full activity log.
Message Structure
Assistant messages use interleaved rendering: text segments and tool-call groups are displayed in the order they occurred, rather than text-first then tools. Consecutive tool calls are collapsed into a single ToolCallsGroup. A TurnSeparator (centered dot divider) appears between consecutive assistant messages when the previous message had tool calls.
User messages that match the Q&A answer format (**Question**\n> Answer) are rendered as structured QA Answer Cards instead of plain text.
If Studio attaches guidance to one of your messages, a collapsed Additional context annotation appears below it. Select Additional context to read the injected guidance; your original message remains separate and unchanged.
Hover over any message to reveal its Copy button. Eligible user and assistant messages also show Fork from here. Choose Fork from here to create a new Intent from that point; later messages remain in the source Intent. Forking from an assistant response includes that response in the child. Forking from one of your messages starts the child before it and places its text in the child's composer without sending it, so you can edit and resend it.
On a long-running conversation, Studio periodically compacts older history to stay within the model's context window. A compacted message is dimmed and labeled Dropped from context; its Fork from here button stays visible but disabled, since forking from it can no longer succeed. Choose a message that has not been compacted instead. If Fork still fails, Studio explains that the message's context was compacted.
Activity in the Conversation
Studio groups execution details into Tool Activity, Hook Activity, Background Activity, and Agent Activity. Select an activity heading to expand or collapse its details.
- Tool Activity shows tool calls and their results.
- Hook Activity shows visible hook runs. A blocked hook opens automatically; Stop-hook feedback appears inside that activity.
- Background Activity shows pending and completed async shell or background sub-agent work, including failures. It starts collapsed.
- Agent Activity shows framework guidance sent to the agent. It starts collapsed.
Collapsed details remain searchable. The same activity appears after Studio reconnects to the Conversation or after you leave and reopen the Intent.
Viewing Artifacts
The agent produces files (artifacts) as part of its work — SQL models, YAML configs, Markdown documents, Python scripts, and more. Artifacts appear as inline file links in chat messages.
- Click any file link in a chat message to open the Artifact Modal.
- The modal shows the file content with syntax highlighting.
- Use the header buttons to copy, download, edit, or open in Code View.
See Artifacts for a full description of the Artifact Modal.
Thinking Blocks
When the agent performs extended reasoning, a ThinkingCard appears as a distinct timeline step with a violet left border and a brain icon. While actively thinking, the border pulses and animated dots appear. Once complete, a duration badge shows how long the thinking took (e.g. "2.3s"). Long thinking content is truncated with a gradient fade and a Show more / Show less toggle.
Reconnecting Banner
If the conversation connection drops during streaming, a yellow Reconnecting banner appears above the chat input with a spinning loader. It disappears automatically once the connection is restored and replay completes.
Recovering a Long Conversation
When a conversation reaches the selected model's context limit, Studio shows Context limit reached. Compacting conversation and retrying… and continues the same message automatically. After recovery, the boundary changes to Context compacted.
Tool Results
When the agent uses a tool that returns data, the result appears as a collapsible block in the chat. The following content types are supported:
| Type | Appearance |
|---|---|
table | Paginated data table with column headers |
sql | SQL code block with syntax highlighting |
log | Scrollable log output in monospace font |
markdown | Rendered Markdown content |
yaml | YAML code block with syntax highlighting |
json | JSON code block with syntax highlighting |
text | Plain text paragraph |
error | Red error message block |
Approval Requests
When the agent proposes an action that exceeds your configured risk threshold, or whose risk couldn't be classified, Studio pauses and shows a single Approval Request card in the chat stream. One card represents the agent's entire pending batch — every action currently waiting on approval — grouped by subject, not one card per action.
Each subject shows:
| Element | Meaning |
|---|---|
| Kind badge | Exact command, Command family, or Tool — how narrowly the subject is scoped |
| Risk badge | Low, Medium, High, or Unknown, colored and iconed by severity |
| Label | The command or tool the subject represents |
×N count | Shown when more than one proposed action maps to the same subject; lists each action underneath |
| "Already covered" | Shown when an existing always-allow grant already matches this subject |
If your confirmation settings changed after the request was created, the card shows an italic notice that it was evaluated against your earlier settings.
Command-family grants apply only to Studio's documented command shape. For example, a normal git push grant requires an explicit remote and refspec and does not cover configuration-driven, force, delete, mirror, or prune pushes; those remain separate exact-command approvals. GitHub CLI commands remain exact-command approvals.
Three actions are available:
- Approve (green) — approves this batch only. The next matching action pauses again.
- Always allow (outlined green) — approves this batch and creates an always-allow grant for every subject not already covered, so matching actions skip approval from then on, at any risk level, until you remove the grant.
- Reject (outline) — opens an inline, optional reason field with Confirm reject / Cancel.
Manage or revoke always-allow grants from Settings → Action Confirmation → Always-allowed actions.
Chat States
| State | What you see |
|---|---|
| Welcome screen | Centered heading "What would you like to build?" + six suggestion cards (no intent selected) |
| New intent empty | Centered heading "Ready when you are" + three quick-start pills (intent selected, no messages) |
| Sub-agent running | Collapsed SubagentItem card with animated status; expand to see live activity |
| Streaming | Typing indicator (three animated dots), Stop button, Queue button |
| Thinking | Violet-bordered ThinkingCard with brain icon and animated dots |
| Error banner | Red banner above input with error message and dismiss (X) button |
| Model unavailable | Warning: “Model unavailable; select another profile.” Send remains disabled until you select an LLM Profile. |
| Reconnecting | Yellow banner with spinner: "Reconnecting..." |
| Background streaming | Blue banner: "Agent is processing in the background..." with Cancel button |
| Scroll-to-bottom button | Floating button when you scroll up in a long conversation |
Quick Reference: Chat Controls
| Control | Location | Action |
|---|---|---|
| Chat input | Bottom center | Type your message |
/ key | Anywhere in app | Focus the chat input |
| Send button (arrow up) | Bottom right of input | Send message |
| Stop button (red square) | Bottom right (streaming) | Stop the agent |
| Queue button (list-plus) | Bottom right (streaming) | Queue a follow-up message |
| Lightbulb | Bottom left of input | Non-functional placeholder |
| LLM Profile picker | Bottom left of input | Select the profile used by the next turn |
| Escape key | Anywhere | Stop the streaming agent |
| Enter | Input focused | Send message |
| Shift+Enter | Input focused | Insert a new line |
| Copy button | Message hover | Copy message text to clipboard |
| Fork from here button | Eligible message hover | Create a new Intent from that message's Conversation boundary |
| Regenerate button | Assistant message hover | Re-run the last assistant response |
| Scroll-to-bottom | Floating (scrolled up) | Jump to latest messages |
Recap briefing card
Type /recap in the conversation composer to get a one- or two-sentence briefing of at most 50 words. It covers work since the current AgentSession opened and emphasizes one recap, insight, or recommendation; recommendations may also show a priority. The compact Recap · not saved card is never added to conversation history and disappears on refresh.
Manual recap works whenever the Intent has an open Conversation, including a terminal Intent opened read-only. During an active Turn, Studio also requests one automatically after three minutes without keyboard, pointer, scroll, composer, or return-to-tab interaction. Agent activity does not restart that clock; finishing, failing, pausing, or cancelling the Turn stops it. Cards and viewed state are not saved, and /recap always requests a fresh snapshot on demand.
Build Summary card
Type /build-summary in the conversation composer when you want a structured account of what was built, the design and architecture, validation evidence, and work attributable to the current AgentSession. Studio reads the complete Conversation but does not run tools, add a message, change the workspace, or save the card. Manual requests show a point-in-time Snapshot and also work for an opened read-only Conversation.
During an active Turn, Studio requests the first Build Summary after 15 minutes and checks again every 15 minutes. Keyboard, pointer, and composer activity do not reset this timer. If no new Conversation event has arrived, Studio keeps the existing card without another generation request. A new result replaces the previous card. When the Turn finishes or fails, a still-visible card refreshes once as a Snapshot with the terminal evidence, then automatic requests stop. Pausing or cancelling stops the timer without requesting another summary. Dismissing the card prevents a final refresh, including while Studio reconnects to the same Turn.
The Build summary · not saved card follows the same inline treatment as BTW and Recap. Its compact view shows a synopsis and up to three rows from Built, Design, and Validation. Select Show all to inspect every non-empty evidence group, including Current session and Architecture; select Show less to collapse it again. Automatic cards are labeled In progress, while manual cards are labeled Snapshot. Select Dismiss build summary to hide the card.