> For the complete documentation index, see [llms.txt](https://docs.patagon.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.patagon.ai/en/agent-optimization/insights.md).

# How to use Agent Insights

Agent Insights analyzes your agent's conversations automatically and proposes specific changes to improve performance. Instead of reviewing conversations manually to find patterns, Insights does it for you and tells you exactly what to change and why.

Access it from the sidebar under Agent > Insights.

## How Insights works

After analyzing a batch of conversations, Insights generates a proposed new version of your agent with a specific behavior change. Each insight shows:

* What to change: the exact rule or behavior the agent should adopt
* Why: the pattern detected across conversations that explains the problem
* Reasoning: the specific conversations and metrics that support the recommendation

## How to apply an insight

1. Open Agent > Insights.
2. Review the proposed change: read the Why and Reasoning sections carefully before deciding.
3. If the change makes sense for your business, click Apply Changes. Patagon AI creates a new draft version with the proposed change applied.
4. Test the new version in Agent > Playground before activating it.
5. Go to Agent > General > Versions and activate the draft when you're confident it performs better.

If the proposed change doesn't fit your context, click Disregard to dismiss it without applying.

{% hint style="warning" %}
Always test an insight in the Playground before activating it. Insights are data-driven suggestions based on patterns across many conversations, but your specific business context may make some suggestions irrelevant.
{% endhint %}

## How to read the reasoning

Each insight includes the number of conversations analyzed, the pattern detected and how often it occurs, and the specific behavior changes proposed. A good insight has a large sample size (100+ conversations), a clear pattern with a specific percentage, and a proposed change that's concrete and testable.

## Insights and versions

Every time you apply an insight, Patagon AI creates a new draft version automatically. You can see it in Agent > General > Versions. If an applied insight doesn't improve performance, roll back to the previous version instantly.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.patagon.ai/en/agent-optimization/insights.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.