Skip to main content
Trinity
Updated Nov 17, 2026main@87e21ff
Guides/Agent Chat

Agent Chat

The Chat tab in Agent Detail provides a bubble UI for conversing with agents, with persistent history and real-time status updates.

See it in the product

How to talk to an agent from its Chat tab

1:03
8 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

•Chat Session — A conversation thread stored in the database. Each agent can have multiple sessions.
•Dynamic Thinking Status — Real-time labels showing what the agent is doing (replaces static “Thinking...”). Each tool call becomes a short line such as Reading …/src/app.py... or Running pytest -q...; each label stays up at least 500 ms so fast tool calls don't flicker.
•Skill Autocomplete — Type / in the chat input to open a Skills dropdown of the agent's skills. Ghost text shows command syntax with argument hints.
•Continue as Chat — Resume a completed or failed execution as an interactive chat, preserving the full context (150K+ tokens) via Claude Code's --resume flag.

How It Works

1

Open an agent's detail page and click the Chat tab.

2

Select an existing session from the dropdown or click New Chat.

3

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.

4

Type a message and press Enter.

5

The agent processes the message — the status label updates in real-time (e.g., Reading …/src/app.py..., Running pytest -q..., Processing results...).

6

The response appears as a chat bubble.

7

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

•Images (JPEG, PNG, GIF, WebP) — passed as vision content blocks
•Plain text, CSV, JSON, and ZIP — written to /home/developer/uploads/ inside the agent container and readable by name; a ZIP is stored as-is, not extracted
•Unsupported: tar, gzip, rar, video, audio. PDF is unsupported by default
•PDF (operator opt-in): an operator can enable PDF delivery for the whole deployment by setting ALLOW_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 instead

Limits per message

Max files3
Max size per file5 MB
Max total image size10 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

•From the Execution Detail page, click Continue as Chat.
•This opens the Chat tab with a resume banner showing execution context.
•Uses --resume {session_id} for native session continuity.

Session Management

•Sessions persist across container restarts.
•Close a session: POST /api/agents/{name}/chat/sessions/{id}/close

API 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.

EndpointMethodDescription
/api/agents/{name}/chatPOSTSend chat message (stream-json output). The response's execution.compaction reports an auto-compaction during the turn, or is null
/api/agents/{name}/chat/sessionsGETList all sessions
/api/agents/{name}/chat/sessions/{id}GETGet session with messages
/api/agents/{name}/chat/sessions/{id}/closePOSTClose session
/api/agents/{name}/chat/history/persistentGETGet persistent history
/api/agents/{name}/chat/historyGETThe agent's current /chat conversation
/api/agents/{name}/chat/historyDELETEReset the /chat conversation so the next turn starts fresh (owner or admin)
/api/agents/{name}/executions/{id}/terminatePOSTStop 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.

See Also

•Continuous Conversations — what resuming preserves, auto-compact, and the per-turn iteration cap
•Workspace — the chat surface that keeps working memory across turns
•Voice Chat — the real-time call, started from the Workspace composer