Adk Agent Studio
A comprehensive development environment for Google ADK (Agent Development Kit) Build, test, and deploy production-ready AI agents with an interactive UI, config-based creation, and zero boilerplate. Features include hierarchical agent structures, tool integration, sequential workflows, structured output, and instant code export.
Ask AI about Adk Agent Studio
Powered by Claude Β· Grounded in docs
I know everything about Adk Agent Studio. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
ADK Agent Manager
A comprehensive development environment for Google ADK (Agent Development Kit)
Build, test, and deploy production-ready AI agents with an interactive UI, config-based creation, and zero boilerplate. Features include hierarchical agent structures, tool integration, sequential workflows, structured output, MCP server management, and instant code export.
Features
- Interactive Web UI: Streamlit interface for creating, testing, and managing agents
- Configuration-driven: Define agents using JSON files with zero boilerplate
- Hierarchical Agents: Sub-agents and coordinator patterns for complex workflows
- Sequential Pipelines: Multi-step workflows with state passing between agents
- Tool System: Function-based and class-based tools with auto-discovery
- MCP Integration: Create and manage Model Context Protocol servers, connect agents to MCP tools
- Structured Output: JSON schemas with Pydantic validation for consistent responses
- AI-Powered: Auto-generate agent instructions and custom tools using AI
- Code Export: Generate standalone Python code from any agent configuration
- Session Management: Automatic conversation history and context retention
Installation
1. Prerequisites
- Python 3.8 or higher
- pip (Python package installer)
2. Clone and Setup
git clone <your-repository-url>
cd adk-agent-manager
# Create virtual environment
python -m venv venv
# Activate virtual environment
# Windows:
venv\Scripts\activate
# Unix/Mac/Linux:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
3. Environment Variables
Create agent_def/.env from the template:
cd agent_def
cp .env.example .env # or create manually
Edit agent_def/.env with your configuration:
# Google Cloud / Vertex AI Configuration
GOOGLE_GENAI_USE_VERTEXAI=false
GOOGLE_CLOUD_PROJECT=your_project_id
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_APPLICATION_CREDENTIALS=agent_def/sa/your-service-account-key.json
# Optional: Tool APIs
WEATHER_API_KEY=your_weather_api_key_here
SEARCH_API_KEY=your_search_api_key_here
SEARCH_ENGINE=google
# Optional: MCP Server Configuration
PORT=8000
TRANSPORT=http
Getting API Keys:
- Google AI API Key: Get from Google AI Studio (required if not using Vertex AI)
- Vertex AI: Set
GOOGLE_GENAI_USE_VERTEXAI=trueand provide project ID, location, and service account credentials - Weather/Search APIs: Optional, for enhanced tool functionality
Note: The .env file is git-ignored. Never commit API keys or credentials to version control.
Quick Start
Web UI (Recommended)
Launch the interactive interface:
streamlit run app.py
# Or use the platform-specific scripts:
# Windows: run_ui.bat
# Unix/Mac: bash run_ui.sh
Open http://localhost:8501 to:
- Browse and test pre-configured agents
- Chat with agents (conversation history maintained)
- Create new agents with AI-assisted form
- Build MCP servers from your tools
- Export agents as standalone Python code
Python Code
import asyncio
from agent_def import AgentManager
async def main():
# Create agent from config
agent = AgentManager("configs/01_basic_template_agent.json")
await agent.initialize()
# Send messages
response = await agent.send_message("Hello! How can you help me?")
print(response)
# Cleanup
await agent.close()
asyncio.run(main())
Example Scripts
python example_usage.py # Basic agent usage
python example_structured_output.py # JSON schema examples
python example_mcp_usage.py # MCP server examples
python example_mcp_integration.py # Agent + MCP integration
Core Concepts
Agent Configuration
Agents are defined in JSON files stored in configs/. Basic structure:
{
"app_name": "my_agent",
"agent_type": "llm",
"agent": {
"name": "my_agent",
"model": "gemini-2.5-flash",
"description": "Brief description of what this agent does",
"instruction": "You are an expert assistant. Help users with..."
},
"tools": ["calculator", "WebSearchTool"],
"sub_agents": ["specialist_agent"],
"mcp_servers": [{"config": "calculator_server"}],
"example_queries": ["What can you help me with?"]
}
Key Fields:
- app_name: Unique identifier for the agent
- agent_type:
"llm"(intelligent) or"sequential"(workflow pipeline) - agent.name: Display name (must be valid Python identifier)
- agent.model: AI model (e.g., "gemini-2.5-flash", "gemini-2.5-pro")
- agent.instruction: System prompt defining behavior (required for LLM agents)
- agent.response_schema: JSON schema for structured output (optional)
- agent.output_key: State variable name for sequential workflows (optional)
- tools: Array of tool names from
tools/directory (optional) - sub_agents: Array of sub-agent config names (optional)
- mcp_servers: Array of MCP server connections (optional)
- example_queries: Array of sample queries for UI display (optional)
Tools
Tools extend agent capabilities. Two types are supported:
Function-based tools (simple, stateless):
# tools/my_tool.py
async def my_tool(param: str) -> str:
"""Tool description."""
return f"Processed: {param}"
Class-based tools (with state, setup/teardown):
# tools/my_advanced_tool.py
from agent_def.base_tool import BaseTool, ToolParameter
class MyAdvancedTool(BaseTool):
@property
def name(self) -> str:
return "my_advanced_tool"
@property
def description(self) -> str:
return "What this tool does"
@property
def parameters(self) -> list[ToolParameter]:
return [
ToolParameter(name="input", type="string", required=True)
]
async def execute(self, **kwargs) -> str:
params = self.validate_parameters(**kwargs)
return f"Result: {params['input']}"
Using Tools:
Add tool names to agent config's tools array. Configure via environment variables in .env:
SEARCH_API_KEY=your_api_key
DATABASE_URL=postgresql://localhost/db
Sub-Agents
Create hierarchical agent systems where coordinators delegate to specialists:
{
"agent": {
"name": "coordinator",
"instruction": "Delegate greetings to greeting_agent, farewells to farewell_agent"
},
"tools": ["get_weather"],
"sub_agents": ["greeting_agent", "farewell_agent"]
}
Sub-agents:
- Share the parent's session (conversation history)
- Can have their own tools and sub-agents (nested hierarchies)
- Are loaded automatically from
configs/{agent_name}.json
Sequential Workflows
For fixed pipelines where agents run in order:
{
"agent_type": "sequential",
"agent": {
"name": "CodePipelineAgent",
"description": "Write β Review β Refactor pipeline"
},
"sub_agents": [
"code_writer_agent",
"code_reviewer_agent",
"code_refactorer_agent"
]
}
State Passing: Use output_key to pass data between pipeline steps:
// Step 1: Writer
{
"agent": {
"name": "code_writer_agent",
"instruction": "Write code based on requirements",
"output_key": "generated_code"
}
}
// Step 2: Reviewer (uses {generated_code})
{
"agent": {
"name": "code_reviewer_agent",
"instruction": "Review:\n```\n{generated_code}\n```\nProvide feedback",
"output_key": "review_comments"
}
}
// Step 3: Refactorer (uses {generated_code} and {review_comments})
{
"agent": {
"name": "code_refactorer_agent",
"instruction": "Original: {generated_code}\nReview: {review_comments}\nRefactor it",
"output_key": "refactored_code"
}
}
Structured Output
Define JSON schemas for consistent, parseable responses:
{
"agent": {
"name": "product_analyzer",
"instruction": "Extract product information",
"response_schema": {
"type": "object",
"properties": {
"product_name": {
"type": "string",
"description": "Product name"
},
"category": {
"type": "string",
"description": "Product category"
},
"key_features": {
"type": "array",
"items": {"type": "string"},
"description": "List of features"
},
"price_range": {
"type": "string",
"enum": ["budget", "mid-range", "premium"]
}
},
"required": ["product_name", "category"]
}
}
}
Usage:
agent = AgentManager("configs/10_structured_product_analyzer_agent.json")
await agent.initialize()
response = await agent.send_message("Analyze: iPhone 15 Pro...")
# Response is a Python dict, not a string
print(response["product_name"]) # "iPhone 15 Pro"
print(response["category"]) # "Electronics"
print(response["key_features"]) # ["A17 Pro chip", ...]
MCP Integration
Connect agents to Model Context Protocol servers for distributed tool access.
MCP Server Configuration (configs_mcp/calculator_server.json):
{
"server": {
"name": "Calculator Server",
"description": "MCP server with calculator tools",
"transport": "http",
"host": "0.0.0.0",
"port": 8000
},
"tools": [
{
"file": "calculator.py",
"type": "function",
"function_name": "calculator"
}
]
}
Transport Options:
- stdio: For Claude Desktop / IDE integration
- http: For network access
- sse: For streaming updates
Using MCP Servers in Agents:
{
"agent": {
"name": "mcp_agent",
"instruction": "You have access to calculator tools"
},
"mcp_servers": [
{
"config": "01_calculator_server",
"url": "http://localhost:8000",
"auto_start": false
}
]
}
MCP Server Options:
- config: Reference to config file in
configs_mcp/(without.json) - url: Direct URL to connect to (optional if in config file)
- auto_start: Start server automatically when agent initializes (requires http/sse)
Connection Scenarios:
- Connect to running server: Provide
urlonly - Auto-start server: Set
auto_start: truewithconfig(http/sse only) - Mixed tools: Combine local
toolsarray withmcp_servers
Example:
# Agent auto-starts MCP server and uses its tools
agent = AgentManager("configs/14_mcp_auto_start_agent.json")
await agent.initialize() # Server starts in background
response = await agent.send_message("Calculate 123 * 456")
await agent.close() # Server stops automatically
Web UI Guide
The Streamlit interface provides a complete environment for agent development.
Main Tabs
π¬ Chat Mode
- Interactive conversations with agents
- Persistent conversation history
- Multi-turn context retention
- "New Chat" and "Clear History" controls
- Session state debugging tools
π― Single Execution
- One-time query testing
- Immediate results (text or JSON)
- Download responses
- Example queries sidebar
π Agent Details
- Configuration overview
- Agent type, model, capabilities
- Tools, sub-agents, and MCP servers list
- Instructions and descriptions
- Structured output schema viewer
- Code export with download
- Raw JSON configuration
π MCP Servers
- Browse available MCP servers
- View server configurations and tools
- Initialize and test servers
- Export config for Claude Desktop/Cursor
- Usage instructions
β Create Agent
- Interactive form for new agents
- AI-powered instruction generation
- Tool and sub-agent selection
- MCP server integration
- Structured output schema builder
- Real-time validation
- Preview and save
β Create MCP Server
- Build MCP servers from existing tools
- Transport protocol selection (stdio/http/sse)
- Tool selection with type detection
- Configuration preview
- Save and reload
Creating Agents via UI
- Navigate to β Create Agent tab
- Fill in basic information:
- App Name (unique identifier)
- Agent Type (LLM or Sequential)
- Model (Gemini 2.5 Flash/Pro)
- Description
- Generate Instructions with AI (optional):
- Enter name and description
- Click β¨ Generate with AI
- AI populates the instructions field
- Add Tools & Sub-Agents (optional):
- Select from
tools/directory - Choose sub-agents from
configs/
- Select from
- Connect MCP Servers (optional):
- Select servers from
configs_mcp/ - Configure URL and auto-start options
- Select servers from
- Add Example Queries (optional):
- Define sample queries for testing
- Enable Structured Output (optional):
- Toggle schema builder
- Define output fields with types
- Preview or Create agent
- Click Reload UI to see new agent
Creating MCP Servers via UI
- Navigate to β Create MCP Server tab
- Write Custom Function (optional):
- Expand "Create New Function"
- Enter function name and description
- Click β¨ Generate with AI for automatic code
- Edit generated code as needed
- Click πΎ Save Function
- Click π Refresh Tools List
- Configure server:
- Server Name
- Config File Name
- Description
- Transport protocol (stdio/http/sse)
- Host and Port (for http/sse)
- Select tools to include
- Preview Config or Create Server
Exporting Agent Code
- Select an agent
- Go to π Agent Details tab
- Click π€ Generate Code
- View standalone Python code
- Download as
.pyfile
The exported code includes:
- All imports and dependencies
- Tool imports with proper instantiation
- Pydantic models for structured output
- MCP toolset initialization (if used)
- Session and runner setup
- Complete usage example
- Prerequisites in comments
Project Structure
adk-agent-manager/
βββ agent_def/
β βββ __init__.py # Exports AgentManager
β βββ agent.py # AgentManager implementation
β βββ base_tool.py # BaseTool abstract class
β βββ tool_loader.py # Tool loading system
β βββ .env # Environment variables (create this)
β βββ .env.example # Environment template
βββ mcp_def/
β βββ __init__.py # MCP package init
β βββ mcp_manager.py # MCPServerManager class
β βββ server.py # Standalone MCP server template
βββ configs/ # Agent configurations
β βββ 01_basic_template_agent.json
β βββ 02_tools_assistant_agent.json
β βββ 03_subagents_coordinator_agent.json
β βββ 10_structured_product_analyzer_agent.json
β βββ 12_mcp_calculator_agent.json
β βββ helper_prompt_generator_agent.json
β βββ ...
βββ configs_mcp/ # MCP server configurations
β βββ 01_calculator_server.json
β βββ 02_weather_server.json
β βββ 03_multi_tool_server.json
β βββ ...
βββ tools/ # Tool implementations
β βββ calculator.py # Function-based tool
β βββ web_search_tool.py # Class-based tool
β βββ get_weather.py # Weather tool
β βββ ...
βββ app.py # Streamlit Web UI
βββ example_usage.py # Basic usage examples
βββ example_structured_output.py # Structured output examples
βββ example_mcp_usage.py # MCP server examples
βββ example_mcp_integration.py # Agent + MCP examples
βββ requirements.txt # Python dependencies
βββ run_ui.bat # Windows UI launcher
βββ run_ui.sh # Unix/Mac UI launcher
βββ .gitignore # Git ignore rules
βββ README.md # This file
API Reference
AgentManager
AgentManager(config_path: str)
- Initialize agent manager with configuration file
- Automatically generates unique user_id and session_id
async initialize()
- Create agent from config
- Load tools and sub-agents
- Connect to MCP servers
- Set up session and runner
- Must be called before sending messages
async send_message(query: str, return_json: bool = False) -> str | dict
- Send message to agent
- Returns string by default
- Returns dict if
return_json=Trueor agent hasresponse_schema
get_conversation_history() -> list[dict]
- Get conversation history from session
- Returns list of message dicts with
roleandcontent
async close()
- Cleanup resources
- Stop auto-started MCP servers
- Close agent connections
MCPServerManager
MCPServerManager(config_path: str)
- Initialize MCP server manager with config file
initialize()
- Load and register all tools from config
- Prepare server for start
start_server()
- Start MCP server (blocks for stdio, background for http/sse)
stop_server()
- Stop running server (for http/sse)
get_config() -> dict
- Get server configuration
export_config_for_claude() -> dict
- Export Claude Desktop compatible config
Advanced Usage
Multi-turn Conversations
Agents maintain conversation history within sessions:
agent = AgentManager("configs/01_basic_template_agent.json")
await agent.initialize()
# Context is preserved across messages
await agent.send_message("My name is Alice")
await agent.send_message("What's my name?") # Agent remembers "Alice"
# Get full history
history = agent.get_conversation_history()
for msg in history:
print(f"{msg['role']}: {msg['content']}")
Environment Variables
Load configuration from .env using python-dotenv:
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("GOOGLE_API_KEY")
project = os.getenv("GOOGLE_CLOUD_PROJECT")
Claude Desktop Integration
To use MCP servers with Claude Desktop:
- Create MCP server in UI or via config
- In MCP Servers tab, select server
- Click π₯ Export for Claude
- Copy JSON configuration
- Add to Claude Desktop config:
- Mac:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Mac:
{
"mcpServers": {
"Calculator Server": {
"command": "python",
"args": ["-m", "mcp_def.mcp_manager", "configs_mcp/01_calculator_server.json"],
"description": "Calculator tools for Claude"
}
}
}
Troubleshooting
"Module not found" errors:
# Ensure virtual environment is activated
# Windows:
venv\Scripts\activate
# Unix/Mac:
source venv/bin/activate
# Reinstall dependencies
pip install -r requirements.txt
"GOOGLE_API_KEY not found":
- Create
agent_def/.envfile - Add
GOOGLE_API_KEY=your_key_here - Restart application
"Failed to connect to MCP server":
- Ensure MCP server is running at specified URL
- Check firewall settings
- Verify port is not in use
- For auto-start: ensure http/sse transport (not stdio)
"Agent name validation error":
- Agent names must be valid Python identifiers
- Use underscores instead of spaces
- Start with letter or underscore
- UI automatically converts spaces to underscores
"Tools not loading":
- Check tool files exist in
tools/directory - Verify function/class names match config
- For class tools, check inheritance from
BaseTool - Review tool logs in console
License
MIT License - feel free to use this template for your own projects!
