adk-python/contributing/samples/adk_agent_builder_assistant

Agent Builder Assistant

An intelligent assistant for building ADK multi-agent systems using YAML configurations.

Quick Start

Using ADK Web Interface

# From the ADK project root
adk web src/google/adk/agent_builder_assistant

Programmatic Usage

# Create with defaults
agent = AgentBuilderAssistant.create_agent()

# Create with custom settings
agent = AgentBuilderAssistant.create_agent(
    model="gemini-2.5-pro",
    schema_mode="query",
    working_directory="/path/to/project"
)

Core Features

🎯 Intelligent Agent Design

• Analyzes requirements and suggests appropriate agent types
• Designs multi-agent architectures (Sequential, Parallel, Loop patterns)
• Provides high-level design confirmation before implementation

📝 Advanced YAML Configuration

• Generates AgentConfig schema-compliant YAML files
• Supports all agent types: LlmAgent, SequentialAgent, ParallelAgent, LoopAgent
• Built-in validation with detailed error reporting

🛠️ Multi-File Management

• Read/Write Operations: Batch processing of multiple files
• File Type Separation: YAML files use validation tools, Python files use generic tools
• Backup & Recovery: Automatic backups before overwriting existing files

🗂️ Project Structure Analysis

• Explores existing project structures
• Suggests conventional ADK file organization
• Provides path recommendations for new components

🧭 Dynamic Path Resolution

• Session Binding: Each chat session bound to one root directory
• Working Directory: Automatic detection and context provision
• ADK Source Discovery: Finds ADK installation dynamically (no hardcoded paths)

Schema Modes

Choose between two schema handling approaches:

Embedded Mode (Default)

agent = AgentBuilderAssistant.create_agent(schema_mode="embedded")

• Full AgentConfig schema embedded in context
• Faster execution, higher token usage
• Best for comprehensive schema work

Query Mode

agent = AgentBuilderAssistant.create_agent(schema_mode="query")

• Dynamic schema queries via tools
• Lower initial token usage
• Best for targeted schema operations

Example Interactions

Create a new agent

Create an agent that can roll n-sided number and check whether the rolled number is prime.

Add Capabilities to Existing Agent

Could you make the agent under `./config_based/roll_and_check` a multi agent system : root_agent only for request routing and two sub agents responsible for two functions respectively ?

Project Structure Analysis

Please analyze my existing project structure at './config_based/roll_and_check' and suggest improvements for better organization.

Tool Ecosystem

Core File Operations

• read_config_files - Read multiple YAML configurations with analysis
• write_config_files - Write multiple YAML files with validation
• read_files - Read multiple files of any type
• write_files - Write multiple files with backup options
• delete_files - Delete multiple files with backup options

Project Analysis

• explore_project - Analyze project structure and suggest paths
• resolve_root_directory - Resolve paths with working directory context

ADK knowledge Context

• google_search - Search for ADK examples and documentation
• url_context - Fetch content from URLs (GitHub, docs, etc.)
• search_adk_source - Search ADK source code with regex patterns

File Organization Conventions

ADK Project Structure

my_adk_project/
└── src/
    └── my_app/
        ├── root_agent.yaml
        ├── sub_agent_1.yaml
        ├── sub_agent_2.yaml
        ├── tools/
        │   ├── process_email.py    # No _tool suffix
        │   └── analyze_sentiment.py
        └── callbacks/
            ├── logging.py            # No _callback suffix
            └── security.py

Naming Conventions

• Agent directories: snake_case
• Tool files: descriptive_action.py
• Callback files: descriptive_name.py
• Tool paths: project_name.tools.module.function_name
• Callback paths: project_name.callbacks.module.function_name

Session Management

Root Directory Binding

Each chat session is bound to a single root directory:

• Automatic Detection: Working directory provided to model automatically
• Session State: Tracks established root directory across conversations
• Path Resolution: All relative paths resolved against session root
• Directory Switching: Suggest user starting new session to work in different directory

Working Directory Context

# The assistant automatically receives working directory context
agent = AgentBuilderAssistant.create_agent(
    working_directory="/path/to/project"
)
# Model instructions include: "Working Directory: /path/to/project"

Advanced Features

Dynamic ADK Source Discovery

No hardcoded paths - works in any ADK installation:

from google.adk.agent_builder_assistant.utils import (
    find_adk_source_folder,
    get_adk_schema_path,
    load_agent_config_schema
)

# Find ADK source dynamically
adk_path = find_adk_source_folder()

# Load schema with caching
schema = load_agent_config_schema()

Schema Validation

All YAML files validated against AgentConfig schema:

• Syntax Validation: YAML parsing with detailed error locations
• Schema Compliance: Full AgentConfig.json validation
• Best Practices: ADK naming and structure conventions
• Error Recovery: Clear suggestions for fixing validation errors

Performance Optimization

Efficient Operations

• Multi-file Processing: Batch operations reduce overhead
• Schema Caching: Global cache prevents repeated file reads
• Dynamic Discovery: Efficient ADK source location caching
• Session Context: Persistent directory binding across conversations

Memory Management

• Lazy Loading: Schema loaded only when needed
• Cache Control: Manual cache clearing for testing/development
• Resource Cleanup: Automatic cleanup of temporary files

Error Handling

Comprehensive Validation

• Path Validation: All paths validated before file operations
• Schema Compliance: AgentConfig validation with detailed error reporting
• Python Syntax: Syntax validation for generated Python code
• Backup Creation: Automatic backups before overwriting files

Recovery Mechanisms

• Retry Suggestions: Clear guidance for fixing validation errors
• Backup Restoration: Easy recovery from automatic backups
• Error Context: Detailed error messages with file locations and suggestions

This comprehensive assistant provides everything needed for intelligent, efficient ADK agent system creation with proper validation, file management, and project organization.