Adk Agent Builder

ADK Agent Builder

Build production-ready agents with Google’s Agent Development Kit (ADK): scaffolding, tool wiring, orchestration patterns, testing, and optional deployment to Vertex AI Agent Engine.

Overview

• Creates a minimal, production-oriented ADK scaffold (agent entrypoint, tool registry, config, and tests).
• Supports single-agent ReAct-style workflows and multi-agent orchestration (Sequential/Parallel/Loop).
• Produces a validation checklist suitable for CI (lint/tests/smoke prompts) and optional Agent Engine deployment verification.

Prerequisites

• Python runtime compatible with your project (often Python 3.10+)
• google-adk installed and importable
• If deploying: access to a Google Cloud project with Vertex AI enabled and permissions to deploy Agent Engine runtimes
• Secrets available via environment variables or a secret manager (never hardcoded)

Instructions

1. Confirm scope: local-only agent scaffold vs Vertex AI Agent Engine deployment. 2. Choose an architecture:

• Single agent (ReAct) for adaptive tool-driven tasks
• Multi-agent system (specialists + orchestrator) for complex, multi-step workflows

3. Define the tool surface (built-in ADK tools + any custom tools you need) and required credentials. 4. Scaffold the project:

• src/agents/, src/tools/, tests/, and a dependency file (pyproject.toml or requirements.txt)

5. Implement the minimum viable agent and a smoke test prompt; add regression tests for tool failures. 6. If deploying, produce an adk deploy ... command and a post-deploy validation checklist (AgentCard/task endpoints, permissions, logs).

Output

• A repo-ready ADK scaffold (files and directories) plus starter agent code
• Tool stubs and wiring points (where to add new tools safely)
• A test + validation plan (unit tests and a minimal smoke prompt)
• Optional: deployment commands and verification steps for Agent Engine

Error Handling

• Dependency/runtime issues: provide pinned install commands and validate imports.
• Auth/permission failures: identify the missing role/API and propose least-privilege fixes.
• Tool failures/rate limits: add retries/backoff guidance and a regression test to prevent recurrence.

Examples

Example: Scaffold a single ReAct agent

• Request: “Create an ADK agent that summarizes PRs and proposes test updates.”
• Result: agent entrypoint + tool registry + a smoke test command for local verification.

Example: Multi-agent orchestrator

• Request: “Build a supervisor + deployer + verifier team and deploy to Agent Engine.”
• Result: orchestrator skeleton, per-agent responsibilities, and adk deploy ... + post-deploy health checks.

Resources

• Full detailed guide (kept for reference): ${CLAUDE_SKILL_DIR}/references/SKILL.full.md
• Repo standards (source of truth):
• 000-docs/6767-a-SPEC-DR-STND-claude-code-plugins-standard.md
• 000-docs/6767-b-SPEC-DR-STND-claude-skills-standard.md
• ADK / Agent Engine docs: https://cloud.google.com/vertex-ai/docs/agent-engine

ARD: ADK Agent Builder

Part of Tons of Skills by Intent Solutions | jeremylongshore.com

System Context

The ADK Agent Builder operates within the Google Cloud AI ecosystem. It generates project scaffolds that target the google-adk SDK and optionally deploy to Vertex AI Agent Engine.

Developer (Claude Code)
    │
    ▼
ADK Agent Builder Skill
    │
    ├── Reads: project context, existing code, user requirements
    ├── Generates: agent scaffold (src/agents/, src/tools/, tests/)
    └── Optionally deploys: adk deploy → Vertex AI Agent Engine
                                            │
                                            ├── IAM (Service Account, roles)
                                            ├── Cloud Build (container image)
                                            └── Agent Engine Runtime (serving)

Data Flow

1. Input: User describes the agent they want (purpose, tools needed, single vs multi-agent) 2. Architecture selection: Skill determines ReAct (single) or orchestrated (multi-agent) based on complexity 3. Scaffold generation: Creates directory structure, agent entrypoint, tool registry, config, tests 4. Tool wiring: Connects requested tools (APIs, databases, search) with credential management 5. Validation: Runs smoke test prompt against local agent to verify it works 6. Deployment (optional): Generates adk deploy command + post-deploy health checks

Key Design Decisions

Tool Usage Pattern

Error Handling Strategy

Extension Points

• Custom tools: Add .py files to src/tools/, register in tool registry
• New agent architectures: ADK supports custom orchestration beyond Sequential/Parallel/Loop
• Alternative deployment: Local-only, Cloud Run, or custom infrastructure instead of Agent Engine
• Testing expansion: Add evaluation datasets, A/B prompt testing, latency benchmarks

PRD: ADK Agent Builder Skill

Version: 1.0.0 Author: Jeremy Longshore Date: 2026-03-22 Status: Active Marketplace: tonsofskills.com by Intent Solutions Portfolio: jeremylongshore.com

---

Problem Statement

Building AI agents with Google's Agent Development Kit requires significant boilerplate: project structure, tool wiring, orchestration pattern selection, testing scaffolds, and deployment configuration. Developers waste hours on repeated setup tasks instead of focusing on agent logic. Without a structured approach, teams end up with inconsistent project layouts, missing tests, hardcoded credentials, and agents that work locally but fail in Vertex AI Agent Engine.

The ADK Agent Builder skill eliminates this friction by generating production-ready scaffolds tailored to the developer's use case, with correct patterns baked in from the start.

Target Users

Success Criteria

1. Time to first working agent: Under 5 minutes from skill invocation to passing smoke test 2. Deployment readiness: Generated scaffold can deploy to Agent Engine without manual fixes 3. Test coverage: Every generated agent includes at least unit tests and one smoke prompt 4. Zero hardcoded secrets: All credentials flow through environment variables or Secret Manager 5. Pattern accuracy: Generated code uses correct ADK APIs (google.adk.agents.Agent, google.adk.tools, google.adk.runners.Runner)

Functional Requirements

FR-1: Scope Confirmation

Before generating anything, the skill confirms:

• Local-only agent vs. Vertex AI Agent Engine deployment
• Single-agent (ReAct) vs. multi-agent orchestration
• Tool surface (built-in ADK tools + custom tools)
• Required credentials and external service dependencies

FR-2: Project Scaffolding

Generate a complete ADK project structure:

project-name/
  src/
    agents/
      __init__.py
      agent.py           # Main agent or orchestrator
    tools/
      __init__.py
      custom_tool.py     # Tool stubs with FunctionTool wrappers
  tests/
    test_agent.py        # Unit tests
    test_tools.py        # Tool-level tests
    smoke_prompts.txt    # Validation prompts for manual/CI testing
  pyproject.toml         # Dependencies with pinned google-adk version
  .env.example           # Required environment variables (no values)
  README.md              # Setup and run instructions

FR-3: Agent Implementation

• Single agent: Uses google.adk.agents.Agent with model, instruction, and tools parameters. ReAct-style reasoning through ADK's built-in agent loop.
• Multi-agent: Uses SequentialAgent, ParallelAgent, or LoopAgent from google.adk.agents to compose specialist sub-agents.
• All agents include: name, description, instruction prompt, tool bindings, and model specification.

FR-4: Tool Wiring

• Generate tool stubs using google.adk.tools.FunctionTool or google.adk.tools.google_search
• Each tool includes: docstring (used by the LLM for tool selection), typed parameters, return type, and error handling
• Tool registry pattern: tools declared in src/tools/__init__.py and imported by agent

FR-5: Testing Scaffold

• Unit tests using pytest with mocked LLM responses
• Tool-level tests that validate input/output schemas
• Smoke prompts: plain-text prompts that exercise the agent end-to-end (for adk run or Runner.run_async)
• Integration test template for live API calls (skipped by default, enabled via env flag)

FR-6: Deployment Support (Optional)

When deployment scope is confirmed:

• Generate adk deploy cloud_run or adk deploy agent_engine command
• Include post-deploy validation checklist:
• Agent endpoint responds to health check
• AgentCard accessible at /.well-known/agent.json
• Task creation and streaming work via A2A protocol
• IAM roles verified (Vertex AI User, Service Account Token Creator)
• Environment-specific configuration (staging vs. production)

FR-7: Error Recovery Guidance

For every known failure mode, the skill provides:

• Specific error message or symptom
• Root cause
• Fix command or configuration change
• Regression test to prevent recurrence

Non-Functional Requirements

NFR-1: API Accuracy

All generated code must reference real ADK APIs. No fabricated class names or import paths. Core imports: google.adk.agents, google.adk.tools, google.adk.runners, google.adk.sessions.

NFR-2: Security

• No credentials in generated files (use .env.example with empty values)
• Service account keys referenced via GOOGLE_APPLICATION_CREDENTIALS environment variable
• Recommend Workload Identity Federation over exported keys

NFR-3: Portability

• Generated projects work on Python 3.10+ (ADK minimum requirement)
• No OS-specific dependencies
• Container-ready by default (Dockerfile optional but available)

NFR-4: Idempotency

• Running the skill twice with the same inputs produces the same output
• Skill does not overwrite existing files unless explicitly confirmed

NFR-5: Minimal Dependencies

• Core: google-adk, google-cloud-aiplatform, pytest
• No unnecessary framework dependencies (no LangChain, no CrewAI unless requested)

Dependencies

Out of Scope

• LangChain/CrewAI integration: This skill is ADK-native. Use other skills for alternative frameworks.
• Frontend/UI generation: Agents are backend services. UI is a separate concern.
• Custom model fine-tuning: The skill uses existing Gemini/Claude models, not fine-tuned variants.
• Multi-cloud deployment: Targets GCP only (Vertex AI Agent Engine, Cloud Run).
• Monitoring dashboard setup: Generates logging/metrics hooks but not Grafana/Cloud Monitoring dashboards.
• Data pipeline orchestration: For Dataflow/Composer pipelines, use dedicated GCP skills.

ADK Agent Builder — Common Errors

Import & Dependency Errors

GCP Authentication Errors

Agent Engine Deployment Errors

Tool & Runtime Errors

Multi-Agent Orchestration Errors

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

ADK Agent Builder — Usage Examples

Example 1: Single ReAct Agent — PR Summarizer

Request: "Create an ADK agent that summarizes GitHub PRs and suggests test updates."

What the skill produces:

my-pr-agent/
├── src/
│   ├── agents/
│   │   └── pr_summarizer.py
│   └── tools/
│       ├── github_fetcher.py
│       └── test_analyzer.py
├── tests/
│   ├── test_github_fetcher.py
│   └── test_pr_summarizer.py
├── pyproject.toml
└── README.md

Agent entrypoint (src/agents/pr_summarizer.py):

from google.adk.agents import Agent
from google.adk.tools import Tool
from src.tools.github_fetcher import fetch_pr_diff
from src.tools.test_analyzer import suggest_tests

agent = Agent(
    name="pr-summarizer",
    model="gemini-2.0-flash",
    system_prompt="You summarize PR changes and suggest missing test coverage.",
    tools=[fetch_pr_diff, suggest_tests],
)

Smoke test: adk run --prompt "Summarize PR #42 in repo owner/project"

---

Example 2: Multi-Agent Team — Research → Write → Review

Request: "Build a 3-agent team: researcher finds info, writer drafts content, reviewer checks quality."

Architecture: Sequential orchestration (researcher → writer → reviewer)

from google.adk.agents import Agent, SequentialAgent

researcher = Agent(name="researcher", model="gemini-2.0-flash",
    system_prompt="Find relevant information on the given topic.",
    tools=[web_search, doc_reader])

writer = Agent(name="writer", model="gemini-2.0-flash",
    system_prompt="Draft content based on research findings.",
    tools=[text_formatter])

reviewer = Agent(name="reviewer", model="gemini-2.0-flash",
    system_prompt="Review draft for accuracy, clarity, and completeness.",
    tools=[fact_checker])

pipeline = SequentialAgent(
    name="content-pipeline",
    agents=[researcher, writer, reviewer],
)

---

Example 3: Deploy to Vertex AI Agent Engine

Request: "Deploy my agent to Agent Engine with health checks."

Commands produced:

# Build and deploy
adk deploy --project=my-gcp-project --region=us-central1 --agent=src/agents/pr_summarizer.py

# Verify deployment
gcloud ai agent-engines list --project=my-gcp-project --region=us-central1

# Test deployed agent
curl -X POST "https://us-central1-aiplatform.googleapis.com/v1/projects/my-gcp-project/locations/us-central1/agents/pr-summarizer:generate" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Summarize PR #42"}'

# Check logs
gcloud logging read "resource.type=aiplatform.googleapis.com/Agent AND resource.labels.agent_id=pr-summarizer" --limit=20

---

Example 4: Add a Custom Tool

Request: "Add a Slack notification tool to my existing agent."

Tool file (src/tools/slack_notifier.py):

from google.adk.tools import Tool
import os, requests

@Tool(description="Send a message to a Slack channel")
def send_slack_message(channel: str, message: str) -> str:
    webhook_url = os.environ["SLACK_WEBHOOK_URL"]
    response = requests.post(webhook_url, json={"channel": channel, "text": message})
    return f"Sent to {channel}: {response.status_code}"

Register in agent:

from src.tools.slack_notifier import send_slack_message

agent = Agent(
    name="pr-summarizer",
    tools=[fetch_pr_diff, suggest_tests, send_slack_message],  # Added
)

Environment: export SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)

ADK Agent Builder — Implementation Guide

How the Skill Works

1. Scope confirmation: Determines if user wants local-only scaffold or full Vertex AI deployment 2. Architecture selection: Chooses ReAct (single agent) or orchestrated (multi-agent) based on task complexity 3. Tool surface definition: Identifies which tools the agent needs, maps to ADK Tool interface 4. Scaffold generation: Creates project structure with all required files 5. Validation: Runs smoke test to verify agent works before handing off

ADK Project Structure

project-root/
├── src/
│   ├── agents/
│   │   ├── __init__.py
│   │   └── main_agent.py       # Agent entrypoint with system prompt + tools
│   └── tools/
│       ├── __init__.py
│       └── custom_tool.py      # Each tool in its own file
├── tests/
│   ├── test_tools.py           # Unit tests for tool functions
│   └── test_agent.py           # Smoke prompt tests for agent behavior
├── pyproject.toml              # Dependencies: google-adk, tool-specific packages
├── .env.example                # Required environment variables (never actual values)
└── README.md                   # Setup and usage instructions

Tool Registry Pattern

Every tool follows the ADK @Tool decorator pattern:

from google.adk.tools import Tool

@Tool(description="Clear description of what this tool does and when to use it")
def tool_name(param1: str, param2: int = 10) -> str:
    """Typed parameters. Return string for agent consumption."""
    result = do_something(param1, param2)
    return f"Result: {result}"

Tools are registered in the Agent constructor:

agent = Agent(
    name="agent-name",
    model="gemini-2.0-flash",
    system_prompt="...",
    tools=[tool_a, tool_b, tool_c],
)

Adding a new tool: Create file in src/tools/, import in agent file, add to tools=[] list.

Multi-Agent Orchestration

ADK provides three built-in orchestration patterns:

Custom orchestrators combine these:

pipeline = SequentialAgent(
    name="research-pipeline",
    agents=[
        ParallelAgent(name="gather", agents=[web_researcher, doc_scanner]),
        synthesizer,
        LoopAgent(name="refine", agent=quality_checker, max_iterations=3),
    ],
)

Testing Strategy

Unit tests: Test each tool function in isolation with mocked external APIs.

def test_fetch_pr_diff(mock_github):
    mock_github.return_value = {"files": [{"filename": "app.py", "changes": 5}]}
    result = fetch_pr_diff("owner/repo", 42)
    assert "app.py" in result

Smoke prompts: Run the full agent against a known scenario.

def test_agent_smoke():
    response = agent.run("Summarize the changes in PR #42")
    assert len(response) > 100  # Non-trivial response
    assert "changes" in response.lower()

Deployment Pipeline

Local Development        Staging                  Production
────────────────────     ─────────────────        ──────────────────
adk run --local          adk deploy --staging     adk deploy --prod
pytest tests/            curl health-check        gcloud monitoring
manual smoke test        automated eval suite     alerting + logging

Local: adk run --prompt "test prompt" — runs agent in local Python process.

Staging: Deploy to Agent Engine with --staging flag, run automated test suite.

Production: Deploy with monitoring, set up Cloud Monitoring alerts for error rate and latency.

Configuration Reference

Environment Variables:

pyproject.toml:

[project]
name = "my-agent"
requires-python = ">=3.10"
dependencies = [
    "google-adk>=0.3.0",
    # Add tool-specific dependencies here
]

[project.optional-dependencies]
dev = ["pytest", "pytest-asyncio"]

--- [Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)