Chat is the main interface for business users and operators who interact with agents. Use chat to send prompts, receive streamed responses, and review previous conversations.

Start a conversation

Open:
Existing conversations use:

Agent selection and deployment status

On the bottom composer toolbar of the chat interface, the agent picker chip displays which agent will receive your next turn. Agents in the selector display a leading deployment stage icon before their name (<icon> Agent Name):
  • 🟢 Production: Officially verified and supported for production use.
  • 🟡 Staging: Candidate version under internal testing.
  • 🧪 Experimental: Prototype or testing configuration.
Click the chip to switch active agents from the searchable dropdown.

What happens during a run

  1. You send a message.
  2. The frontend sends the request to the backend.
  3. The backend runs the configured ADK agent.
  4. The frontend renders the streamed response.

Response formats: Streaming SSE, Blocks, OpenUI, and Full JSON

By default, conversation messages stream responses incrementally using Server-Sent Events (SSE). Callers can control the response mode and structured content format by passing the X-Pinter-Response-Format header on POST /api/conversations/{conversationId}/messages:

Supported header values

Blocks response format (blocks)

When X-Pinter-Response-Format: blocks is supplied, Pinter injects envelope instructions into the model prompt to structure output into self-contained block objects:

Supported Block Types:

  • markdown: Text and narrative prose. Text between non-text block lines is implicitly handled as markdown.
  • flint_chart: Self-contained ChartAssemblyInput JSON specifying chart type (Bar Chart, Line Chart, Pie Chart, Heatmap, Sankey, etc.), data rows, and encodings. See Flint chart artifacts.
  • html: Standalone HTML document (<!DOCTYPE html>...) styled with Tailwind CSS and optional Chart.js for custom visual widgets.
  • image: Image artifact containing an image URL in content.
  • followup: An array of up to 4 unique, context-grounded next-step exploration questions or action suggestions (maximum 120 characters each) emitted as the final block of the response.

OpenUI response format (blocks,openui)

OpenUI is opt-in. Send both tokens and the model may return UI component definitions in a fenced openui-lang block inside ordinary prose:
Rules that matter when integrating:
  • Tokens are comma-separated and case-insensitive. blocks, OpenUI behaves the same as blocks,openui.
  • openui alone does not enable blocks, so a client that only opts into OpenUI never receives block events it cannot render.
  • json wins: json,openui returns a collected JSON response with no OpenUI prompt injection.
  • OpenUI never becomes a block type. It stays plain text inside delta, so clients that do not render it can strip the fence or show it as a code block.
  • The OPENUI_ENABLED server flag is a kill switch; when it is false, the token is accepted but ignored.
  • The fence may be unterminated while streaming. Parse and validate after the stream ends.

Embedded chat

Pinter also has embedded chat routes for surfaces that host chat inside another application:

Human-in-the-Loop (HITL) tool approval

For operations that modify resources, invoke external side effects, or incur computational costs, Pinter intercepts tool execution using a Human-in-the-Loop (HITL) security gate built on Google ADK’s native tool confirmation mechanism.

When tool approval is required

The runtime evaluates every candidate tool call in before_tool_callback prior to PII rehydration. An action requires confirmation if it meets any of the following criteria:
  • Action prefixes: Any tool whose name starts with create_, update_, delete_, run_, or add_ (e.g., create_agent, update_agent, delete_asset, run_eval, add_test_case). This applies to MCP tools too.
  • Database queries: query_snowflake calls that are non-read-only (not starting with SELECT, WITH, SHOW, DESCRIBE, or EXPLAIN), or queries containing multi-statement semicolons.
All other tools, including MCP tools and api_request, run without confirmation. There is no per-tool allow or deny list; the rule is the name prefix plus the query_snowflake check.

Approval mode

The gate only applies when the turn runs in approval mode. Both POST /send and POST /approvals/{approvalId} accept an approval_mode field: The chat UI always sends its own choice and starts in approval. When the field is omitted, the backend uses full-access, so API clients that want the gate must send approval on every turn. The mode is rewritten on every turn and never persists on the session. An explicit answer to a pending approval is always honored, so a rejection still blocks the tool in full-access.

Protocol lifecycle: Pause and resume

  1. Pause: When a risky tool is detected, approval_gate invokes tool_context.request_confirmation(hint=...) and marks actions.skip_summarization = True. ADK yields an adk_request_confirmation event, triggering an approval_required SSE event to the client:
    The backend suppresses premature empty-turn messages and avoids emitting raw protocol events.
  2. Resume: The client sends the decision via:
    When the agent pauses on several tool calls at once, answer all of them in one request. Put one decision in approved and the rest in decisions ([{ "approval_id": "...", "approved": false }]). The run resumes once, after every decision is applied. A listed approval that is missing (404) or already resolved (409) rejects the whole request.
  3. In-place continuation: The backend resumes the session with an ADK FunctionResponse. Execution details and tool results update the existing assistant message row in-place (update_assistant_turn), so the entire interaction lives in a single, cohesive chat bubble without synthetic messages.

Reading responses

Agent responses may include markdown, citations, tool output, execution details, or Flint chart artifacts depending on backend configuration. See Flint chart artifacts for the supported chart types, required encodings, examples, and compatibility aliases.
If a response looks incomplete, check backend connectivity and whether the conversation stream closed early.

Inspect execution traces

Each agent response can show an inline trace above the message. Expand it to see how the agent produced the answer:
  • Model reasoning steps.
  • Tool calls and their results.
  • Sub-agent transfers in multi-agent workflows.
Traces come from the backend trace store:
Use traces to diagnose wrong answers: check whether the agent called the expected tool and whether the tool returned useful data before blaming the model or the instruction.