How mohitbhimrajka/adk-copilot works
Project Type and Purpose
• This is an open-source framework (ADK Copilot) built on the Google Agent Development Kit (ADK) that orchestrates a team of specialized AI agents to automate end-to-end workflows—primarily the software development lifecycle.
• It is not a traditional frontend-backend web app; rather, it is a modular AI orchestration system with pluggable “sub-agents,” custom tools, data sources, evaluation suites, and deployment scripts.
File Structure
• Top-level directories:
• adk_copilot/
– agent.py → The central orchestrator agent (state machine)
– prompts.py → Shared prompt templates
– entities/ → Pydantic models (SupportTicket, etc.)
– sub_agents/ → Six specialist agents (analysis, retrieval, generation, review, problem solving)
• data/ → Knowledge base materials and sample database CSV
• scripts/ → Data preparation, doc scraping, RAG setup, PDF conversion
• deployment/ → Cloud Run and Vertex AI Agent Engine deployment entry points
• eval/ → Test harness for conversation-based evaluation
• setup_environment.sh → Bootstrap script for provisioning GCP resources
• Configuration files: .env.example, pyproject.toml, .gitignore
• CI/infra: deployment/*.sh & .py, setup_environment.sh
Extract Key Architectural Insights from the README
• Orchestrator as a stateful finite state machine with discrete lifecycle states (New → Analyzing → AwaitingConfirmation → Generating → Reviewing).
• Six specialist sub-agents, each with a narrow responsibility:
1. ticket_analysis_agent
2. knowledge_retrieval_agent (Vertex AI RAG)
3. db_retrieval_agent (BigQuery vector search)
5. code_reviewer_agent (style guide QA)
6. problem_solver_agent
• Custom tools bridge to external systems:
• GCS file reader for multi-modal inputs
• Vertex AI RAG for documentation search
• BigQuery for historical ticket search
• Deployment targets: Google Cloud Run and Vertex AI Agent Engine
Main Components
• User Interface Layer
• ADK CLI/Web UI (adk web)
• Orchestrator Agent
• State machine logic (agent.py)
• Prompts engine
• Tooling Layer
• FileReaderTool (GCS)
• BigQuerySearchTool
• RAGTool (Vertex AI)
• MermaidRenderer
• Data Sources
• GCS bucket (knowledge_base documents)
• BigQuery dataset (resolved_tickets.csv)
• External Services
• Google Cloud Storage
• BigQuery
• Vertex AI RAG Engine
• Deployment & Infrastructure
• setup_environment.sh (IaC)
• Cloud Run service
• Vertex AI Agent Engine
• Evaluation Suite
• eval/test_eval.py
Relationships and Interactions
• Sub-Agents → Tools → External Services/Data Sources (GCS, BigQuery, Vertex AI)
• code_generator_agent → Generated Code → code_reviewer_agent → Approved Code → User
• Deployment scripts triggered by setup_environment.sh → provision infra → deploy Cloud Run & Agent Engine
• eval suite invokes orchestrator endpoints for automated testing
Architectural Patterns and Principles
• State Machine Workflow: clear lifecycle transitions in the orchestrator
• Modular, Pluggable Sub-Agents: each agent isolated, interchangeable, single-responsibility
• Tool Abstraction Layer: decouples sub-agents from external systems
• Event-Driven/Message-Passing: agents communicate via structured messages/entities