> ## Documentation Index
> Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details.
# Improve Your Agent
> Make your agent faster, cheaper and shorter without making it worse, with a scenario test suite as the quality gate and one hypothesis at a time.
## What the improvement loop is
The agent improvement loop is how you change your agent and prove that the change did not make it worse. Change one small thing in the harness, the prompt, a tool description or the model, and something that worked before can break five turns down the line. So you need a loop to keep improving the agent, in cost, in latency or in what it can handle, without dropping the quality.
The loop starts with a definition of quality that you can run. That definition is a test suite of [scenarios](/docs/agent-testing/scenarios): simulated conversations with the criteria the agent has to meet, all of which pass on the agent you trust today. The judge in each scenario reads the whole conversation together with the agent's traces, passes or fails every criterion you wrote, and explains the verdict, which is what makes a suite a better gate than a golden answer.
Everything else you care about, turns, tokens, cost and latency, is a metric you push down while that suite keeps passing. The same run that gives you the verdicts also gives you those numbers, so you see in one place whether the change paid off and whether it cost you anything.
## The loop
| Step | What you do | Where |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| 1. Define quality | Write five to ten scenarios from real conversations, with the criteria the agent must meet. Run them on the model and prompt you trust. Every scenario passes: this is the baseline. | [Scenarios](/docs/agent-testing/scenarios), [Test suites](/docs/agent-testing/test-suites) |
| 2. Measure | Read the pass rate, the cost and the reply latency of the baseline run. | [Results](/docs/agent-testing/results) |
| 3. Change one thing | Ask Langy or your coding agent to read the run and come back with a hypothesis and one change: a smaller model, a rewritten tool description, a tool that validates its input, a shorter prompt, a lower iteration cap. One change per run, so the result has one cause. | [Reduce turns](/docs/improve-your-agent/reduce-turns) |
| 4. Compare | Run the same suite against the changed agent, next to the baseline. Keep the change when the pass rate holds and the metric moved. | [Compare agents](/docs/agent-testing/compare-agents) |
Repeat from step 3, and put the suite in CI so a later change cannot undo the gain: see [Run from CI](/docs/agent-testing/run-from-ci).
## Where the changes come from
The hypotheses come out of the last run. When a criterion failed, the judge's reasoning quotes the turn where it happened and the trace of that turn shows what the agent saw and did; when a scenario passed but took ten turns, the conversation usually shows the same tool called twice in a row. There are two ways to turn that into a change:
* **Guided.** Langy, or your coding agent with the `langwatch` CLI, reads the results and the traces and comes back with a hypothesis and the change for it, and you run the suite on that change to prove it made the agent better. See [Prompt optimization with Langy](/docs/langy/prompt-optimization) for the prompt case.
* **Algorithmic.** A DSPy optimizer rewrites the instructions and the tool descriptions and scores every candidate by running the suite, and GEPA also feeds the judge's reasoning back in as the feedback for the next candidate. See [Optimize with DSPy](/docs/improve-your-agent/optimize-with-dspy).
Use the guided loop when the change is in code, in a tool or in the harness, since no optimizer can touch those, and when you want to review each change. Use an optimizer when the change is in text and you have the budget to run the suite fifty or so times.
## Guides
Find out why your agent takes ten turns for a basic task, get the cause changed, and prove the suite still passes.
Catch a tool your agent retries, get the tool contract fixed, and assert on the tool calls in the criteria.
Run the same suite on two models side by side and keep the cheaper one where the pass rate holds.
Let an optimizer rewrite the instructions and the tool descriptions, scored by your scenarios.
What each algorithm changes, what it needs, what it costs and when to use it.
The same loop on a single prompt, on the experiments workbench, with a dataset and an evaluator.
**Also check:** [Agent testing](/docs/agent-testing/overview) (how a scenario runs), [Connect your agent](/docs/agent-testing/connect-your-agent) (one decorator, so the suite runs against your real code), [Skills directory](/docs/skills/directory) (the `agent-improve` and `scenarios` skills for your coding agent).