> For the complete documentation index, see [llms.txt](https://docs.finout.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.finout.io/user-guide/optimize/agents-beta/managing-agents-beta.md).

# Managing Agents \[Beta]

## Agents List

The **Agents** page is where you view and act on every Detection Agent in your account.

### View the Agents page

{% hint style="info" %}

* Viewing agents requires the a permission for agents view. Go to [permissions list](https://docs.finout.io/settings/role-based-access-control-rbac/managing-roles/permissions-list) to see more details.
  {% endhint %}

**Navigate** to **Agents** in the main navigation.

The Agents page loads with a list of all agents in your account.

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2FNyCgRXLfAzcQATyhY7XL%2Fimage.png?alt=media&amp;token=ceaf6251-5763-4f3d-bd73-56ed78d39cd3" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
If you don't have any agents yet, the Agents page shows an empty state instead of a list.
{% endhint %}

### Act on an agent

Click the action menu (···) on any agent row to:

* **Edit** — open the configuration form pre-filled with the agent's current settings
* **Duplicate** — duplicate an agent
* **Move to a Folder** — organize your agents in folders
* **View Findings** — opens a list of all findings this agent has found
* **Deactivate or Activate and Agent** — click to pause or resume an agent without losing its configuration.
  * **Activate** — the agent runs daily.
  * **Deactivate** — the agent keeps its full configuration and historical findings, but skips runs until you re-activate it.

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2FNCvGTx4cL9lpmrO1W852%2Fimage.png?alt=media&amp;token=e10c2be0-2090-411a-9c41-7db4e8db2126" alt=""><figcaption></figcaption></figure>

## Create or Edit Agents

### Create a new agent

{% hint style="info" %}

* The AI Opt-In toggle is turned on for your account.&#x20;
* You have the **Create Agents** permission and **Edit Agents** permission to edit an existing agent.
  {% endhint %}

1. From the **Agents** page, **click Create agent**.

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2FpwzLdU1cb8INm03WWsa8%2Fimage.png?alt=media&amp;token=9d1aa0e9-a26d-441e-afe8-c7dd1c134898" alt=""><figcaption></figcaption></figure>

2. In the full-page creation form, **enter** a name for the agent.
3. **Select** a provider.
4. **Select** a service. Only services available for your chosen provider appear.
5. **Select** a use case. Only use cases valid for the selected service appear. See Agents Overview for the full matrix of which services, providers are use cases are available.

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2FgqxbymExgg9Y1AHYowr4%2Fimage.png?alt=media&amp;token=70abc385-7f8b-427c-8070-c702b400c2d5" alt=""><figcaption></figcaption></figure>

#### Add cost filters

Cost filters narrow which resources the agent evaluates — for example, limiting the agent to a specific team or environment.

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2FLt8mnjbSzO9cc62jiVyh%2Fimage.png?alt=media&amp;token=8c3eeac1-2487-4211-81ec-49091b5460ea" alt=""><figcaption></figcaption></figure>

#### Estimate scanned resources

Get an estimate of how many resources the current configuration would scan.

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2FVrX4SFtSYnVQ3xHzgtD3%2Fimage.png?alt=media&amp;token=8821ae24-a77e-46e3-8873-f9091a8e340f" alt=""><figcaption></figcaption></figure>

#### Set the look-back period

Choose how many days of data the agent evaluates: **7, 14, or 30 days**.&#x20;

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2F1F7KUkEDqhqyajGSEkKr%2Fimage.png?alt=media&amp;token=c0d67866-962e-40f5-bd5e-2b8565fa5cb1" alt=""><figcaption></figcaption></figure>

#### Configure metrics

Add one or more metric metrics the agent should evaluate. Only metrics relevant to the selected use case and service are available. For each metrics, configure the metric name, operator, threshold, and aggregations.

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2Fwr24n59NWoehgqcSYva3%2Fimage.png?alt=media&amp;token=17f5e6ce-9133-4699-9ab7-b93fe566d0da" alt=""><figcaption></figcaption></figure>

#### Set metric headroom

Available for rightsizing use cases only. Headroom reserves extra capacity on top of a candidate's expected utilization, to absorb growth or spikes. If a candidate's projected utilization plus headroom would exceed 100%, that candidate isn't recommended.

{% hint style="info" %}
For example: a rightsizing threshold of 70% qualifies an instance running at 60% CPU for downsizing. A smaller candidate instance is found with a projected utilization of 92%. With a 20% headroom setting, 92% + 20% = 112% — over 100%, so this candidate is rejected even though it looks efficient on paper.
{% endhint %}

<figure><img src="https://3858159242-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWqjB2puKXPDR7L86FX2e%2Fuploads%2FCs5S9GrvncqAiqTbc1Qm%2Fimage.png?alt=media&amp;token=b46300cc-c93b-4a28-bcfa-abe5fd744431" alt=""><figcaption></figcaption></figure>

#### Set wait period

The wait period sets how many days to hold a resource after its configuration changes, before it's eligible for a new recommendation. It's empty by default — no wait period applies unless you set one.

{% hint style="info" %}
If you do set a wait period, it must be **greater than or equal to** the agent's look-back period. A shorter wait period would bring the resource back into evaluation while its look-back window still contains data from before the change — the exact problem the wait period exists to prevent. A longer wait period is allowed, for teams whose change-management process runs longer than the data requirement alone.
{% endhint %}

**What starts the clock:** the day Finout detects that the resource's actual configuration has changed — for example, an EC2 instance type change. This is independent of whether the change came from a Finout recommendation; the trigger is the change itself, because the reason to wait is data sufficiency, not attribution.

**What counts as a configuration change** depends on the service:

| Service  | Configuration key                 |
| -------- | --------------------------------- |
| EC2      | Instance type                     |
| RDS      | Instance type + deployment option |
| Azure VM | VM size                           |

While a resource is within its wait period, the agent won't issue a new recommendation for it, even if it would otherwise qualify — regardless of whether someone has marked the existing finding **In progress**. Wait period and finding status track two different things: wait period is about whether there's enough new data to trust; status is about what a person has done.

#### Save the agent

**Click Save**. The agent is created and appears in your Agents list with status **Active**.

{% hint style="info" %}
Agents run once a day. A newly created agent won't have any findings yet — its Findings tab shows an empty state with the expected next run time until the first scheduled run completes.
{% endhint %}

### Edit an agent

1. From the **Agents** page, click the action menu (···) on an agent row and select **Edit**.
2. The configuration form opens pre-filled with the agent's current settings.
3. **Modify** the fields you want to change, then **click Save**.

{% hint style="info" %}
Your changes take effect on the agent's next scheduled run — not retroactively on findings it already surfaced.
{% endhint %}

### Activate or deactivate an agent

Use the menu of each agent in the Agents list to pause or resume it and agent. See Managing Agents List — a deactivated agent keeps its configuration and finding history but skips scheduled runs until re-activated.

### FAQs

**Can I change an agent's provider or service after creating it?** No. You can't change the provider, service, or use case after an agent is created — create a new agent instead.&#x20;

**Does editing an agent affect findings it already found?** Not immediately — your changes apply starting with the agent's next run, not retroactively. If a resource is still identified as a finding on that next run, its finding gets updated to reflect the new configuration.

**What happens if my headroom setting rejects every candidate?** The agent won't surface a rightsizing recommendation for that resource until a candidate satisfies both the utilization threshold and the headroom buffer.

**What happens to an agent's finding history when I pause it?** Nothing — pausing only stops future runs. All existing findings and the agent's configuration remain exactly as they were.

**Who can see and act on the Agents page?** Access is controlled by four permissions — View, Create, and Edit agents — which admins have by default.&#x20;

**Why is my agent inactive and not running?** Most likely, one of its cost filters uses a virtual tag that had reallocation added to it after the agent was created. Reallocated virtual tags aren't supported in agent cost filters, so the agent is automatically disabled until you update the filter.

**Can I limit who can see or edit a specific agent in my account?** No. ACL for agents will come in a future release.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.finout.io/user-guide/optimize/agents-beta/managing-agents-beta.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
