Customizing Reflection Prompts¶

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm

# Define agent with template placeholders
agent = LlmAgent(
    name="Reflector",
    model=LiteLlm(model="ollama_chat/llama3.2:latest"),
    instruction="""## Component Text
{component_text}

## Trial Results
{trials}

Improve the component text based on the trials.""",
)

# Session state is set up automatically by gepa-adk
# ADK's inject_session_state() replaces {component_text} and {trials}

# gepa-adk automatically handles serialization:
session_state = {
    "component_text": "Be helpful",  # String - used as-is
    "trials": json.dumps(trials),    # List → JSON string
}

from gepa_adk import evolve, EvolutionConfig

config = EvolutionConfig(
    reflection_prompt="""You are improving an AI agent's instructions.

## Current Instruction
{component_text}

## Evaluation Results
{trials}

## Your Task
Based on the feedback, propose ONE specific improvement to the instruction.
Focus on the most impactful change.

Return ONLY the improved instruction text."""
)

result = await evolve(
    agent=my_agent,
    trainset=test_cases,
    critic=my_critic,
    config=config,
)

from gepa_adk import evolve, EvolutionConfig
from gepa_adk.engine.adk_reflection import REFLECTION_INSTRUCTION

# Add domain-specific context to the default
custom_prompt = REFLECTION_INSTRUCTION + """

Additional Guidelines:
- Focus on clarity and conciseness
- Preserve any safety constraints in the original
- Consider edge cases mentioned in feedback
"""

config = EvolutionConfig(reflection_prompt=custom_prompt)

from gepa_adk import evolve

# reflection_prompt defaults to None → uses REFLECTION_INSTRUCTION
result = await evolve(
    agent=my_agent,
    trainset=test_cases,
    critic=my_critic,
)

# This will log a warning about missing {trials}
config = EvolutionConfig(
    reflection_prompt="Improve this: {component_text}"
)

# Good: Clear output expectation
prompt = """...
Return ONLY the improved instruction text, with no additional commentary.
"""

# Also good: Structured output
prompt = """...
Respond with exactly this JSON structure:
{
  "analysis": "Brief analysis",
  "improved_instruction": "The improved text"
}
"""

prompt = """...
## Your Task
1. Address the issues identified in negative feedback
2. Preserve elements that worked well in positive feedback
3. Maintain clarity and specificity
4. Keep the instruction concise (under 200 words)
"""

minimal_prompt = """Instruction:
{component_text}

Feedback:
{trials}

Improved instruction:"""

cot_prompt = """You are an expert at improving AI instructions.

## Current Instruction
{component_text}

## Performance Feedback
{trials}

## Analysis Process
1. What patterns appear in successful examples?
2. What patterns appear in failed examples?
3. What specific changes would address the failures while preserving successes?

Think through each step, then provide the improved instruction.

## Improved Instruction
"""

json_prompt = """Analyze the agent instruction and feedback, then respond with JSON.

## Current Instruction
{component_text}

## Feedback
{trials}

Respond with exactly this JSON structure:
{
  "analysis": "Brief analysis of what's working and what isn't",
  "improved_instruction": "The complete improved instruction text"
}
"""

code_review_prompt = """You are improving a code review agent's instructions.

## Current Instruction
{component_text}

## Evaluation Feedback
{trials}

## Domain Guidelines
- The agent should identify bugs, security issues, and style problems
- Feedback should be actionable and specific
- Code examples should be provided when suggesting fixes
- Tone should be constructive, not critical

Provide an improved instruction that addresses the feedback while
following these domain guidelines.

## Improved Instruction
"""

from gepa_adk import evolve, EvolutionConfig

# Local model (default)
config = EvolutionConfig(
    reflection_model="ollama_chat/gpt-oss:20b",
)

# Cloud model (OpenAI)
config = EvolutionConfig(
    reflection_model="gpt-4o-mini",
)

# Cloud model (Anthropic)
config = EvolutionConfig(
    reflection_model="claude-3-haiku-20240307",
)

from gepa_adk.engine.adk_reflection import REFLECTION_INSTRUCTION

# See what the default looks like
print(REFLECTION_INSTRUCTION)

# Test your custom prompt with sample values
my_prompt = "..."
formatted = my_prompt.format(
    component_text="Be helpful",
    trials="Example 1: Score 0.5..."
)
print(formatted)

# OLD: Data embedded directly in user message
user_message = f"""## Component Text to Improve
{component_text}

## Trials
{json.dumps(trials, indent=2)}

Propose an improved version..."""

async for event in runner.run_async(
    user_id="reflection",
    session_id=session_id,
    new_message=Content(role="user", parts=[Part(text=user_message)]),
):
    events.append(event)

# NEW: Data in session state, placeholders in instruction
agent = LlmAgent(
    name="Reflector",
    model=LiteLlm(model="ollama_chat/llama3.2:latest"),
    instruction="""## Component Text to Improve
{component_text}

## Trials
{trials}

Propose an improved version...""",
)

# Session state set during session creation
session_state = {
    "component_text": component_text,
    "trials": json.dumps(trials),  # Pre-serialize complex types
}

await session_service.create_session(
    app_name="gepa_reflection",
    user_id="reflection",
    session_id=session_id,
    state=session_state,
)

# Simple trigger message - ADK handles substitution
async for event in runner.run_async(
    user_id="reflection",
    session_id=session_id,
    new_message=Content(role="user", parts=[Part(text="Improve the component.")]),
):
    events.append(event)