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
1 maintainer
Metadata
1 maintainer
Release files for gepa-adk 2.7.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| gepa_adk-2.7.5.tar.gz | 263.8 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gepa_adk-2.7.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 561.0 kB
Release files / gepa_adk-2.7.5.tar.gz
| Download URL | gepa_adk-2.7.5.tar.gz |
|---|---|
| Size | 263.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f94d1c3dc58515bd6c8dee54f213a393a3d465962ca508f75eb989992d56599f
|
|
BLAKE2b-256 checksum How to use checksums |
de585067022570a1b5d467cfa8f65746183c900220a5327b7603720c767d102c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logRelease files / gepa_adk-2.7.5-py3-none-any.whl
| Download URL | gepa_adk-2.7.5-py3-none-any.whl |
|---|---|
| Size | 297.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ed6d404c2b754087860a0aced2b6789138495b9e076fd963556a458b05f50e55
|
|
BLAKE2b-256 checksum How to use checksums |
79e5aa6bf19a8932719e1702babf04ff4cf63770c5565684d1e6e0b268f72725
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logSecurity for gepa-adk 2.7.5
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for gepa_adk-2.7.5.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
