ADR-070: ADK (Agent Development Kit) Integration

Status

Accepted - January 13, 2026

Track: T.2 - External Tools Integration

Context

Problem Statement

CODITECT has 150+ agents defined in markdown, but lacks:

Multi-Agent Orchestration - No native patterns for sequential, parallel, or hierarchical agent coordination
Standardized Evaluation - No built-in framework for testing agent accuracy and reliability
Remote Agent Communication - No protocol for agent-to-agent communication across trust boundaries
Code-First Development - Agents are markdown-defined, not programmatically composable

Solution: Google ADK

Agent Development Kit (ADK) is Google's open-source, code-first Python framework for building, evaluating, and deploying sophisticated AI agents.

Key Features:

Feature	Description
Code-First	Define agent logic in Python for flexibility and testability
Multi-Agent Patterns	Sequential, Parallel, Loop, and Hierarchical orchestration
Rich Tool Ecosystem	50+ tools including Google APIs, OpenAPI, MCP
Evaluation Framework	Built-in testing with metrics and CI/CD integration
A2A Protocol	Agent-to-Agent communication for remote agents
A2UI Integration	Generate rich UIs via companion A2UI standard
Model-Agnostic	Works with Gemini, Claude, GPT, and others

ADK Version

Current: Latest from main branch (15.6K+ stars)
PyPI: pip install google-adk
Submodules: adk-python, adk-samples

Decision

Integrate ADK as the agent orchestration and evaluation backbone for CODITECT, enabling:

CODITECT ↔ ADK Agent Bridge - Convert markdown agents to ADK format
Multi-Agent Workflows - Use ADK patterns for complex orchestration
Agent Evaluation - Built-in testing and quality gates
A2A Protocol - Remote agent communication
Integration with A2UI - Rich UI responses (see ADR-069)

Integration Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                      CODITECT + ADK INTEGRATION                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    CODITECT Agent Definitions                        │   │
│  │                    (agents/*.md - 150+ agents)                       │   │
│  └───────────────────────────────┬─────────────────────────────────────┘   │
│                                  │                                          │
│                                  ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                    adk-coditect-adapter.py                           │   │
│  │                    Converts markdown → ADK Python                    │   │
│  └───────────────────────────────┬─────────────────────────────────────┘   │
│                                  │                                          │
│                                  ▼                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         ADK Agent Types                              │   │
│  │                                                                      │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │   │
│  │  │  LlmAgent   │  │ Sequential  │  │  Parallel   │  │   Loop      │ │   │
│  │  │             │  │   Agent     │  │   Agent     │  │   Agent     │ │   │
│  │  │ Single LLM  │  │  Pipeline   │  │  Fan-out    │  │  Iterative  │ │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘ │   │
│  └───────────────────────────────┬─────────────────────────────────────┘   │
│                                  │                                          │
│         ┌────────────────────────┼────────────────────────┐                │
│         │                        │                        │                 │
│         ▼                        ▼                        ▼                 │
│  ┌─────────────┐         ┌─────────────┐         ┌─────────────┐           │
│  │   Runner    │         │  Evaluator  │         │ A2A Client  │           │
│  │ Orchestrate │         │  Test/QA    │         │ Remote Comm │           │
│  └─────────────┘         └─────────────┘         └─────────────┘           │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

ADK Core Concepts

Agent Types

Agent Type	Class	Use Case	Example
LLM Agent	`LlmAgent`	Single agent with LLM reasoning	Chat assistant, code reviewer
Sequential Agent	`SequentialAgent`	Ordered pipeline	Research → Analyze → Report
Parallel Agent	`ParallelAgent`	Concurrent execution	Multi-source search
Loop Agent	`LoopAgent`	Iterative refinement	Quality improvement until threshold
Hierarchical	`LlmAgent` with `sub_agents`	Delegation pattern	Coordinator → Specialists

Agent Definition

from google.adk.agents import Agent, LlmAgent

# Simple agent
search_agent = Agent(
    name="search_assistant",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant that searches for information.",
    description="An assistant that can search the web.",
    tools=[google_search, web_fetch]
)

# Agent with sub-agents (hierarchical)
coordinator = LlmAgent(
    name="coordinator",
    model="gemini-2.5-flash",
    instruction="Delegate tasks to appropriate specialists.",
    sub_agents=[research_agent, writer_agent, editor_agent]
)

Multi-Agent Patterns

Sequential Pipeline

from google.adk.agents import SequentialAgent

research_pipeline = SequentialAgent(
    name="research_pipeline",
    agents=[
        researcher,   # Step 1: Gather information
        analyzer,     # Step 2: Analyze findings
        reporter,     # Step 3: Generate report
    ]
)

Parallel Fan-Out

from google.adk.agents import ParallelAgent

comprehensive_search = ParallelAgent(
    name="multi_search",
    agents=[
        web_search_agent,
        document_search_agent,
        code_search_agent,
    ]
)

Iterative Loop

from google.adk.agents import LoopAgent

quality_loop = LoopAgent(
    name="quality_refinement",
    agent=editor_agent,
    max_iterations=5,
    stop_condition="quality_score >= 0.9"
)

Runner (Orchestration Engine)

The Runner manages agent execution lifecycle:

from google.adk import Runner

runner = Runner(agent=my_agent)

# Synchronous execution
response = runner.run(
    session_id="session-123",
    message="What is the weather in NYC?"
)

# Asynchronous execution
async for event in runner.run_async(session_id="session-123", message="..."):
    print(event)

# Live bidirectional streaming
async for event in runner.run_live(session_id="session-123"):
    # Audio/video streaming with Gemini Live
    pass

Evaluation Framework

from google.adk.evaluation import Evaluator, EvalDataset

# Load dataset
dataset = EvalDataset.from_file("eval_datasets/test_set.json")

# Create evaluator
evaluator = Evaluator(
    agent=my_agent,
    dataset=dataset,
    metrics=["accuracy", "tool_accuracy", "latency"]
)

# Run evaluation
results = await evaluator.run()

print(f"Accuracy: {results.accuracy:.2%}")
print(f"Tool Accuracy: {results.tool_accuracy:.2%}")
print(f"Avg Latency: {results.avg_latency:.0f}ms")

A2A Protocol (Agent-to-Agent)

from google.adk.a2a import A2AClient

# Connect to remote agent
remote_agent = A2AClient(
    url="https://travel-agent.example.com",
    auth_token="..."
)

# Send task (may return A2UI response)
response = await remote_agent.send_task(
    task="Book a flight from SFO to JFK",
    context={"date": "2026-01-20"}
)

CODITECT Components

Created Components (T.2)

Type	Component	Purpose
Agent	`adk-orchestrator`	Multi-agent coordination using ADK patterns
Agent	`adk-agent-builder`	Build ADK agents from specifications
Skill	`adk-evaluation`	Evaluate agent performance
Skill	`adk-tool-integration`	Integrate tools with ADK agents
Command	`/adk-eval`	Run agent evaluations
Command	`/adk-run`	Execute ADK agents
Hook	`adk-agent-structure-validation`	Validate ADK agent directory structure
Workflow	`adk-agent-development`	End-to-end ADK development workflow
Script	`adk-coditect-adapter.py`	Convert CODITECT agents to ADK format

CODITECT ↔ ADK Agent Mapping

CODITECT Agent	ADK Pattern	Use Case
`senior-architect`	Hierarchical coordinator	System design, delegation
`testing-specialist`	LoopAgent	Iterative QA until quality threshold
`devops-engineer`	SequentialAgent	Build → Test → Deploy pipeline
`research-analyst`	ParallelAgent	Multi-source information gathering
`codi-documentation-writer`	LlmAgent	Single-purpose documentation

Usage Examples

Orchestrate Research Workflow

/agent adk-orchestrator "Coordinate research: parallel web/doc search, then sequential analysis and reporting"

Build Deployment Pipeline

/agent adk-orchestrator "Create sequential pipeline: lint → test → build → deploy with rollback"

Evaluate Agent Quality

/adk-eval agents/search-assistant eval_datasets/search_tests.json --min-accuracy 0.85

Convert CODITECT Agent to ADK

python scripts/adk-coditect-adapter.py convert agents/senior-architect.md --output adk_agents/

ADK Source Structure

adk-python/src/google/adk/
├── agents/              # Agent implementations
│   ├── base_agent.py    # BaseAgent class
│   ├── llm_agent.py     # LlmAgent (primary)
│   ├── loop_agent.py    # LoopAgent (iterative)
│   ├── parallel_agent.py # ParallelAgent (concurrent)
│   └── sequential_agent.py # SequentialAgent (pipeline)
├── runners.py           # Core orchestration engine
├── tools/               # 50+ tool integrations
│   ├── google_api_tool/ # Google APIs
│   ├── openapi_tool/    # OpenAPI specs
│   └── mcp_tool/        # Model Context Protocol
├── models/              # LLM integrations
│   ├── gemini/          # Gemini models
│   ├── anthropic/       # Claude integration
│   └── litellm/         # Multi-provider
├── evaluation/          # Evaluation framework
│   ├── evaluator.py     # Main evaluator
│   ├── metrics/         # Built-in metrics
│   └── datasets/        # Dataset handling
├── sessions/            # Session management
├── memory/              # Long-term memory
├── a2a/                 # Agent-to-Agent protocol
├── cli/                 # CLI tools
└── telemetry/           # Observability

ADK Samples

40+ sample agents in adk-samples:

Sample	Category	Description
`hello_world`	Getting Started	Basic agent
`customer_service`	Enterprise	Support chatbot
`data_science`	Analysis	Data analysis agent
`travel_booking`	Multi-agent	A2A + A2UI integration
`code_assistant`	Development	Code generation
`rag_agent`	RAG	Retrieval-augmented agent
`multi_tool_agent`	Tools	Tool orchestration

Implementation

Phase 1: Foundation (Complete)

Phase 2: Agent Conversion (Planned)

Convert core CODITECT agents to ADK format
Build agent registry with ADK metadata
Create ADK test datasets for CODITECT agents
Implement evaluation CI/CD pipeline

Phase 3: Orchestration (Planned)

Build multi-agent workflow templates
Integrate with CODITECT task tracking
Add A2A support for remote CODITECT agents
Create visual workflow editor

Phase 4: Production (Planned)

Deploy ADK agents to Vertex AI
Integrate with CODITECT Cloud backend
Add production monitoring (telemetry)
Build customer-facing agent builder UI

Configuration

ADK Installation

# Install ADK
pip install google-adk

# Or from source
pip install git+https://github.com/google/adk-python.git@main

ADK CLI Commands

# Run agent
adk run agents/my_agent --message "Hello"

# Start web UI
adk web agents/my_agent --port 8080

# Evaluate agent
adk eval agents/my_agent eval_datasets/test.json

# Create new agent
adk create my_new_agent

CODITECT Configuration

File: ~/.coditect/config/adk.json

{
  "adk": {
    "default_model": "gemini-2.5-flash",
    "agents_path": "~/.coditect/adk_agents/",
    "eval_datasets_path": "~/.coditect/eval_datasets/",
    "evaluation": {
      "min_accuracy": 0.85,
      "metrics": ["accuracy", "tool_accuracy", "latency"],
      "parallel_workers": 4
    },
    "a2a": {
      "enabled": true,
      "auth_method": "oauth2"
    }
  }
}

Consequences

Positive

Multi-Agent Orchestration - Sequential, Parallel, Loop, Hierarchical patterns
Code-First Development - Python-based agent definitions
Built-in Evaluation - Testing framework with metrics and CI/CD
A2A Protocol - Remote agent communication
A2UI Integration - Rich UI responses (ADR-069)
Model-Agnostic - Works with Gemini, Claude, GPT
50+ Tools - Rich tool ecosystem
Production Ready - Deploy to Cloud Run, Vertex AI
Community - 15.6K+ stars, active development

Negative

Python Dependency - Requires Python 3.10+ runtime
Learning Curve - New patterns for existing CODITECT users
Conversion Effort - 150+ agents to convert (gradual)
Complexity - Multi-agent systems add orchestration complexity

Neutral

Dual System - CODITECT markdown + ADK Python coexist
Version Management - ADK evolves rapidly (bi-weekly releases)
Google Ecosystem - Optimized for Gemini, but model-agnostic

Alternatives Considered

Option A: Build Custom Orchestration (Rejected)

Effort: 6-12 months development Reason: ADK provides mature orchestration patterns; no need to reinvent

Option B: LangChain Integration (Rejected)

Issue: Different abstraction level, heavier dependency Reason: ADK is more focused on agent orchestration, cleaner integration

Option C: AutoGen (Rejected)

Issue: Microsoft-specific, different multi-agent approach Reason: ADK's patterns align better with CODITECT architecture

Option D: CrewAI (Rejected)

Issue: Less mature, smaller ecosystem Reason: ADK has larger community, better Google integration

Submodules:
- submodules/tools/adk-python/
- submodules/tools/adk-samples/
Agents:
- agents/adk-orchestrator.md
- agents/adk-agent-builder.md
Skills:
- skills/adk-evaluation/SKILL.md
- skills/adk-tool-integration/SKILL.md
Commands:
- commands/adk-eval.md
- commands/adk-run.md
Hook: hooks/adk-agent-structure-validation.md
Workflow: workflows/devops/adk-agent-development.yaml
Script: scripts/adk-coditect-adapter.py
Track: internal/project/plans/2026-01-13T05-27-27Z-pilot-tracks/TRACK-T-TOOLS.md
ADR-069: A2UI Integration (companion ADR)

Appendix

A. ADK Agent Directory Structure (Required)

my_agent/
├── __init__.py      # MUST contain: from . import agent
└── agent.py         # MUST define: root_agent = Agent(...) OR app = App(...)

B. Evaluation Dataset Format

[
  {
    "input": "What is the capital of France?",
    "expected_output": "Paris",
    "expected_tool_calls": [],
    "tags": ["geography", "simple"]
  },
  {
    "input": "Book a flight from SFO to JFK",
    "expected_output": null,
    "expected_tool_calls": ["search_flights", "book_flight"],
    "expected_tool_args": {
      "search_flights": {"origin": "SFO", "destination": "JFK"}
    },
    "tags": ["booking", "multi-tool"]
  }
]

C. CODITECT to ADK Conversion Example

Input (CODITECT markdown):

---
title: Code Reviewer
model: sonnet
tools: Read, Write, Edit
---

# Code Reviewer Agent

Review code for quality, security, and best practices.

Output (ADK Python):

from google.adk.agents import Agent
from google.adk.tools import read_file, write_file, edit_file

root_agent = Agent(
    name="code_reviewer",
    model="claude-sonnet-4",
    instruction="Review code for quality, security, and best practices.",
    description="Code review agent for CODITECT",
    tools=[read_file, write_file, edit_file]
)

D. Quick Reference

# Install ADK
pip install google-adk

# Run agent
adk run agents/my_agent --message "Hello"

# Evaluate agent
adk eval agents/my_agent eval_datasets/test.json

# Web UI
adk web agents/my_agent

# CODITECT commands
/adk-eval agents/search-assistant tests.json
/adk-run agents/my_agent "Task description"
/agent adk-orchestrator "Create multi-agent workflow"

E. ADK Ecosystem Links

Resource	URL
Documentation	https://google.github.io/adk-docs
Python ADK	https://github.com/google/adk-python
Samples	https://github.com/google/adk-samples
Java ADK	https://github.com/google/adk-java
Go ADK	https://github.com/google/adk-go
ADK Web	https://github.com/google/adk-web
A2A Protocol	https://github.com/google-a2a/A2A
A2UI	https://github.com/google/A2UI

Author: CODITECT Integration System Track: T.2 - ADK Integration Repository: google/adk-python

Status​

Context​

Problem Statement​

Solution: Google ADK​

ADK Version​

Decision​

Integration Architecture​

ADK Core Concepts​

Agent Types​

Agent Definition​

Multi-Agent Patterns​

Sequential Pipeline​

Parallel Fan-Out​

Iterative Loop​

Runner (Orchestration Engine)​

Evaluation Framework​

A2A Protocol (Agent-to-Agent)​

CODITECT Components​

Created Components (T.2)​

CODITECT ↔ ADK Agent Mapping​

Usage Examples​

Orchestrate Research Workflow​

Build Deployment Pipeline​

Evaluate Agent Quality​

Convert CODITECT Agent to ADK​

ADK Source Structure​

ADK Samples​

Implementation​

Phase 1: Foundation (Complete)​

Phase 2: Agent Conversion (Planned)​

Phase 3: Orchestration (Planned)​

Phase 4: Production (Planned)​

Configuration​

ADK Installation​

ADK CLI Commands​

CODITECT Configuration​

Consequences​

Positive​

Negative​

Neutral​

Alternatives Considered​

Option A: Build Custom Orchestration (Rejected)​

Option B: LangChain Integration (Rejected)​

Option C: AutoGen (Rejected)​

Option D: CrewAI (Rejected)​

Related Documents​

Appendix​

A. ADK Agent Directory Structure (Required)​

B. Evaluation Dataset Format​

C. CODITECT to ADK Conversion Example​

D. Quick Reference​

E. ADK Ecosystem Links​