Google ADK (Agent Development Kit) - Architecture

Framework: Open-source by Google Version: 0.2.0+ Production: Powers Google Agentspace and CES Documentation: https://google.github.io/adk-docs/

---

🎯 What is Google ADK?

Agent Development Kit (ADK) is Google's open-source framework for developing and deploying AI agents.

Key Characteristics

• 🧠 Model-agnostic - Works with Gemini, OpenAI, Claude, Llama, etc.
• 🚀 Deployment-agnostic - Local, Vertex AI, Cloud Run, GKE, Kubernetes
• 🔧 Framework-compatible - Integrates with LangChain, CrewAI, custom tools
• 🏢 Production-ready - Battle-tested in Google products
• 🔄 Interoperable - Java and Python SDKs with identical APIs

---

🏗️ Core Architecture

┌─────────────────────────────────────────────────────┐
│                  Your Application                    │
│            (Clojure via Java interop)               │
└─────────────────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────┐
│                   Agent Layer                        │
│  ┌──────────┐  ┌──────────┐  ┌──────────────────┐ │
│  │   LLM    │  │ Workflow │  │  Multi-Agent     │ │
│  │  Agent   │  │  Agent   │  │    System        │ │
│  └──────────┘  └──────────┘  └──────────────────┘ │
└─────────────────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────┐
│                   Tool Ecosystem                     │
│  ┌─────────┐ ┌─────────┐ ┌────────┐ ┌──────────┐  │
│  │Built-in │ │ Custom  │ │ OpenAPI│ │Third-party│  │
│  │ Tools   │ │Functions│ │  Tools │ │   (LC)    │  │
│  └─────────┘ └─────────┘ └────────┘ └──────────┘  │
└─────────────────────────────────────────────────────┘
                         │
                         ↓
┌─────────────────────────────────────────────────────┐
│                    LLM Layer                         │
│        Gemini | Claude | GPT | Open Models          │
└─────────────────────────────────────────────────────┘

---

🤖 Agent Types

1. LLM Agent (Dynamic Routing)

Concept: Agent uses LLM to make decisions about which actions to execute.

When to use:

• ✅ Adaptive behavior based on context
• ✅ Multiple tools available
• ✅ Complex decisions required
• ✅ Unpredictable input patterns

Clojure Example:

(ns lab.agents.llm-agent
  "LLM Agent with dynamic tool selection"
  (:import [com.google.adk.agent LLMAgent]
           [com.google.adk.model GeminiModel]
           [com.google.adk.tool Tool]))

(defn create-calculator-tool
  "Custom calculator tool"
  []
  (-> (Tool/builder)
      (.setName "calculator")
      (.setDescription "Performs basic arithmetic operations")
      (.setFunction
        (reify java.util.function.Function
          (apply [_ input]
            ;; Parse and execute calculation
            (str "Result: " (eval (read-string input))))))
      (.build)))

(defn create-llm-agent
  "Creates LLM agent with tools"
  [tools]
  (-> (LLMAgent/builder)
      (.setModel
        (-> (GeminiModel/builder)
            (.setModelName "gemini-1.5-flash")
            (.setTemperature 0.7)
            (.build)))
      (.addTools tools)
      (.setSystemPrompt "You are a helpful assistant with access to tools.")
      (.build)))

;; REPL Usage
(comment
  (def tools [(create-calculator-tool)])
  (def agent (create-llm-agent tools))

  (.execute agent "What is 25 * 4?")
  ;; Agent decides to use calculator tool
  ;; => "The result is 100"
  )

Flow:

Input → LLM decides → Selects Tool → Executes → LLM synthesizes → Output

---

2. Workflow Agents (Structured)

2.1 Sequential Agent

Concept: Execute steps in predetermined order.

When to use:

• ✅ Fixed pipeline (ETL, data processing)
• ✅ Deterministic execution required
• ✅ Lower cost (no LLM routing overhead)

(ns lab.agents.sequential
  (:import [com.google.adk.agent SequentialAgent]
           [com.google.adk.agent.step LLMStep]))

(defn create-sequential-pipeline
  "Sequential agent for data processing"
  []
  (-> (SequentialAgent/builder)
      (.addStep
        (-> (LLMStep/builder)
            (.setPrompt "Extract key entities from: {{input}}")
            (.setModel "gemini-1.5-flash")
            (.build)))
      (.addStep
        (-> (LLMStep/builder)
            (.setPrompt "Classify entities: {{previous_output}}")
            (.build)))
      (.addStep
        (-> (LLMStep/builder)
            (.setPrompt "Generate summary: {{previous_output}}")
            (.build)))
      (.build)))

;; REPL Usage
(comment
  (def pipeline (create-sequential-pipeline))
  (.execute pipeline "Process this medical text...")
  ;; Step 1: Extract entities
  ;; Step 2: Classify
  ;; Step 3: Summarize
  ;; => Final summary
  )

Flow:

Input → Step 1 → Step 2 → Step 3 → ... → Output

---

2.2 Parallel Agent

Concept: Execute multiple agents concurrently.

When to use:

• ✅ Independent tasks can run simultaneously
• ✅ Need to reduce latency
• ✅ Aggregating results from multiple sources

(ns lab.agents.parallel
  (:import [com.google.adk.agent ParallelAgent]))

(defn create-parallel-researcher
  "Parallel agent for multi-source research"
  []
  (-> (ParallelAgent/builder)
      (.addAgent "scholar" (create-scholar-agent))
      (.addAgent "pubmed" (create-pubmed-agent))
      (.addAgent "web" (create-web-search-agent))
      (.setAggregationStrategy :merge-all)
      (.build)))

;; REPL Usage
(comment
  (def researcher (create-parallel-researcher))
  (.execute researcher "Research: effectiveness of salicylic acid")
  ;; Executes 3 agents concurrently:
  ;; - Google Scholar search
  ;; - PubMed search
  ;; - Web search
  ;; => Aggregated results from all sources
  )

Flow:

Input → ┬─ Agent 1 ─┐
        ├─ Agent 2 ─┼─ Aggregate → Output
        └─ Agent 3 ─┘

---

2.3 Loop Agent

Concept: Repeat execution until condition met.

When to use:

• ✅ Iterative refinement needed
• ✅ Quality threshold must be reached
• ✅ Self-correction workflows

(ns lab.agents.loop
  (:import [com.google.adk.agent LoopAgent]))

(defn create-refining-agent
  "Loop agent that refines output until quality threshold"
  []
  (-> (LoopAgent/builder)
      (.setAgent (create-writer-agent))
      (.setMaxIterations 5)
      (.setCondition
        (reify java.util.function.Predicate
          (test [_ output]
            (>= (calculate-quality-score output) 0.8))))
      (.build)))

;; REPL Usage
(comment
  (def refiner (create-refining-agent))
  (.execute refiner "Write professional medical article")
  ;; Iteration 1: quality = 0.6
  ;; Iteration 2: quality = 0.75
  ;; Iteration 3: quality = 0.85 ✓
  ;; => Returns iteration 3 output
  )

Flow:

Input → Execute → Check condition ─No─┐
                         │            │
                        Yes           │
                         ↓            │
                      Output ←────────┘

---

3. Multi-Agent Systems

Concept: Coordinate multiple specialized agents.

Patterns:

• Hierarchical: Manager agent delegates to worker agents
• Collaborative: Agents negotiate and share information
• Competitive: Best result selected from multiple approaches

(ns lab.agents.multi-agent
  (:import [com.google.adk.agent MultiAgentSystem]))

(defn create-healthcare-system
  "Multi-agent system for healthcare content generation"
  []
  (-> (MultiAgentSystem/builder)
      (.addAgent "extractor" (create-data-extraction-agent))
      (.addAgent "validator" (create-claims-validator-agent))
      (.addAgent "researcher" (create-reference-search-agent))
      (.addAgent "seo" (create-seo-optimizer-agent))
      (.addAgent "consolidator" (create-final-consolidator-agent))
      (.setOrchestrationStrategy :sequential-with-feedback)
      (.build)))

📘 Complete implementation: See

cva-healthcare-pipeline

for production multi-agent system.

---

🔧 Tool Ecosystem

Built-in Tools

Available out-of-box:

• Web search (Google Search, Google Scholar)
• Code execution (Python, JavaScript)
• Data retrieval (BigQuery, Cloud Storage)
• API calls (REST, GraphQL)

Custom Tools (Clojure)

(ns lab.tools.custom
  (:import [com.google.adk.tool Tool]))

(defn create-database-query-tool
  "Custom tool for database queries"
  [db-spec]
  (-> (Tool/builder)
      (.setName "query_database")
      (.setDescription "Queries PostgreSQL database for tenant data")
      (.setInputSchema
        {:type "object"
         :properties {:query {:type "string"
                              :description "SQL query to execute"}}
         :required ["query"]})
      (.setFunction
        (reify java.util.function.Function
          (apply [_ input]
            (let [query (get input "query")]
              (jdbc/execute! db-spec [query])))))
      (.build)))

Tool Composition

Combine tools from different sources:

(defn create-hybrid-agent
  "Agent with built-in + custom + third-party tools"
  []
  (let [built-in-search (GroundingTool/googleSearch)
        custom-db (create-database-query-tool db-spec)
        langchain-tool (from-langchain wikipedia-tool)]
    (create-llm-agent [built-in-search custom-db langchain-tool])))

---

🚀 Deployment Options

1. Local Development

# Run locally with Clojure CLI
clojure -M:dev -m lab.core

2. Vertex AI Agent Engine

(ns lab.deployment.vertex
  (:import [com.google.cloud.vertexai.agent AgentEngine]))

(defn deploy-to-vertex
  "Deploy agent to Vertex AI Agent Engine"
  [agent project-id]
  (-> (AgentEngine/builder)
      (.setProjectId project-id)
      (.setLocation "us-central1")
      (.setAgent agent)
      (.deploy)))

;; REPL Usage
(comment
  (deploy-to-vertex my-agent "saas3-476116")
  ;; => Deployed to Vertex AI with endpoint URL
  )

3. Cloud Run (Container)

FROM clojure:openjdk-17-tools-deps
COPY . /app
WORKDIR /app
RUN clojure -M:build
CMD ["clojure", "-M:prod"]

# Deploy to Cloud Run
gcloud run deploy agent-service \
  --source . \
  --region us-central1 \
  --allow-unauthenticated

---

📊 Observability

Logging

(ns lab.observability.logging
  (:require [clojure.tools.logging :as log]))

(defn execute-with-logging
  "Execute agent with comprehensive logging"
  [agent input]
  (log/info "Agent execution started" {:input input})
  (let [start-time (System/currentTimeMillis)
        result (.execute agent input)
        duration (- (System/currentTimeMillis) start-time)]
    (log/info "Agent execution completed"
              {:duration-ms duration
               :output-length (count result)
               :success true})
    result))

Metrics

Track key metrics:

• Execution time
• Token usage
• Tool invocations
• Error rates
• Cost per execution

(defn track-metrics
  [agent input]
  (let [metrics (atom {})]
    (add-watch agent :metrics
               (fn [_ _ _ new-state]
                 (swap! metrics assoc
                        :tokens (:tokens-used new-state)
                        :tools-called (:tool-invocations new-state))))
    (.execute agent input)
    @metrics))

---

💡 Best Practices

1. Start Simple, Optimize Later

Progression:

LLM Agent → Sequential Agent → Parallel Agent → Multi-Agent System
(Day 1)     (Week 1)           (Month 1)        (Production)

Rationale: Build complexity incrementally based on actual requirements.

2. Choose the Right Agent Type

Decision Matrix:

Need	Agent Type	Reason
Simple task, one path	Sequential	Lowest cost, deterministic
Complex routing needed	LLM	Flexibility, adaptability
Independent parallel tasks	Parallel	Reduced latency
Iterative refinement	Loop	Quality improvement
Complex system	Multi-Agent	Specialized expertise per component

📘 Detailed guidance: See

cva-concepts-agent-types

for A/B/C/D taxonomy.

3. Tool Design Principles

• Single Responsibility: One tool = one clear function
• Descriptive Names:

  query_customer_database

  not

  db

• Rich Descriptions: Help LLM understand when to use tool
• Error Handling: Return structured errors, not exceptions
• Idempotent: Safe to retry

4. Model Selection

By task complexity:

• Simple (extraction, classification):

  gemini-1.5-flash

• Medium (reasoning, personalization):

  gemini-1.5-pro

  or

  claude-3-5-haiku

• Complex (consolidation, critical decisions):

  claude-3-5-sonnet

  or

  gemini-2.0-flash-thinking

📘 Cost optimization: See

cva-patterns-cost

for multi-model routing.

5. Testing Strategy

(ns lab.testing.agents
  (:require [clojure.test :refer :all]))

(deftest test-agent-execution
  (testing "Agent produces valid output"
    (let [agent (create-test-agent)
          result (.execute agent "test input")]
      (is (string? result))
      (is (> (count result) 0))
      (is (valid-json? result)))))

(deftest test-agent-tools
  (testing "Agent uses correct tools"
    (let [agent (create-test-agent-with-mock-tools)
          _ (.execute agent "calculate 2 + 2")
          tool-calls (get-tool-invocations agent)]
      (is (= 1 (count tool-calls)))
      (is (= "calculator" (:tool-name (first tool-calls)))))))

6. Error Handling

(defn execute-with-retry
  "Execute agent with exponential backoff retry"
  [agent input max-retries]
  (loop [attempt 1]
    (try
      (.execute agent input)
      (catch Exception e
        (if (< attempt max-retries)
          (do
            (Thread/sleep (* 1000 (Math/pow 2 attempt)))
            (recur (inc attempt)))
          (throw e))))))

---

🔗 Related Skills

• cva-concepts-agent-types

  - A/B/C/D agent taxonomy ⭐

• cva-quickref-adk

  - ADK API quick reference ⭐

• cva-patterns-workflows

  - Multi-agent workflow patterns

• cva-patterns-cost

  - Cost optimization strategies

• cva-healthcare-pipeline

  - Production multi-agent system

• cva-setup-vertex

  - Vertex AI deployment setup

---

📘 Additional Resources

Official Documentation

• Google ADK Docs
• ADK GitHub
• Vertex AI Agent Engine

Advanced Topics

• Custom Tool Development
• Multi-Agent Orchestration
• Production Deployment

---

This skill provides foundational ADK knowledge. Combine with agent-types taxonomy and workflow patterns for complete understanding.