Google ADK Best Practices: Architecting Multi-Agent Systems with Explicit Tool Schemas

As autonomous AI agents shift from experimental scripts into enterprise production, engineering teams confront persistent issues with tool hallucinations, execution loops, and state corruption. Google’s Agent Development Kit (ADK) addresses these failure modes with a standardized framework for building resilient, deterministic multi-agent applications.

Drawing on ADK architectural patterns and production telemetry, this technical guide details core principles for multi-agent reliability. By establishing structured markdown prompt hierarchies, explicit JSON tool schemas, isolated execution contexts, and strict boundary controls, developers can eliminate infinite retry cascades and deploy dependable autonomous workflows.

Technical & Strategic Deep Dive

The fundamental failure mode of early autonomous agents was unconstrained natural-language planning. When an LLM is given broad permissions and vague instructions, it inevitably hallucinates non-existent parameters, gets trapped in recursive loops, or executes destructive side effects.

Google ADK resolves these issues through four core architectural pillars.

Structure Instructions Using Markdown Hierarchies

Large language models process markdown formatting (headers, bullet points, and code blocks) with significantly higher semantic fidelity than continuous blocks of unstructured text. Google ADK establishes a standardized three-section prompt specification:

# AGENT ROLE & OBJECTIVE
You are the Database Migration Chaperone for Useful AI News. Your sole responsibility is validating schema diffs and executing non-destructive SQL migrations.

# OPERATIONAL CONSTRAINTS
- NEVER execute DROP, TRUNCATE, or destructive ALTER statements without explicit two-man confirmation.
- ALWAYS execute a DRY RUN validation before committing transactions.
- Output all errors using the standardized ErrorEnvelope JSON schema.

# TOOL USAGE INSTRUCTIONS
Use `query_database` ONLY for read-only schema inspection.
Use `execute_migration` ONLY after `validate_diff` returns status: "PASSED".

Separating role definition from negative operational constraints prevents models from “forgetting” boundaries during extended multi-turn conversations.

Define Explicit JSON Tool Schemas with Type Safety

Never rely on natural-language descriptions to define tool parameters. Google ADK mandates strict schema validation using OpenAPI 3.0 or JSON Schema definitions. Every tool exposed to the model must specify required fields, data types, and allowed enum values:

{
"name": "fetch_llm_benchmarks",
"description": "Retrieves empirical latency and throughput benchmarks for a specific frontier model.",
"parameters": {
 "type": "object",
 "properties": {
   "model_slug": {
     "type": "string",
     "enum": ["gemini-3-8-flash", "claude-3-7-sonnet", "o3-mini"],
     "description": "The canonical identifier of the target model."
   },
   "metric_type": {
     "type": "string",
     "enum": ["ttft_ms", "tokens_per_sec", "swe_bench_score"],
     "description": "The target benchmark metric."
   }
 },
 "required": ["model_slug", "metric_type"]
}
}

By constraining inputs to concrete enums, the runtime engine intercepts malformed requests before they hit underlying backend services.

$ adk-runner validate --schema schemas/llm_benchmarks.json --strict-types
✓ Schema validation passed: OpenAPI 3.0 compliant
✓ Runtime boundaries: 3 worker agents registered (isolated context)
✓ Execution sandbox: Docker ephemeral container initialized (egress: disabled)
✓ Dispatching task: fetch_llm_benchmarks(model="gemini-3-8-flash")
[Response] Status: PASSED (latency: 138ms, validation_errors: 0)

Implement Few-Shot Demonstrations as Historical Turns

Placing long example demonstrations directly into the system instruction dilutes the model’s attention over long conversations. Google ADK recommends structuring few-shot demonstrations as synthetic historical user/assistant turns:

[
{"role": "user", "content": "Check database status for post 423."},
{"role": "assistant", "tool_calls": [{"name": "get_post_meta", "args": {"post_id": 423}}]},
{"role": "tool", "content": "{"id": 423, "status": "publish", "cached": true}"},
{"role": "assistant", "content": "Post 423 is currently published and served via edge cache."}
]

This teaches the model the exact expected calling pattern without cluttering the primary instruction context.

Enforce Boundary Isolation and Sub-Agent Delegation

Monolithic agents given access to dozens of tools suffer from context confusion and severe security risks. Google ADK establishes an orchestrator-subagent hierarchy:

1. Root Orchestrator: Handles user intent decomposition, routing, and synthesis. It possesses zero execution tools—only delegate_to_agent.
2. Specialized Worker Agents: Scoped to single operational domains (e.g., SQL execution, SEO metadata validation, cache purging) with minimal tool permissions and ephemeral context memory.

Updated on September 5, 2026