adk-dev-guide

ADK Development Guide

Development lifecycle guardrails for AI agents using Google ADK and Gemini models.

4-Phase Development Lifecycle

Every ADK agent feature follows this workflow. Skipping phases increases risk of eval failures, infinite loops, and deployment issues.

Phase 1: Understand Spec

Before writing any code:

• Read DESIGN_SPEC.md completely — this is the source of truth
• Identify: agent purpose, required tools, safety constraints, success criteria, edge cases
• Flag ambiguities, contradictions, or missing information before proceeding
• Check if similar agent patterns exist in your project already (avoid duplication)
• Clarify: is this a new agent or an enhancement to an existing one?

Stop if:

• The spec is vague or self-contradictory
• Required dependencies are unavailable
• The scope exceeds what a single agent should handle

Phase 2: Build

Follow these patterns:

• Use ToolContext for session state — never global variables
• Import tools with precision (see ADK Import Precision Rules section below)
• Add # Fallback: comment to every tool function
• Use InMemoryRunner for development and tests
• Development commands:
  • adk web — launch ADK playground for interactive testing
  • uv run pytest tests/ -v — run unit tests
  • uv run ruff check src/ && uv run ruff format src/ — lint and format
  • uv run mypy src/ — type check

Stop if:

• Type errors appear when running mypy
• Linting fails (ruff check returns non-zero)
• Unit tests fail

Phase 3: Evaluate

Iterate 5–10 rounds per feature:

• Create evalset.json with: 1 happy path, 1 error path, 1+ edge cases
• Create eval_config.json with appropriate eval criteria
• Run: adk eval ./app evalset.json --config_file_path=eval_config.json --print_detailed_results
• Review detailed results — identify failure patterns
• Refine agent instructions, tool signatures, or tool implementations
• Re-run until success rate stabilizes
• Common pitfalls: app name must match directory name, state type mismatches, tool return types