Review: adk.dev, and what Marg takes from it

October 2026. A study of Google's Agent Development Kit site (adk.dev) as the reference for how a well-run agent framework presents itself, what it offers, and how it solves the developer's problem. The second half is Marg's response: what to add, what to change, what to leave alone. This note feeds ROADMAP.md, "0.3 — the surface".

1. What adk.dev is

One sentence, one button, code above the fold. The home page says "Build production agents, not prototypes", one line of subtitle (open source, build/debug/deploy, five languages), a single "Start building" button, then a tabbed code block (Python, TypeScript, Go, Java, Kotlin) with the install one-liner under it. Nothing else competes for attention. Below: four feature sections, each a pill label, a headline, a paragraph, a "Learn more" and a visual; then community, then an FAQ. Light, Material-style typography, lots of white space, a purple accent, a search box in the header. It is built on MkDocs Material.

The documentation is the product. The left nav has six top-level groups: Build Agents (get started per language, tutorials, agents, workflows, models), Run Agents (runtime, the web UI, CLI, API server, deployment, observability, evaluation, safety), Components (tools, skills, callbacks, plugins, context, sessions, memory, A2A), Live and Voice, Grounding, Integrations, Reference (API per language, CLI, config, REST, release notes), Community. Every page carries a "Supported in ADK: Python vX · TypeScript vY" badge and, where it applies, an "Experimental" label with a feedback link. Each section ends with "Next: …".

What it offers, in Marg's terms.

adk.dev	What it is	Marg today
Agents, workflow agents, graph workflows	LLM agents plus deterministic orchestration (sequential, loop, parallel, graph with routes)	one job shape: collect → validate → confirm → write; the super agent routes between domains
Tool confirmation, human input nodes	a tool pauses for a yes/no or structured input; "experimental"; the model asks, a dialog answers	the runtime owns the moments (forms, chips, pickers, summary, create gate), reads by whole content, three-fold write gate, measured on a blind corpus
Models	pages per provider: Gemini, Gemma, Claude, OpenAI, Ollama, vLLM, LiteLLM, model routing	Anthropic, any OpenAI-compatible endpoint (presets), a scripted mock; one env line to switch; no per-provider pages
adk web dev UI	chat, sessions, state inspection, event history, trace view, run evals from the UI	the playground: chat, past chats, a live draft pane; no trace or step/decision inspection
adk run, API server	CLI chat, a REST server	npm run gateway; no CLI binary (until marg-gateway)
Evaluation	trajectory + final response, test files, eval sets, rubric and LLM-judged criteria, user simulation, conformance tests, CI	scripted scenarios against a writes-off gateway with deterministic checks; a scripted mock model for the model's side; flake classification; a gate in CI with no key
Skills	an Agent Skill spec, loaded incrementally into context	markdown skills per domain and shared skills; the same idea, earlier
Agent Config (YAML)	build an agent without code	domain.json + skills in markdown: a domain is a folder; steps are the only code
Agents CLI	"build agents with agents": skills for Claude Code / Codex / Antigravity that scaffold, test, evaluate and deploy	CLAUDE.md for working on Marg itself; nothing that teaches a coding agent to build a domain
Deploy	Cloud Run, GKE, Agent Runtime (managed)	a Dockerfile, Compose profiles, Caddy, a Render blueprint
Observability	logging, metrics, traces pages; many APM integrations	OpenTelemetry in the GenAI conventions, OpenObserve dashboards and alerts as code
Integrations	~100 partner pages (stores, observability, guardrails, data, voice)	none listed
Reference	API docs per language, CLI, REST, release notes	docs/ markdown; the client protocol; no generated API reference
Community	contributing guide, community calls, developer resources	CONTRIBUTING, Discussions on

2. How it solves the developer's problem, and how it communicates it

• Time to first agent is minutes, in every language, and the path is identical: install, one file, adk web. The web UI is the feedback loop: you see events, state and the trace without adding code.
• The breadth is the promise: whatever you need next has a page. The cost is that the pages read as a catalogue; the "why this and not a prompt" argument is thin, and the parts that matter most for a transaction (confirmation, human input) are experimental and model-driven.
• It sells safety by vocabulary ("production", "reliable", "enterprise scale") rather than by evidence. There is no number on the home page.
• "Build agents with agents" is the newest message: the coding agent is the user, so the framework ships skills for it.
• Every page is dated by support: "Supported in Python v1.14, TypeScript v0.2" tells the reader what works where before they read a word.

3. What Marg should do differently, and what it should copy

Keep the wedge, say it louder. Marg is not a general agent framework and should not grow into one. Its claim is narrow and backed by numbers: the runtime owns the moments that cost when wrong, reads replies by their whole content, gates the write three times, and proves all of it offline. adk.dev's confirmation story is the gap Marg exists to fill; the comparison page should say so plainly, with the 235-of-521 number next to it.

Copy the surface. The parts of adk.dev that make adoption easy are not framework features, they are presentation: a site with a landing page and search, a nav that answers "where do I start, where do I go next", support badges, an FAQ, a dev UI that shows what happened. Marg's docs are complete and well written, and nobody can find them. That is the cheapest, largest improvement available.

Make the playground the dev UI. The playground already shows the draft filling itself; it should also show the trace: the route decision and its confidence, each step's state, every tool call with its arguments and result, the model's share of the turn. That is what adk web offers and what a developer debugging a step needs. Its visual design should be as plain as adk.dev's: one column of conversation, the draft and the trace as side panes that collapse, suggested openers on the empty state, no sidebar of past chats stealing a quarter of the screen.

Build domains with agents. Marg's build order (tools → probe → schema → skill → steps → evals) is already a procedure; written as a skill for Claude Code and Codex, a coding agent can scaffold and finish a domain. create-marg-app gives the project; the skill gives the method.

One command. npm run gateway, npm run new-domain -- …, npm run evals, npm run verdict become marg web, marg new, marg evals, marg verdict, in a marg CLI on npm, the way adk is. The scripts stay for the repository.

Say what works where. A "since" line on every doc page (core 0.2, gateway 0.2 …) and an "experimental" label where it applies.

Leave alone. Graph workflows, A2A, live audio, visual builders, a hundred integrations: not Marg's job. Marg plugs into those ecosystems through MCP and the client protocol; the docs should show how (a page on using Marg tools from another framework, a page on a Marg domain behind an A2A card), not reimplement them.

4. The resulting scope — ROADMAP "0.3 — the surface"

In order of leverage:

1. The site. VitePress, GitHub Pages, marg-adk.github.io/marg: a landing page in adk.dev's shape (one sentence, one button, the GIF, the quickstart in tabs, four feature sections, the numbers, an FAQ), the existing docs reorganised into Get started · Build · Components · Run · Deploy · Reference · Community, search, support badges, the comparison page. Built and deployed by CI on every merge to main.
2. The playground as the dev UI. A redesign: one centred conversation, collapsible draft and trace panes, suggested openers, a clean header, mobile first. The trace pane: route decision, steps state, tool calls with arguments and results, model turns, timings, from the gateway's existing per-turn data plus one new endpoint where needed. The widget's own look follows.
3. The marg CLI. marg web | new | evals | verdict | check, one package, wrapping what the scripts do; create-marg-app wires it into the new project.
4. A skill for coding agents. skills/build-a-domain/SKILL.md, installable into Claude Code and Codex: the worksheet, the build order, the gate, the classification rule.
5. Provider and integration pages. One page per model provider with the env lines; a page per store, observability backend and voice provider Marg supports; a "use Marg from another framework" page.
6. Evals: user simulation. A scripted or model-played user for scenarios that need free text beyond the mock policy, with the same deterministic checks.

Items 4–6 of 0.2 (the bookings example, the English core with lexicons, the Python template) keep their place; the site ships before them because it multiplies everything after it.

---

Source: docs/reviews/adk-dev-2026-10.md — edit it there; the site mirrors the repository.