Evaluation-Driven Prompt Learning

Prompt engineering usually begins as a manual activity:

1. write a prompt
2. try a few inputs
3. inspect the answers
4. rewrite the prompt

That works for a prototype. It becomes unreliable when an application handles thousands of varied requests, uses tools, or must satisfy rules defined by several teams.

Evaluation-driven prompt learning turns those repeated edits into an evidence-based workflow. The system collects representative outputs, evaluates them, explains the failures, and uses those explanations to propose a better prompt. The proposed prompt is tested before a person decides whether it should be deployed.

The model does not retrain itself. Its weights remain unchanged. What changes is the readable text that instructs the model.

A Beginner’s Mental Model

Imagine an AI application as a new employee following an operating manual.

• The system prompt is the operating manual.
• An application run is a piece of completed work.
• An evaluator checks whether that work meets defined requirements.
• Feedback explains what was correct or incorrect.
• A meta-prompt asks another model to revise the operating manual from that evidence.
• The candidate prompt is the proposed new version of the manual.
• A held-out test set is an exam the revised manual has not already seen.

The valuable part is not simply asking an LLM to rewrite a prompt. The valuable part is the controlled loop around that rewrite.

flowchart TD
    A["Current system prompt"] --> B["Run application on representative cases"]
    B --> C["Evaluate outputs and traces"]
    C --> D["Collect labels, explanations, and human annotations"]
    D --> E["Meta-prompt proposes a candidate prompt"]
    E --> F["Test candidate on held-out cases"]
    F --> G{"Meets quality and safety gates?"}
    G -->|No| H["Reject or revise candidate"]
    H --> D
    G -->|Yes| I["Human approval and versioned deployment"]
    I --> J["Monitor production behavior"]
    J --> B

This resembles learning because behavior changes from feedback. It is still prompt optimization, not model training.

The Term “Prompt Learning” Is Ambiguous

In the Arize project discussed in the source talk, Prompt Learning means using natural-language feedback to improve human-readable prompt instructions.

In machine-learning research, prompt tuning or soft prompt learning often means something different: training continuous embedding vectors that are added to a model’s input. Those learned vectors are not normal sentences and are usually optimized through backpropagation.

This page concerns hard-prompt optimization:

Question	Evaluation-driven prompt learning	Soft-prompt tuning
What changes?	Readable instructions	Learned embedding vectors
Are model weights changed?	No	Usually no, but prompt parameters are trained
Can a person inspect the result?	Yes	Not as normal language
Can it work through a hosted model API?	Yes	Only if the platform supports training soft prompts
Main signal	Evaluations, critiques, and annotations	Training loss and gradients

Naming the distinction prevents two unrelated techniques from being treated as interchangeable.

Why A Score Is Not Enough

Suppose a support agent receives this evaluation:

correctness: 0

The score says that something failed. It does not say what should change.

Compare it with this critique:

The answer promised a refund before checking whether the order was eligible.
The agent should retrieve the refund policy and order status before offering
a resolution. It should escalate when the eligibility result is ambiguous.

That explanation contains several possible instructions:

• check policy before promising an outcome
• retrieve the relevant account state
• distinguish an ineligible request from an uncertain one
• escalate uncertainty instead of guessing

Scores and explanations serve different purposes:

Signal	Best use
Numeric score or label	Compare candidates and track aggregate performance
Natural-language critique	Explain the failure and propose an instruction change
Human annotation	Add domain knowledge or policy that an automated evaluator may not know
Deterministic test result	Establish objective correctness where code can check it

A practical optimizer often needs both: an explanation to generate a candidate and a score to decide whether the candidate is actually better.

Start With A Real Definition Of Success

An evaluator cannot compensate for an undefined product requirement.

Before collecting failures, ask the people responsible for the application what success means. Different stakeholders may care about different dimensions:

• users care whether the answer solves their problem
• domain experts care about factual and policy correctness
• security teams care about data access and unsafe actions
• operations teams care about latency, cost, and escalation behavior
• product owners care about task completion and business outcomes

Turn those requirements into separate checks rather than one vague “quality” score.

For a tool-using support agent, the evaluation suite might include:

1. Was the correct tool selected?
2. Were its arguments correct?
3. Did the tools run in a valid order?
4. Did the final answer use the returned evidence?
5. Did the agent avoid unsupported commitments?
6. Did it escalate when policy required escalation?
7. Did it expose any restricted information?

This decomposition also makes failures diagnosable. A wrong final answer and a wrong tool argument require different fixes.

Build A Representative Learning Dataset

Prompt optimization is only as useful as the cases it learns from.

Collect examples from:

• real production traces after removing or protecting sensitive data
• known failures reported by users or reviewers
• successful cases that the new prompt must preserve
• important edge cases
• adversarial and misuse cases
• rare but high-impact scenarios
• different languages, customer groups, and workflow variants where relevant

Do not create a dataset containing only failures. Without successful examples, an optimizer may add rules that fix one problem while damaging behavior that already worked.

Each record should preserve enough evidence to reconstruct the decision:

Field	Purpose
Input	What the application received
Relevant context	Retrieved records, documents, or state
Trace	Tool calls and intermediate actions when available
Output	What the application produced
Expected behavior	Ground truth or reviewed target
Evaluation label	Pass, fail, category, or score
Explanation	Why the result received that evaluation
Human annotation	Domain-specific correction or policy guidance

Keep Optimization And Final Testing Separate

Using the same examples to create and approve a prompt is like giving a student the answers before the exam.

Split the data by purpose:

flowchart LR
    A["Representative reviewed dataset"] --> B["Optimization set"]
    A --> C["Validation set"]
    A --> D["Untouched test set"]
    B --> E["Generate candidate instructions"]
    C --> F["Choose settings and compare candidates"]
    D --> G["Final quality and safety decision"]
    E --> F
    F --> G

• The optimization set supplies failures and feedback used to revise instructions.
• The validation set helps compare candidates and tune the process.
• The test set is used only for final evaluation.

Split by the unit that can leak information. If the same customer, repository, document, or conversation pattern appears in every split, the test may be less independent than it looks.

Track important categories separately. A higher average score is not acceptable if performance falls on safety-critical or high-value cases.

Design Evaluators Before Designing The Optimizer

The optimizer follows the signal it receives. A weak evaluator can produce a confidently worse prompt.

Use the simplest reliable evaluator for each requirement.

Deterministic checks

Use code when correctness can be computed:

• schema and type validation
• exact identifiers or required fields
• compilation and unit tests
• numerical calculations
• tool-call argument constraints
• forbidden actions or strings
• latency and cost thresholds

These checks are reproducible and difficult for an optimizer to reinterpret.

Reference-based checks

Compare against reviewed answers, expected tool calls, or known outcomes when several forms of output may be valid but the core result is known.

LLM judges

Use an LLM judge for criteria that require semantic interpretation, such as completeness, tone, faithfulness to evidence, or adherence to a nuanced policy.

A useful judge should return structured evidence, not only a verdict:

{
  "label": "fail",
  "criterion": "policy_grounding",
  "explanation": "The response promised a refund without checking eligibility.",
  "evidence": "The trace contains no refund-policy lookup.",
  "confidence": 0.93
}

The exact confidence number should not be treated as calibrated probability unless it has been tested as such. It is mainly a signal for prioritizing review.

Human review

Humans are necessary when requirements are subjective, costly, new, or policy-sensitive. They also provide the reference labels used to evaluate automated judges.

Evaluate The Evaluator

An LLM judge is another AI component. It can be inconsistent, biased toward particular writing styles, influenced by the candidate answer, or wrong about the domain.

Create a reviewed evaluator test set and measure:

• agreement with domain experts
• false-positive and false-negative rates
• performance by important category
• consistency across repeated runs
• sensitivity to irrelevant formatting or answer order
• response to ambiguous cases
• resistance to instructions embedded inside the content being judged

Candidate outputs and retrieved documents are untrusted data. Delimit them clearly and tell the judge to evaluate their content rather than follow instructions inside them. Use deterministic checks for security boundaries wherever possible.

If evaluator behavior changes, version it. A score from evaluator version 3 may not be comparable with a score from version 4.

The Agent And Evaluator Need Separate Improvement Loops

A production system may eventually improve both the application prompt and the evaluator prompt. Those loops must not collapse into one unreviewed cycle.

flowchart LR
    subgraph AgentLoop["Application improvement loop"]
        A1["Application traces"] --> A2["Reviewed application failures"]
        A2 --> A3["Candidate system prompt"]
        A3 --> A4["Held-out application tests"]
    end

    subgraph EvalLoop["Evaluator improvement loop"]
        E1["Judge decisions"] --> E2["Human-reviewed judge errors"]
        E2 --> E3["Candidate evaluator prompt"]
        E3 --> E4["Held-out evaluator tests"]
    end

    A4 --> G["Human release gate"]
    E4 --> G
    G --> P["Versioned production release"]

The application loop asks, “Did the agent behave correctly?”

The evaluator loop asks, “Did the judge evaluate that behavior correctly?”

If an agent and its judge change together using the same examples, they can learn a shared shortcut. Independent reviewed data and release gates reduce that risk.

Not Every Failure Is A Prompt Failure

Prompt optimization is attractive because it is cheaper than changing an architecture or training a model. That does not make every problem a wording problem.

Observed failure	Likely correction
The model ignores a clear, stable rule	Improve or reposition the instruction
Required information never enters context	Fix retrieval or context assembly
A tool description is ambiguous	Improve the tool contract or schema
The tool returns incorrect data	Fix the tool or upstream system
The model cannot reliably perform the task	Try a stronger model, decomposition, or training
The application executes unsafe actions	Add authorization and runtime controls, not only prompt text
The evaluator marks correct work as wrong	Fix the evaluator
Business requirements conflict	Resolve the policy conflict with stakeholders

A prompt can guide behavior. It cannot replace missing data, broken software, authorization, or deterministic enforcement.

Manage Instructions As A Controlled Artifact

Repeatedly appending new rules creates long, contradictory prompts. Treat system instructions like maintained configuration.

A useful structure separates stable and editable content:

SYSTEM PROMPT

[Protected identity and purpose]
[Protected safety and permission boundaries]
[Protected tool and output contracts]

<managed_instructions>
Rules that the optimization process may add, merge, rewrite, or retire.
</managed_instructions>

[Protected runtime context placeholders]

Restricting edits to a managed block reduces accidental damage to safety constraints, template variables, and output contracts.

For each generated instruction, preserve metadata outside the runtime prompt:

Metadata	Why it matters
Source examples	Shows which evidence caused the change
Target failure class	Explains the rule’s intended purpose
Scope	Prevents a local rule from becoming universal
Owner	Identifies who can approve or remove it
Added version	Supports auditing and rollback
Review or expiry date	Prevents old assumptions from becoming permanent

An optimizer should be allowed to propose several operations:

• add a missing instruction
• merge duplicate instructions
• rewrite an ambiguous instruction
• resolve a documented conflict
• narrow an instruction’s scope
• retire an obsolete instruction
• reject feedback that should not become a rule

The goal is a small, coherent policy, not an ever-growing list of patches. This is especially important for capable long-running agents, where excessive scaffolding can constrain useful behavior. See Prompting Long-Horizon Coding Agents.

Compare The Main Improvement Methods

These methods overlap, but they do not change the same artifact or use the same search process.

Method	What changes	Main feedback	Typical use
Manual prompt engineering	Human-readable prompt	Human inspection	Early exploration and small tasks
Meta-prompting	Human-readable prompt	Instructions, examples, or critiques supplied to another LLM	Generate one or more candidate prompts
Arize Prompt Learning	Usually a readable prompt or managed rules section	Evaluator explanations and human annotations	Continuous, feedback-driven instruction maintenance
DSPy GEPA	Instructions in a DSPy program	Score plus reflective feedback and candidate evaluation	Search across instruction candidates within DSPy
Soft-prompt tuning	Trainable embedding vectors	Loss and gradients	Parameter-efficient adaptation with training access
Fine-tuning	Model weights	Training examples and an optimization objective	Persistent behavioral or domain adaptation after prompt-only methods plateau

Meta-prompting is a mechanism inside several workflows. It is not limited to scalar feedback and does not by itself provide dataset management, held-out validation, deployment, or monitoring.

For the detailed DSPy optimizer workflow, including GEPA, MIPROv2, metric gaming, and saving compiled programs, see DSPy Evaluation and Optimization.

A Safe Production Workflow

Do not allow production feedback to rewrite the live system prompt directly.

Use a release pipeline:

flowchart TD
    A["Versioned production prompt"] --> B["Collect reviewed production evidence"]
    B --> C["Generate candidate prompt"]
    C --> D["Review prompt diff and rule provenance"]
    D --> E["Offline validation and safety tests"]
    E --> F{"Candidate approved?"}
    F -->|No| G["Archive result and diagnosis"]
    F -->|Yes| H["Canary or limited rollout"]
    H --> I{"Production checks pass?"}
    I -->|No| J["Rollback"]
    I -->|Yes| K["Promote version"]
    J --> A
    K --> A

The release record should include:

• original and candidate prompt versions
• exact optimizer and evaluator versions
• data snapshot or immutable dataset identifier
• prompt diff and instruction provenance
• test results by important category
• model and inference settings
• cost and latency changes
• reviewer and approval decision
• rollback target

This makes the improvement reproducible instead of mysterious.

Common Failure Modes

Overfitting to visible failures

The new prompt solves the optimization examples but performs worse on new inputs.

Controls: representative splits, untouched tests, category-level metrics, and preservation tests for existing successes.

Evaluator gaming

The optimized prompt learns behavior that pleases the judge without satisfying the user.

Controls: deterministic checks, independent judges, human review, adversarial cases, and business-outcome measurements.

Feedback poisoning

Malicious or incorrect feedback becomes a trusted system instruction.

Controls: treat feedback as untrusted data, require provenance, restrict who can annotate, review proposed rules, and protect safety sections from automated edits.

Prompt bloat

Every failure adds another rule until the prompt becomes expensive, contradictory, or hard for the model to follow.

Controls: merge rules, expire stale guidance, measure token growth, and test whether removing instructions changes performance.

Model drift

A prompt optimized for one model version behaves differently after a provider or model change.

Controls: bind evaluations to model versions and rerun the full test suite before migration.

Privacy leakage

Raw production traces or feedback contain personal, confidential, or regulated data.

Controls: minimize collected fields, redact before optimization, limit retention, and restrict access to prompts and datasets.

Cost without durable gain

Optimization loops consume many model calls but produce only marginal or unstable improvement.

Controls: set budgets and stopping criteria, compare against a manual baseline, and stop when held-out performance plateaus.

A Practical Arize Prompt Learning Example

The source talk uses the Arize Prompt Learning project as a concrete implementation. Its current architecture has three conceptual roles:

1. the agent produces outputs with the current prompt
2. evaluators or humans produce natural-language feedback
3. a meta-prompt uses that feedback to propose revised instructions

The repository expects data shaped roughly like this:

input,output,correctness,explanation
"Where is my order?","It will arrive tomorrow.","fail","The answer invented a date without retrieving shipment status."
"Can I return this item?","Let me check the return policy.","pass","The answer correctly avoids promising eligibility before checking policy."

The current command-line interface can optimize a prompt from one or more feedback columns:

prompt-learn optimize \
  --prompt "Answer the support request: {input}" \
  --dataset reviewed-runs.csv \
  --output-column output \
  --feedback-columns correctness,explanation \
  --save candidate-prompt.txt

This command creates a candidate. It does not replace the validation and release stages described above.

When this page was checked in July 2026, the repository described itself as a beta 0.1.0 Python package requiring Python 3.12 or newer. It supported OpenAI and Google model providers and used the Elastic License 2.0, which restricts offering the software as a hosted or managed service. These implementation details can change, so verify the repository and documentation before adopting it.

Interpreting The Reported Benchmarks

The talk reports improvements for coding agents and Big-Bench Hard tasks, and compares its Prompt Learning experiments with GEPA and MIPROv2.

Those results demonstrate that feedback-driven prompt updates can improve some evaluated workloads. They do not establish that:

• the method improves every task
• the same gain transfers to another model or agent harness
• Prompt Learning universally outperforms GEPA
• prompt changes replace architectural or tool improvements
• more optimization loops always improve performance

The associated Arize research article states that prompt-learning training results can fall after an update. It also notes that some Big-Bench Hard tasks with unresolved issues were excluded from its published result. Treat the charts as reported experiments with particular datasets, models, evaluators, and budgets.

Reproduce the comparison on your own held-out workload before making a product decision.

When This Pattern Is Useful

Evaluation-driven prompt learning is a good fit when:

• the task repeats often enough to collect representative cases
• desired behavior can be evaluated with reasonable reliability
• failures reveal reusable instructions
• prompts are versioned and testable
• model weights cannot or should not be changed
• domain experts can explain why important failures occurred

It is a poor fit when:

• requirements are still undefined
• there is no trustworthy evaluation signal
• every case needs unrelated one-off knowledge
• the failure comes from missing context, broken tools, or permissions
• the prompt cannot be tested before deployment
• automatic prompt changes would violate governance requirements

Implementation Checklist

Before optimization:

• Define success by stakeholder and failure category.
• Build evaluators for separate dimensions.
• Validate LLM judges against reviewed examples.
• Collect both successful and failed cases.
• Protect sensitive data in traces and annotations.
• Separate optimization, validation, and test data.
• Mark the prompt section an optimizer may edit.
• Establish a baseline with the current prompt.

Before deployment:

• Inspect the prompt diff and rule provenance.
• Check for duplicated or contradictory instructions.
• Verify template variables and output contracts.
• Run deterministic, semantic, safety, and regression checks.
• Compare important categories, not only the average score.
• Review cost, latency, and prompt length.
• Record the candidate, model, evaluator, and dataset versions.
• Obtain human approval.
• Prepare a canary rollout and rollback target.

After deployment:

• Monitor the same metrics used for approval.
• Sample real outputs for human review.
• Track evaluator disagreement and low-confidence cases.
• Add newly reviewed failures to a future dataset version.
• Retire rules whose assumptions are no longer valid.

Sources And Further Reading

• Source talk: Build a Prompt Learning Loop
• Arize Prompt Learning repository
• Arize Prompt Learning SDK documentation
• Arize Prompt Learning research article
• Arize evaluation fundamentals
• Phoenix tutorial: Optimize Prompts Automatically
• The Power of Scale for Parameter-Efficient Prompt Tuning
• DSPy Evaluation and Optimization