gepa-adk 0.3.1

Evolutionary optimization for Google ADK agents

gepa-adk

Evolutionary optimization for Google ADK agents.

What is this?

gepa-adk makes your AI agents better automatically. It takes an agent, runs it against examples, gets feedback from a critic, and evolves the agent's instructions until performance improves.

Think of it as natural selection for AI prompts—the best instructions survive and improve.

Installation

pip install gepa-adk

Requirements: Python 3.12+, a Gemini API key (or other ADK-supported model)

export GOOGLE_API_KEY=your-api-key

Quick Start

The simplest way to evolve an agent: provide a critic to score outputs.

import asyncio
from google.adk.agents import LlmAgent
from pydantic import BaseModel, Field
from gepa_adk import evolve, CriticOutput

# Your agent to evolve
agent = LlmAgent(
    name="assistant",
    model="gemini-2.0-flash",
    instruction="You are a helpful assistant.",
)

# A critic that scores the agent's output (0.0-1.0)
critic = LlmAgent(
    name="critic",
    model="gemini-2.0-flash",
    instruction="Score the response for helpfulness and accuracy.",
    output_schema=CriticOutput,  # Has score: float and feedback: str
)

# Training examples
trainset = [
    {"input": "What is 2+2?"},
    {"input": "Explain photosynthesis briefly."},
]

# Evolve!
result = asyncio.run(evolve(agent, trainset, critic=critic))

print(f"Score: {result.original_score:.2f} -> {result.final_score:.2f}")
print(f"Evolved instruction:\n{result.evolved_instruction}")

That's it. The critic provides feedback, a reflection agent proposes improvements, and evolution finds better instructions.

Key Concepts

• Agent: The ADK agent whose instruction you want to improve
• Critic: Scores the agent's output (0.0-1.0) and provides feedback
• Trainset: Examples to evaluate against
• Evolution: Iterative improvement using reflection and selection

Examples

See examples/ for complete working code:

• basic_evolution.py — Single agent with critic scoring
• critic_agent.py — Custom critic for story generation
• multi_agent.py — Evolving multiple agents together

Configuration

from gepa_adk import evolve, EvolutionConfig

config = EvolutionConfig(
    max_iterations=5,   # Maximum evolution iterations
    patience=2,         # Stop early if no improvement
)

result = await evolve(agent, trainset, critic=critic, config=config)

Documentation

• Getting Started
• Single-Agent Guide
• Critic Agents Guide
• API Reference

Status

In Development — API may change.

Credits

Implements concepts from GEPA (Genetic-Pareto optimization) and integrates with Google ADK.

License

Apache License 2.0 - see LICENSE for details.