ADK Expert Agent

I can answer any ADK related question, help debug and fix errors in your ADK code, provide guidance for ADK GitHub issues, generate unit tests for ADK components, Evalsets for your own agents!

Comment

Inspiration

The inspiration for the ADK Expert Agent came from a desire to address the real-world friction developers face when adopting and mastering a new, powerful framework like the Agent Development Kit. I asked myself: "What if I could build an agent that wasn't just a Q&A bot, but a true developer companion?"

This led to a series of guiding questions:

  • What if an agent could go beyond static documentation and provide live, context-aware guidance on actual GitHub issues?
  • What if it could handle the tedious, time-consuming tasks of creating project artifacts, like generating professional-looking reports, presentations, and architecture diagrams directly from a simple request?
  • What if I could build an agent that is not only helpful to someone who is starting out using ADK but also someone who is a contributor on the ADK project and wants guidance to implemente a feature request, bug etc.?

The core idea was to create a "meta-agent"—an expert on ADK, built with ADK. I wanted to build a tool that I want to use every day: one that accelerates development, demystifies complex topics, and transforms abstract requests into tangible, useful outputs. This project is my answer to making the full power of ADK more accessible, productive, and intuitive for every developer.

What it does

The ADK Expert Agent is a sophisticated, multi-purpose assistant designed to be a one-stop-shop for developers working with Google's Agent Development Kit (ADK). It acts as a comprehensive "ADK expert" that has the following features:

  • ADK Expertise: Answers general questions about Google ADK v1.2.0.
  • Write ADK Agents: Help you design and even write ADK agents, for e.g. ask "write a multi-agent setup for HR onboarding"
  • Debug and Fix errors: Provide your ADK code including your query and the ADK expert agent will provide you guidance on how to solve the issues.
  • Generate Unit tests: Use the ADK knowledge to create tests for the ADK components.
  • Evalsets for your own ADK Agents: Provide your code to the expert agent and as long as the total amount of input tokens don't exceed 1 million, the expert agent will be able to create Evalsets for your own agents.
  • GitHub Issue Processing:
    • Fetches details for specific GitHub issues from the google/adk-python repository.
    • Provides ADK-specific guidance based on the issue content.
  • Document Generation:
    • Generates Markdown content based on user queries and ADK knowledge.
    • Converts Markdown to PDF, HTML (Marp slides), or PPTX (Marp slides).
    • Uploads generated documents to Google Cloud Storage and provides a signed URL.
  • Mermaid Diagram Generation:
    • Generates Mermaid diagram syntax based on user requests and ADK context.
    • Converts Mermaid syntax to PNG images.
    • Uploads generated diagrams to Google Cloud Storage and provides a signed URL.
  • Modular Architecture:
    • A root_agent (orchestrator) to delegate tasks to specialized agents.
    • Dedicated agents for GitHub issue processing, document generation, and diagram orchestration.
    • A suite of tools for specific functionalities (e.g., GitHub API interaction, Marp CLI, Mermaid CLI).
  • Web UI: An Angular-based web interface for interacting with the agent.
  • Assist with Code: Help developers debug errors in their ADK code and generate unit tests or evaluation sets (evalsets) for their own agents, streamlining the development and testing process.

Ultimately, it's designed to accelerate the entire ADK development lifecycle, from learning and debugging to documentation and testing.

How I built it

The agent is built on Python and the Google ADK framework, with Gemini 2.5 Pro as its core intelligence. The architecture is centered around a powerful Orchestrator-Specialist pattern:

  1. The Root Orchestrator (adk_expert_orchestrator): This is the brain of the operation. It analyzes incoming user queries and intelligently delegates tasks to the appropriate specialist agent.

  2. Specialist Agents: I built a suite of focused, single-purpose agents to handle complex tasks:

    • github_issue_processing_sequential_agent: A multi-step SequentialAgent that first uses a tool to fetch an issue's description from the GitHub API, then passes that content to another LLM-based tool to generate ADK-specific guidance.
    • document_creation_specialist_agent: An agent that takes prepared Markdown content and a document type (PDF, HTML, PPTX) and uses a FunctionTool to execute the Marp CLI for conversion.
    • mermaid_diagram_orchestrator_agent: An agent that first calls a dedicated syntax-generation agent and then passes the resulting Mermaid code to a tool that uses the Mermaid CLI (mmdc) to render a PNG.

  3. Rich Tooling & Integrations: The agents' capabilities are powered by a collection of custom ADK Tools that integrate with:

    • External CLIs: marp-cli and mermaid-cli are executed in a subprocess to handle document and diagram generation.
    • Google Cloud Services: I use Google Cloud Storage to host all generated artifacts and provide expiring signed URLs for secure access. Google Cloud Secret Manager is used to securely manage all API keys and tokens.
    • GitHub API: To fetch live issue data.

  4. Insightful Web UI: The frontend is a feature-rich Angular application that provides a real-time chat interface with token streaming (SSE). I customized the adk-web project so that the user-experience is enhanced when using the UI.

The entire system is containerized using Docker and designed for easy deployment on Google Cloud Run.

Challenges I ran into

  • Model Non-Determinism: Ensuring consistent, high-quality output, especially for generating structured content like Mermaid syntax or Markdown, was a major challenge. Even with a temperature of 0.0, the same prompt could occasionally yield slightly different or erroneous results, requiring me to build resilient parsers and error handlers. Even now, the model sometimes returns erroneous mermaid syntax, hence the users are advised to rerun queries when they fail.

  • ADK behavior on skip_summarization=true: My expectation was that when I set skip_summarization to true on in a tool callback and it is the final tool to be called, then LLM response should be the text in my FunctionResponse. However, the adk web does not show any text. I had customize the UI myself in order to show the text from FunctionResponse when skip_summarization is set to true.

  • Robust Agent Chaining: Passing data cleanly between the agents in my SequentialAgent was difficult. I discovered that the output of one agent wasn't being correctly relayed to the next, forcing me to implement a dedicated FormatOutputAgent just to ensure the final guidance was correctly packaged and passed back to the orchestrator.

  • Dockerizing CLI Dependencies: Integrating marp-cli and mermaid-cli into a Python Docker container was complex. It required installing Node.js, managing npm packages, and correctly configuring all system dependencies for the headless Chrome instance used by Puppeteer, including wrestling with sandbox and pathing issues inside the container.

  • Complex Prompt Engineering: Designing the instruction_provider for the root orchestrator to accurately understand user intent and delegate to the correct sub-agent required significant iteration, combining keyword matching with regular expressions to reliably distinguish between a request for a diagram, a PDF, or a GitHub issue.

  • Graceful Error Handling: When a tool like mmdc or marp-cli failed (e.g., due to invalid syntax from the LLM), I needed a robust way to capture the error and return a meaningful message to the user, including the problematic syntax they could then correct, rather than just failing silently.

  • Custom UI: Integrating custom UI with the ADK backend presented challenges. There were some corner cases where the streaming data chunks was handled correctly when running on the local server but when packaged and running on Cloud Run, the local server optimizations were not there and it took a long time to figure the problem out.

Accomplishments that I'm proud of

  • Creating a True "Orchestrator": I successfully implemented a root agent that acts as an intelligent router, delegating complex tasks to specialized agents. This modular architecture is powerful, scalable, and a fantastic demonstration of advanced ADK patterns.
  • Generating High-Quality, Professional Artifacts: I'm incredibly proud that the agent generates more than just text. By integrating Marp and Mermaid CLIs, it can create beautifully formatted PDF reports, PPTX presentations, and clear PNG architecture diagrams directly from user requests, making it a true productivity tool. There is a caveat here that the mermaid syntax generated by the LLM can sometimes be erroneous and can lead to the agent not giving the correct output.
  • Deep, Context-Aware GitHub Assistance: The agent doesn't just fetch a GitHub issue; it analyzes its content against a knowledge base of ADK documentation to provide relevant, actionable guidance, effectively acting as an automated domain expert that can help developers solve real problems.
  • Resilient and User-Centric Error Handling: I implemented robust error handling within my tools. For example, if diagram generation fails, the agent returns the faulty Mermaid syntax to the user, empowering them to correct it and try again. This user-centric approach makes the agent much more practical and less frustrating to use.
  • Gemini Bugs: I was able to report some bugs related to Gemini 2.5 Flash and Gemini 2.5 Pro and able to help the LLM get more robust. The Gemini 2.5 Flash bug has been also fixed in the mean time while the Gemini 2.5 Pro bug is still being worked on.

What I learned

  • The Orchestrator/Specialist pattern is highly effective for building complex agents. A central router delegating to single-purpose agents is far more maintainable and scalable than a single, monolithic agent trying to do everything.
  • ADK's Tool abstraction is fundamental. Encapsulating external interactions like CLI commands or API calls into clean, reusable tools was the key to integrating diverse functionalities like document generation and GitHub analysis in a clean way.
  • Callbacks are essential for control and observability. I used before_model_callback for detailed logging, which was invaluable for debugging, and after_agent_callback to intercept and format the output from sub-agents, giving me fine-grained control over the data flow.
  • Design for failure. LLMs can produce unexpected or invalid output. By using Pydantic for strict input/output validation and building error-handling logic directly into my tools, I created a much more resilient and user-friendly application.

What's next for ADK Expert Agent

  • Integration into ADK Ecosystem: Output from ADK Expert Agent was already used in multiple github issue like 773 and 772 and was quite useful to the collaborators. Due to this, I am in contact with the ADK team to see how we can integrate the agent into the Github Ecosystem and provide automatic guidance when a new issue is opened.

  • Improvement potential in PDF/Slides generation: The pdf output can be further improvement.

  • Generalize ADK Expert: The modular design of the ADK Expert Agent allows it to be generalized easily to act as an expert for any open-source framework. I am currently looking into this.

Built With

Share this project:

Updates