Adk expert

ADK Expert

ADK is a mental model for agent composition, not a framework to learn. The patterns transfer to any orchestration foundation.

This skill covers how to think about agent boundaries, orchestration topology, and tool seams using Google ADK principles. It is not a tutorial on SDK methods — the official docs at adk.dev own that. This skill covers the architecture of agent systems.

When to use

• Designing a multi-agent system on Google ADK
• Deciding where to draw agent boundaries
• Choosing between orchestration topologies (supervisor-worker vs peer-to-peer vs sequential)
• Reviewing an existing ADK-based system for structural problems
• Integrating MCP servers or external tools into an ADK agent graph

Procedure

1. Verify current ADK documentation — before writing any agent topology or referencing API surface, fetch the latest docs from adk.dev. ADK evolves; training data lags.

2. Define agent responsibilities first — each agent in the system must have:

   • A single, nameable responsibility
   • A defined input contract (what it receives)
   • A defined output contract (what it produces)
   • A declared set of tools it may use (no raw DB access; use bounded tool seams)

3. Choose the orchestration topology:

   Topology	When to use	Trade-off
   Supervisor → Worker	Audit trails required; routing logic is complex	Adds latency; supervisor is a bottleneck
   Sequential pipeline	Tasks are strictly ordered; each step feeds the next	Simple but no parallelism
   Parallel fan-out	Independent sub-tasks that merge at a synthesis step	Fast; coordination overhead at merge
   Peer-to-peer	Speed over governance; tasks are loosely coupled	Hard to audit; compliance risk

4. Design the tool seams — tools are the boundary between an agent and the external world. Each tool should:

   • Have a typed schema (inputs and outputs)
   • Enforce the agent's permission scope (least-privilege)
   • Be independently testable
   • Return structured errors, not raw exceptions

5. Plan for agent failure — every agent in the graph must have a declared failure behaviour: retry, escalate to supervisor, return partial result, or halt. Unhandled agent failure silently corrupts downstream output.

6. Add observability at the boundary — log every agent invocation: agent name, input summary, output summary, latency, tool calls made. The agent graph is only debuggable if the boundary calls are visible.

7. Run the Adversarial Gate — before finalising the topology, invoke adversarial-gate on the design. Common failure modes: supervisor SPOF, context window overflow at the synthesis step, tool permission creep, silent agent loops.

Outputs

• Agent topology diagram (C4 component or sequence diagram)
• Agent responsibility matrix: agent | input | output | tools | failure behaviour
• Tool schema definitions (typed inputs/outputs)
• ADR for topology choice (via the-architect)

Guardrails

• The agent graph is not self-documenting. Name every agent, every tool, every edge. Implicit wiring creates invisible failure modes.
• No raw database access from agents. Agents call tools; tools call infrastructure. This boundary is the governance seam.
• Context window is finite. Design the graph so no single agent accumulates unbounded context. Summarise at synthesis points.
• Verify API surface before writing code. ADK API changes. Always ground against adk.dev before implementing.