gepa-adk

Evolutionary optimization for Google ADK agents.

What is this?

gepa-adk evolves AI agent instructions automatically. Give it an agent and training examples, and it finds better prompts through iterative improvement using genetic algorithms and Pareto frontier selection.

Supports single-agent evolution, multi-agent co-evolution, workflow optimization (Sequential, Loop, Parallel agents), output schema evolution, generation config tuning, and multimodal inputs including video.

Requirements

• Python 3.12 or 3.13 (>=3.12,<3.14)
• Ollama with a local model (recommended for development), or any model supported by LiteLLM

Installation

pip install gepa-adk

For database-backed ADK sessions (DatabaseSessionService, used by examples/app_runner_integration.py), install the db extra:

pip install "gepa-adk[db]"

The extra forwards to google-adk[db]. On ADK 1.x, which has no db extra, pip prints a harmless unknown-extra warning and installs normally.

# For local models (recommended)
export OLLAMA_API_BASE=http://localhost:11434

Quick Start

Evolve a greeting agent to produce formal, Dickens-style greetings:

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from gepa_adk import evolve, run_sync, EvolutionConfig, SimpleCriticOutput

model = LiteLlm(model="ollama_chat/llama3.2:latest")

agent = LlmAgent(
    name="greeter",
    model=model,
    instruction="Greet the user appropriately.",
)

critic = LlmAgent(
    name="critic",
    model=model,
    instruction="Score for formal, Dickens-style greetings. 0.0-1.0.",
    output_schema=SimpleCriticOutput,
)

trainset = [
    {"input": "I am His Majesty, the King."},
    {"input": "I am your mother."},
    {"input": "I am a close friend."},
]

config = EvolutionConfig(
    max_iterations=5,
    patience=1,
    reflection_model="ollama_chat/llama3.2:latest",
)
result = run_sync(evolve(agent, trainset, critic=critic, config=config))
print(f"Score: {result.original_score:.2f} -> {result.final_score:.2f}")
print(result.evolved_components["instruction"])

When you have labelled examples, score with plain code instead of a critic agent. LabelAgreementScorer scores 1.0 when the output (or one JSON field of it) equals the row's expected label after stripping whitespace, else 0.0. Any object with score and async_score methods (the Scorer protocol, from gepa_adk import Scorer) also works as scorer=. critic= and scorer= are mutually exclusive:

from gepa_adk import LabelAgreementScorer

trainset = [{"input": "I am your mother.", "expected": "Dearest Mother, how fare you?"}]
# For JSON output, LabelAgreementScorer(field="label") compares that one field
# instead of the whole output.
result = run_sync(evolve(agent, trainset, scorer=LabelAgreementScorer(), config=config))

Examples

Getting started:

• basic_evolution.py — Single agent with critic
• basic_evolution_adk_reflection.py — Single agent evolution with an ADK reflection agent
• critic_agent.py — Story generation with dedicated critic
• custom_reflection_prompt.py — Custom reflection prompts

Multi-agent & workflows:

• multi_agent.py — Multi-agent co-evolution
• loop_agent_evolution.py — LoopAgent workflow evolution
• parallel_agent_evolution.py — ParallelAgent workflow evolution
• nested_workflow_evolution.py — Nested workflow evolution
• multi_agent_component_demo.py — Per-agent component evolution in a multi-agent pipeline
• sandwich_evolution.py — Nested workflow evolution that preserves the workflow structure

Advanced:

• schema_evolution_example.py — Output schema evolution
• schema_evolution_critic.py — Output schema evolution via critic feedback
• schema_reflection_demo.py — Schema reflection with validation
• config_evolution_demo.py — Generation config evolution
• video_transcription_evolution.py — Video input evolution
• app_runner_integration.py — ADK App/Runner integration

Documentation

Getting Started · Guides · API Reference

Credits

Based on GEPA (source). Built on Google ADK (source).

License

Apache 2.0