# Manage agents

> Change an egress agent's targets and protection, disable it, rotate its token or delete it, from the dashboard, the API or MCP.

An agent is one app or bot that calls model providers through the hosted gateway. It has a name, a description, the targets it may call (1 to 32), two protections (**Block prompt injection**, `enforce_injection`, and **Block data leaks**, `block_dlp`, both on by default), a `disabled` switch and its own token. Every change needs an organization-wide `admin`. To create one, see [get started](https://developers.openwaf.dev/egress/cloud/get-started/#create-an-agent).

In the API, agents are named by id (`…/egress/agents/{id}`, where `…` is `https://dash.openwaf.dev/v1/orgs/{org}`); in MCP, by name or id. Changes take an optional `X-Change-Reason` header (MCP: the required `reason`) that is kept in the audit log; they are not versioned configuration, so there is no `dry_run` or `If-Match`.

## Change targets and protection

Only the fields you send change; `allowed_targets` is replaced as a whole. The name cannot change, because it is part of the agent's gateway URLs: create a new agent instead.

**Dashboard**

In **AI egress → Agents**, choose **Edit** on the agent's row, change its description, targets or protection and save.
**API**

```sh
curl -sS -X PATCH "https://dash.openwaf.dev/v1/orgs/$ORG/egress/agents/$AGENT_ID" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" -H "Content-Type: application/json" \
  -H "X-Change-Reason: support bot may also call OpenAI" \
  -d '{"allowed_targets": ["openrouter", "openai"]}'
```
**MCP**

`egress_update_agent` with `agent`, the fields to change (`description`, `allowed_targets`, `enforce_injection`, `block_dlp`, `disabled`) and a `reason`; `confirm=false` shows the change, `confirm=true` applies it.


Turn a protection off only for an agent that must process text that looks like an attack, such as security reports: the detectors cannot be switched off one by one.

## Disable an agent

A disabled agent's token is refused (`401`) until you enable it again; nothing else changes. Set **Disabled** in the agent's edit dialog, send `{"disabled": true}` with `PATCH`, or call `egress_update_agent` with `disabled: true`.

## Rotate the token

Rotation issues a new token, shown once, and the current one stops working within seconds. Update every app that uses it first.

**Dashboard**

In **AI egress → Agents**, choose **Rotate token** on the agent's row and confirm. Copy the new token from the dialog.
**API**

```sh
curl -sS -X POST "https://dash.openwaf.dev/v1/orgs/$ORG/egress/agents/$AGENT_ID/rotate-token" \
  -H "Authorization: Bearer $OPENWAF_TOKEN" -H "X-Change-Reason: token leaked in a CI log"
```

The answer is `{"agent": …, "token": "OWE_TOKEN_…"}`, like the creation.
**MCP**

`egress_rotate_token` with `agent` and `reason`, then again with `confirm=true`. The new token is in that answer only.


If a token leaks, rotate it or disable the agent: a token only works against the gateway, for the agent's allowed targets and with its protections, but it can spend the provider key until then.

## Delete an agent

Deleting an agent makes its token stop working at once; its blocked requests stay in the log. It cannot be undone. In the dashboard choose **Delete** on the agent's row; in the API send `DELETE …/egress/agents/{id}`; over MCP call `egress_delete_agent`.

Deleting agents, targets and keys keeps working even if AI egress is turned off for the organization, so you can always remove what you set up.

## Audit log

Each change leaves an entry in the organization's audit log: `egress.agent.create`, `egress.agent.update`, `egress.agent.rotate_token` and `egress.agent.delete`, with the actor, the reason and, for changes made over MCP, `"channel": "mcp"`. The token never appears; only its prefix (`OWE_TOKEN_` and 6 characters) does.