Start a conversation
Open: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.
What happens during a run
- You send a message.
- The frontend sends the request to the backend.
- The backend runs the configured ADK agent.
- 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 theX-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-containedChartAssemblyInputJSON 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 incontent.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:
- Tokens are comma-separated and case-insensitive.
blocks, OpenUIbehaves the same asblocks,openui. openuialone does not enable blocks, so a client that only opts into OpenUI never receivesblockevents it cannot render.jsonwins:json,openuireturns 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_ENABLEDserver flag is a kill switch; when it isfalse, 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 inbefore_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_, oradd_(e.g.,create_agent,update_agent,delete_asset,run_eval,add_test_case). This applies to MCP tools too. - Database queries:
query_snowflakecalls that are non-read-only (not starting withSELECT,WITH,SHOW,DESCRIBE, orEXPLAIN), or queries containing multi-statement semicolons.
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 inapproval 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
- Pause: When a risky tool is detected,
approval_gateinvokestool_context.request_confirmation(hint=...)and marksactions.skip_summarization = True. ADK yields anadk_request_confirmationevent, triggering anapproval_requiredSSE event to the client:The backend suppresses premature empty-turn messages and avoids emitting raw protocol events. - 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
approvedand the rest indecisions([{ "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. - 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.