Agent Chat
The Chat tab in Agent Detail provides a bubble UI for conversing with agents, with persistent history and real-time status updates.
How to talk to an agent from its Chat tab
1:038 chapters
I Gave My AI Three Years of My Notes — Then Interviewed It
May 2026
A New Session per Message
Each message on this tab runs as a new agent session, and the last 20 messages of the visible transcript are included as text for context. The tab says so in a banner (Each message runs as a new agent session; the last 20 messages are included for context.), with a Continue in Workspace → link beside it that opens the Workspace in its own browser tab.
For a conversation where the agent keeps its working memory between turns — tool results, mid-task state, reasoning — use the Workspace instead. The Session-mode toggle that used to live here has been retired in its favour, and ?tab=session links now redirect there.
The tab is text only. Voice lives in the Workspace: open it from the navigation bar and use the composer's call button — see Voice Chat. Calls you had here before that change are still in their sessions, badged Voice.
Concepts
/ in the chat input to open a Skills dropdown of the agent's skills. Ghost text shows command syntax with argument hints.--resume flag.How It Works
Open an agent's detail page and click the Chat tab.
Select an existing session from the dropdown or click New Chat.
Optionally pick a model in the Default model dropdown above the input; empty means the agent's default. The choice is remembered in this browser.
Type a message and press Enter.
The agent processes the message — the status label updates in real-time (e.g., Reading …/src/app.py..., Running pytest -q..., Processing results...).
The response appears as a chat bubble.
Type / to autocomplete skill commands.
The agent must be running; a stopped agent shows Agent Not Running in place of the input.
The floating Help launcher is hidden on this tab so it never covers Send. A help conversation you already had open stays open when you switch to Chat. See Getting Help.
Stopping a Turn
While a turn runs, Send becomes Stop. Click it, or press Escwith nothing else open, to cancel the in-flight turn: the turn ends as cancelled (not failed) and your message text returns to the input, in front of anything you typed while waiting. A cancel that loses the race to the reply says nothing — the reply is already on screen. A refused cancel leaves the input untouched and says the turn is still running. Stop is available once the turn has an execution id, which takes about a second.
File Attachments
Attach files using the paperclip button or drag-and-drop onto the chat input.
Supported types
/home/developer/uploads/ inside the agent container and readable by name; a ZIP is stored as-is, not extractedALLOW_PDF_UPLOADS=true in .env and recreating the backend. The setting applies to every agent and to web, public and channel chat alike; there is no per-agent switch. An enabled PDF is written unchanged to /home/developer/uploads/ like any other document, and reading it (text extraction, OCR) is up to the agent's own tools. Delivery is not validation: Trinity checks that the file is a PDF, not that it is safe to open. The paperclip picker does not list PDFs, so drop the file onto the input insteadLimits per message
| Max files | 3 |
| Max size per file | 5 MB |
| Max total image size | 10 MB |
Oversized files are rejected client-side. Files exceeding limits are skipped with a note appended to the message context. File uploads work in both authenticated and public chat.
Continue as Chat
--resume {session_id} for native session continuity.Session Management
POST /api/agents/{name}/chat/sessions/{id}/closeAPI Endpoints
The Chat tab itself sends each message as an asynchronous POST /api/agents/{name}/task with save_to_session: true (the transcript rides along as text), then follows the execution's stream and polls it for the result. POST /chat is the programmatic route that chat_with_agent and the trinity CLI use — see Chat API.
| Endpoint | Method | Description |
|---|---|---|
| /api/agents/{name}/chat | POST | Send chat message (stream-json output). The response's execution.compaction reports an auto-compaction during the turn, or is null |
| /api/agents/{name}/chat/sessions | GET | List all sessions |
| /api/agents/{name}/chat/sessions/{id} | GET | Get session with messages |
| /api/agents/{name}/chat/sessions/{id}/close | POST | Close session |
| /api/agents/{name}/chat/history/persistent | GET | Get persistent history |
| /api/agents/{name}/chat/history | GET | The agent's current /chat conversation |
| /api/agents/{name}/chat/history | DELETE | Reset the /chat conversation so the next turn starts fresh (owner or admin) |
| /api/agents/{name}/executions/{id}/terminate | POST | Stop an in-flight turn (what Stop calls) |
MCP Tools
chat_with_agent(agent_name, message) — Send a message to an agent. In its default sequential mode it continues the agent's own chat session, shared by every caller of that agent. It never picks up a scheduled or other headless run's session — on Claude Code and Gemini agents alike; if that session has gone missing, the turn retries once from a fresh start. The session starts fresh after a model change or a history reset (DELETE /api/agents/{name}/chat/history). A turn that crosses the context limit can pay a one-off auto-compaction, which is recorded as compact_metadata (read it with get_execution_result) and does not mean the agent is degraded. A turn whose run ends in an error is a failed execution with the real error, never a reply whose text is the error message. On an agent in the experimental pull-mode pilot, each caller gets their own conversation instead of the shared one — see Chat API.get_chat_history(agent_name) — Retrieve chat history for an agent.