Ackgent: Rapid Agent Development on GCP with ADK and AgentConfig

This project provides a rapide approach for deploying conversational agents to Google Cloud Platform (GCP) using the Agent Development Kit (ADK) and Agent Config.

It serves as a practical demonstration of the power and simplicity of this method for building and managing sophisticated, multi-capability agents.

Table of Contents

• Ackgent: Rapid Agent Development on GCP with ADK and AgentConfig
  • Table of Contents
  • Features
  • Prerequisites
  • Installation
  • Usage
    • Running the Agent Locally
    • Deploying to GCP
  • Available Agents
    • Root Agent
    • Sub-Agents
  • Integration Testing with Evalsets
  • Limitations
  • Tips and Tricks
  • License

Features

• Rapid Deployment: Go from code to a deployed agent on GCP in minutes.
• Modern Python Packaging: Employs uv for fast Python dependency management.
• Simplified Task Management: Utilizes just for command execution and automation.
• Agent-in-Agent Architecture: Demonstrates a modular approach that delegates tasks to specialized sub-agents or tools.
• Declarative Agent Configuration: Agents are defined using simple and intuitive YAML files, using a configuration-based approach.

Prerequisites

Before you begin, ensure you have the following tools installed:

• gcloud
• just
• uv

Installation

1. Clone the repository:

   git clone https://github.com/fmind/ackgent.git
   cd ackgent

2. Set up your environment:

   Create a .env file in the agent directory by copying the .env.sample file. Populate it with your GCP project ID and location.

   cp agent/.env.sample agent/.env
   # Edit agent/.env with your details

3. Install dependencies and set up hooks:

   just install

4. Configure Google Cloud:

   just cloud

Usage

This project uses just as a command runner. You can see all available commands by running just with no arguments.

Running the Agent Locally

To serve the agent's web interface locally for testing and interaction:

just web

This will start a local server with a web UI where you can chat with your agent.

Deploying to GCP

To deploy the agent to Google Cloud Run:

just deploy

You can customize the deployment with the following variables:

• log_level: The logging level (defaults to "info").
• service_name: The name of the Cloud Run service (defaults to "agent").

Example:

just deploy service_name="My Agent"

Available Agents

This project features a root_agent that acts as a dispatcher to more specialized agents.

Root Agent

• Name: root_agent
• Description: A helpful assistant for user questions.
• Capabilities: Can understand and respond to a wide range of queries by delegating to its sub-agents.

Sub-Agents

• datetime_agent:
  • Description: A helpful assistant for date and time questions.
  • Tools: now, today
• internet_agent:
  • Description: A helpful assistant for internet questions.
  • Tools: markitdown-mcp as an MCPToolset (STDIO)

Integration Testing with Evalsets

This project uses evalsets (*.evalset.json files) for robust integration testing. Evalsets are recorded conversations that capture user interactions and agent responses.

They are a powerful feature of the ADK, allowing you to:

• Create Reliable Tests: Build a suite of integration tests by recording complex, multi-turn conversations. These can be replayed automatically to ensure that agent behavior remains consistent and correct after code changes.
• Debug and Iterate: Analyze past conversations to identify and fix issues. The web UI allows you to inspect the full context of an interaction, making it easier to pinpoint the source of errors.
• Provide Executable Examples: Use evalsets as living documentation. They provide clear, executable examples of your agent's capabilities, which is invaluable for developers and stakeholders.

You can create and manage evalsets directly from the agent's web UI. For a comprehensive guide on creating and using evalsets, refer to the official ADK documentation:

• ADK Docs: Evaluating Agents

Limitations

• Tool and Sub-Agent Exclusivity: In root_agent.yaml, you cannot simultaneously use google_search or VertexAiSearchTool alongside sub-agents or other tools. However, you can work around this by embedding the search functionality within a custom tool.
• Python Dependency for ADK: The AgentConfig framework requires a Python environment with the ADK installed to extend its capabilities with custom tools and callbacks.

Tips and Tricks

• Python Version Alignment: Ensure your local Python version matches the one specified in the ADK's Dockerfile template to avoid deployment inconsistencies. You can find the version in ADK repository.
• Increase Reproducibility: Set the model's temperature to 0 in your agent's YAML configuration. This will make the agent's responses more deterministic and predictable, which is ideal for testing.
• Use Callbacks: Implement callbacks to intercept the agent's execution flow. This is useful for logging, monitoring, or modifying data before and after calls to the model or tools.
• Leverage Pre-Commit Hooks: Use pre-commit to automatically lint and format your code before committing. This helps maintain code quality and consistency across the project.
• Write Clear Tool Documentation: Provide detailed descriptions and instructions for your custom tools. This helps the language model understand how and when to use them effectively.
• Secure Your Deployments: Be cautious when deploying your agent to Cloud Run. Avoid exposing it to the public internet without proper authentication, especially in a corporate environment!
• Extend Capabilities with MCP: Use the MCP (Modular Command Protocol) to integrate external command-line tools and extend your agent's capabilities. This project uses it to integrate markitdown-mcp.

License

This project is licensed under the MIT License. See the LICENSE.txt file for details.