adk-agent

termchart ADK agent

A standalone Google ADK agent that listens to one termchart viewer console scope and responds — by rendering/updating the diagram on the canvas and posting a short text reply in the console log.

It's an alternative to driving termchart from a coding harness (Claude Code / agy) via the termchart CLI: instead of a harness reading the inbox and pushing diagrams, this is a small, purpose-built Python process that does it for one scope. Use it as a runnable reference and customize the prompt + tools for your own agent.

How it works

human types in the console ──▶ GET /inbox (long-poll)  ──▶ ADK agent (Gemini) runs a turn
                                                              │  render_diagram / patch_diagram
                                                              │  suggest_chips / set_status   ──▶ canvas
                                                              ▼
        incoming text reply  ◀── POST /inbox (kind=message) ── the agent's final answer

• The listener long-polls GET /inbox for its project/agent scope (the same endpoint the CLI's inbox --follow uses), with the CLI's resilience: back off 1s→2s→…→15s on transient errors, exit on a 4xx, advance the cursor each healthy round.
• Each human message (or clicked chip) runs one ADK turn. The model calls tools that hit the viewer's HTTP API to render/patch/suggest/status, then its final text is posted back into the console as a reply (a tokenless POST /inbox).
• Reading the inbox marks it read (no peek), so the human sees "Read by the agent ✓".
• Loop-back guard: the agent's own replies land in the same inbox it polls, so it records each reply's seq and skips it on the next read — it never responds to itself.
• Scope discipline: it only ever acts on its one configured scope.

Prerequisites

• Python 3.11+ and uv.
• A running termchart viewer (termchart serve, or a deployed …/w/<wsid> workspace).
• For the default Vertex AI backend: Application Default Credentials — gcloud auth application-default login — plus a GCP project/location.

Setup

cd integrations/adk-agent
cp .env.example .env        # then edit .env
uv sync

Fill in .env:

Variable	Required	Notes
TERMCHART_VIEWER_URL	yes	Viewer base including /w/<wsid>
TERMCHART_VIEWER_TOKEN	for rendering	Bearer token; unset ⇒ the agent can only post text replies
TERMCHART_PROJECT / TERMCHART_AGENT	yes	The single scope to listen on
GOOGLE_GENAI_USE_VERTEXAI	1 (default)	Use Vertex AI
GOOGLE_CLOUD_PROJECT	for Vertex	Read from your env via ADC — never hardcode/commit a real id
GOOGLE_CLOUD_LOCATION	for Vertex	e.g. us-central1
GEMINI_API_KEY	fallback	Used only if GOOGLE_GENAI_USE_VERTEXAI=0
TERMCHART_ADK_MODEL	no	Defaults to a flash-tier model (low latency); override freely

Run

uv run termchart-adk

You'll see a redacted startup line (scope=… · Vertex AI · project=… · model=…) and following <scope>…. Open the viewer, toggle the console on, select the same scope, and type a message — the diagram appears and a reply lands in the log.

--project / --agent / --model override the env; --once runs a single poll round (for smoke testing).

Customize

• src/termchart_adk/prompts.py — the system instruction + the compact diagram cheat-sheet.
• src/termchart_adk/tools.py — the tools the model can call. Add your own (each is a typed async function with a docstring) and they become available to the agent.

Develop

uv run pytest          # fast, hermetic (mocked HTTP + a scripted runner; no network, no LLM)
uv run ruff check .
uv run mypy src

Troubleshooting

• "no TERMCHART_VIEWER_TOKEN configured" — set the token to enable rendering; without it the agent still posts text replies.
• ADC errors at the first model call — run gcloud auth application-default login and set GOOGLE_CLOUD_PROJECT / GOOGLE_CLOUD_LOCATION (or switch to GEMINI_API_KEY).
• config: … then exit — a required variable is missing; the message names it.
• reconnecting in Ns… — the viewer was briefly unreachable; the listener retries with backoff and recovers on its own.