Skip to content

google_adk

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

google_adk

README.md

IBM i MCP Agents: Google ADK

AI agents for IBM i system administration and monitoring built with Google's Agent Development Kit (ADK) and Model Context Protocol (MCP) tools. This project provides intelligent agents that can analyze IBM i system performance, manage resources, and assist with administrative tasks.

What is this project?

The IBM i MCP Agents project provides Python-based intelligent agents that leverage MCP tools to perform system administration tasks on IBM i systems using Google's ADK framework.

Key Features

  • Multiple Specialized Agents: Five purpose-built agents for different IBM i tasks
  • Multi-Agent Coordination: Intelligent routing between specialized sub-agents
  • Multi-Model Support: Works with Google Gemini, OpenAI, Anthropic, and other providers via LiteLLM
  • MCP Integration: Connects to the IBM i MCP Server for system operations
  • Interactive Web UI: Built-in ADK Web interface for testing and debugging
  • Evaluation Framework: Track and analyze agent performance

Available Agents

  1. Performance Agent - Monitor and analyze system performance metrics (CPU, memory, I/O)
  2. Security Agent - Analyze security configurations, vulnerabilities, and compliance
  3. Discovery Agent - High-level system discovery, inventory, and service summaries
  4. Browse Agent - Detailed exploration of system services by category or schema
  5. Search Agent - Find specific services, programs, or system resources

Requirements

  • Python 3.13+ - The project requires Python 3.13 or newer
  • uv - Python package manager for installing dependencies (Install uv)
  • IBM i MCP Server - Must be installed and running on your system
  • API Keys - For your chosen LLM provider (Google AI, OpenAI, Anthropic, or others)

Setup Guide

Follow these step-by-step instructions to set up and run the IBM i Google ADK MCP Agents.

Step 1: Install Prerequisites

1.1 Install Python 3.13+

# Check your Python version
python --version  # or python3 --version

# If you need to install Python 3.13+, visit:
# https://www.python.org/downloads/

1.2 Install uv (Python package manager)

# On macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Alternative: Install via pip
pip install uv

Step 2: Set Up the IBM i MCP Server

Ensure you have the IBM i MCP Server installed and running.

Note

Follow the MCP Server installation guide → Quickstart Guide

Configure the server → Server Configuration Guide

2.1 Install dependencies and build the server:

cd ibmi-mcp-server
npm install
npm run build

2.2 Start the MCP server:

npx ibmi-mcp-server --transport http --tools ./tools

The server will start on http://127.0.0.1:3010/mcp by default.

Step 3: Configure Environment Variables

Create a .env file in the agents/frameworks/google_adk directory:

cd agents/frameworks/google_adk
touch .env

3.1 Choose your model provider:

Option A: Google AI (Simplest - Recommended)

  1. Get an API key from Google AI Studio
  2. Add to your .env file:
# Google AI Configuration
GOOGLE_API_KEY=your_google_api_key_here
IBMI_AGENT_MODEL=gemini-2.0-flash-exp

# IBM i MCP Server
IBMI_MCP_ACCESS_TOKEN=your_mcp_token
IBMI_MCP_SERVER_URL=http://127.0.0.1:3010/mcp

Option B: Vertex AI (Enterprise)

  1. Create a Google Cloud Project
  2. Enable Vertex AI API
  3. Create service account credentials
  4. Add to your .env file:
# Vertex AI Configuration
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_APPLICATION_CREDENTIALS=secrets/credentials.json
VERTEX_AI_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=TRUE
IBMI_AGENT_MODEL=gemini-2.0-flash-exp

# IBM i MCP Server
IBMI_MCP_ACCESS_TOKEN=your_mcp_token
IBMI_MCP_SERVER_URL=http://127.0.0.1:3010/mcp

Option C: OpenAI via LiteLLM

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key
IBMI_AGENT_MODEL=gpt-4o

# IBM i MCP Server
IBMI_MCP_ACCESS_TOKEN=your_mcp_token
IBMI_MCP_SERVER_URL=http://127.0.0.1:3010/mcp

Option D: Anthropic via LiteLLM

# Anthropic Configuration
ANTHROPIC_API_KEY=your_anthropic_api_key
IBMI_AGENT_MODEL=claude-3-5-sonnet-20241022

# IBM i MCP Server
IBMI_MCP_ACCESS_TOKEN=your_mcp_token
IBMI_MCP_SERVER_URL=http://127.0.0.1:3010/mcp

Step 4: Install Dependencies

cd agents/frameworks/google_adk
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

Step 5: Run an Agent

5.1 Using the ADK Web UI (Recommended):

cd agents/frameworks/google_adk
adk web

This will:

  • Start a local web server
  • Open your browser to the ADK Web UI
  • Load the multi-agent system from adk_agents/

5.2 Using the command line:

# Run a specific agent with a query
uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "Show me system CPU usage"

# List available agents
uv run src/ibmi_agents/agents/ibmi_agents.py --list-agents

5.3 Interact with the agent CLI:

cd agents/frameworks/google_adk
adk run adk_agents
  • Type your questions or requests at the prompt
  • The agent will use IBM i MCP tools to fulfill your requests
  • Type exit to end the session

Usage Examples

Performance Monitoring

uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "What is the current CPU utilization?"

Example questions:

  • "Show me system CPU usage"
  • "What are the top 10 CPU consumers?"
  • "Analyze memory pool utilization"

Security Analysis

uv run src/ibmi_agents/agents/ibmi_agents.py --agent security --query "Check system security configuration"

Example questions:

  • "Analyze system security vulnerabilities"
  • "Check user access controls"
  • "Review security compliance"

System Discovery

uv run src/ibmi_agents/agents/ibmi_agents.py --agent discovery --query "List all available schemas"

Example questions:

  • "Give me an overview of the system services"
  • "What databases are available?"
  • "Show me system categories"

Detailed Browsing

uv run src/ibmi_agents/agents/ibmi_agents.py --agent browse --query "Navigate to QSYS2 library"

Example questions:

  • "Show me details about the QSYS library"
  • "Explore the database schemas"
  • "What's in the QTEMP library?"

System Search

uv run src/ibmi_agents/agents/ibmi_agents.py --agent search --query "Find services related to performance"

Example questions:

  • "Find all programs named CUST*"
  • "Search for SQL examples with 'CPU'"
  • "Locate file CUSTOMER in any library"

Advanced Options

Debug Mode

Enable verbose output to troubleshoot issues:

uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "Show me CPU usage" --verbose

Quiet Mode

Only show final response without logs:

uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "Show me CPU usage" --quiet

Custom Model

Use a different model:

# Use Gemini 2.5 Flash
uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "Show me CPU usage" --model "gemini-2.5-flash"

# Use OpenAI GPT-4o
uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "Show me CPU usage" --model "gpt-4o"

# Use Anthropic Claude
uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "Show me CPU usage" --model "claude-3-5-sonnet-20241022"

Architecture Overview

How It Works

  1. Agent Selection: You choose an agent specialized for a specific task (performance, discovery, etc.)
  2. MCP Connection: The agent connects to the IBM i MCP Server via HTTP
  3. Tool Filtering: Each agent only has access to relevant tools (e.g., performance agent gets performance tools)
  4. Model Execution: Gemini model processes requests and generates tool calls
  5. Multi-Agent Coordination: The coordinator routes complex queries to appropriate sub-agents

Supported Models

Google Gemini Models

Model Description Best For
gemini-3-pro-preview Preview of next generation Advanced capabilities
gemini-2.5-pro State-of-the-art thinking model Advanced capabilities
gemini-2.5-flash Stable flash model Production workloads
gemini-2.0-flash-exp Latest experimental flash model Fast responses, general tasks
gemini-2.0-pro-exp Experimental pro model Complex reasoning

OpenAI Models and Anthropic Models (via LiteLLM or Vertex AI)

Model Description
gpt-4o Latest GPT-4 Optimized
claude-3-5-sonnet-20241022 Latest Claude 3.5 Sonnet

Vertex AI Model Garden

Access additional models through Vertex AI Model Garden:

  • Meta Llama models
  • Mistral models
  • And more

For complete model information, see Google ADK Models Documentation.

Multi-Agent System

The adk_agents/ directory contains a sophisticated multi-agent system with a coordinator that intelligently routes queries to specialized sub-agents. See Multi-Agent System Documentation for details.

Troubleshooting

IBM i MCP Server Issues

Connection errors:

  • Verify the MCP server is running: curl http://127.0.0.1:3010/mcp
  • Check IBMI_MCP_ACCESS_TOKEN is set correctly
  • Ensure the server URL matches your configuration

Google AI / Vertex AI Issues

API key not valid:

  • Verify your GOOGLE_API_KEY is correct
  • Check the API key is enabled in Google Cloud Console
  • Ensure you've enabled the Gemini API

Permission denied (403):

  • Verify service account has "Vertex AI User" role
  • Check billing is enabled for your project
  • Ensure Vertex AI API is enabled

Model not found:

  • Verify model name in IBMI_AGENT_MODEL
  • Check Google AI Studio for available models
  • For OpenAI/Anthropic: Ensure correct API key is set
  • Try using gemini-2.0-flash-exp as a default

Rate limit exceeded (429):

  • You've hit API rate limits
  • For Google AI: Check quota limits
  • For Vertex AI: Review quota settings
  • For OpenAI: Check usage limits
  • For Anthropic: Review rate limits
  • Solutions:
    • Wait and retry (rate limits reset over time)
    • Upgrade your plan for higher limits
    • Request quota increases from your provider
    • Switch to a different model or provider
    • Implement exponential backoff in your code

Environment variable not set:

  • Ensure .env file is in agents/frameworks/google_adk/
  • Verify variable names are spelled correctly (case-sensitive)
  • Use --verbose flag to check if .env is being loaded

LiteLLM configuration:

  • Set LITELLM_API_KEY for OpenAI or Anthropic
  • Model names must match provider format:
    • OpenAI: gpt-4o, gpt-4o-mini
    • Anthropic: claude-3-5-sonnet-20241022
  • For custom endpoints, see LiteLLM docs

ADK Web UI Issues

Web UI doesn't load:

  • Clear browser cache and reload
  • Check browser console for errors (F12 → Console)
  • Ensure adk web command is running
  • Verify network connectivity

Agent not responding:

  • Check IBM i MCP server is running
  • Verify IBMI_MCP_ACCESS_TOKEN is set
  • Review execution traces in the UI
  • Check .adk/eval_history/ for detailed logs

Debug Tips

  1. Enable verbose logging:

    uv run src/ibmi_agents/agents/ibmi_agents.py --agent performance --query "test" --verbose

  2. Test Google Cloud setup:

    gcloud auth application-default print-access-token
gcloud config get-value project

  3. Verify credentials file:

    cat secrets/credentials.json | python -m json.tool

For more troubleshooting information, see Google ADK Troubleshooting.

Resources

License

This project is licensed under the MIT License - see the LICENSE file for details.