AI Agents

The AI Agents module registers the AI agents that consume AI Gateway. Each AI Agent has a unique identifier, a free-form description, a list of Scopes that defines what the agent can access, and a pair of Client ID / Client Secret credentials managed by the gateway. Agents use these credentials to get access tokens client_credentials and call the Routes and MCP Servers whose scopes match the agent's scopes.

NOTE

Before creating your AI Agent, register at least one Scope. The form requires at least one scope to be selected and does not let you save with an empty list.

Quick links

Learn how to:

• Filter and list AI Agents
• Create an AI Agent
• View an AI Agent
• Edit an AI Agent
• Manage credentials
• Delete an AI Agent
• Review the Audit Log record
• Review the form fields
• Review permissions

Listing

The AI Agents page lists registered agents with pagination. You can filter by:

• Name (optional): text search by agent name.
• Description (optional): text search by description.

Use Search to apply the filter and Clear to reset it.

Columns shown in the table:

• Name: agent name.
• Description: registered free-form description.
• Scopes: list of associated scopes, resolved to the name registered in Scopes. Shows No scopes assigned. when empty.
• Created At: creation date and time in your time zone.
• Actions: View and Delete icons for each row, each one shown according to the user's permission — see Permissions. The whole column disappears when neither icon is available.

Create AI Agent

TIP

The Credentials section does not appear in the creation form. Credentials are issued when the agent is created and managed from its details screen (see below).

View AI Agent

In the Actions column of the row you want, click the View icon. This opens the read-only Overview screen, on the General Info tab. The AI Agent configuration block holds the following fields:

• Name
• Description
• Scopes
• Created At

No field is editable on this screen. Right below it, the Credentials section appears according to the user's permission — see Manage credentials.

Edit AI Agent

Editing lives inside the details screen. Open the agent through the View icon (see View AI Agent) and, on the Overview screen, click the Edit button. The Update AI Agent form opens in a drawer with the current data and shows, below the editable fields, the same Credentials section described in Manage credentials. Change the required fields and click Save.

EDITING REQUIRES VIEWING

The Edit button only exists inside the agent's Overview screen. Because of that, a user holding Create and Update AI Agents but not View AI Agent has no path to edit an already registered agent. This is expected platform behavior, not a bug.

Manage credentials

The Credentials section appears on the Overview screen and in the agent's edit form, gated by the ai-gateway.ai-agents.credentials.read and ai-gateway.ai-agents.credentials.update permissions — see Permissions. Without either one, the whole section is not shown.

With credentials.read:

• Status: Active or Status: Revoked: current state of the agent credentials.
• Client ID: masked by default. Use the eye icon to reveal it and the copy icon to copy it.
• Client Secret: follows the same behavior as Client ID.

When the status is Revoked, the Client ID and Client Secret fields are empty, the eye and copy icons are disabled, and the Revoke button is disabled — use Generate client secret to issue a new Client Secret (the Client ID does not change).

Without credentials.read: the Client ID and Client Secret fields do not appear — the credential is never even fetched — and a warning tells you that the ai-gateway.ai-agents.credentials.read permission is required to view this agent's credentials. Because the status also depends on that same read, it stays unknown to anyone who doesn't have it.

The button that rotates the secret is gated by credentials.update, with a label that depends on what is known about the status:

Clicking the button opens the "Generate a new client secret?" confirmation, warning that the current secret, if any, stops working immediately. Upon confirming:

• With credentials.read: the new Client Secret appears revealed on screen, with the toast "Client secret regenerated. Copy it before leaving this screen.".
• Without credentials.read: the toast is "Client secret regenerated. You do not have permission to see the new value.", and the new value is not shown on any screen.

The API no longer returns the value when the client secret is generated or rotated; reading it requires ai-gateway.ai-agents.credentials.read.

Revoke, gated only by credentials.update, revokes the current credential. Without credentials.read (status unknown), the button stays always available to anyone holding that permission. With credentials.read, the button is only available when the status is Active — in Revoked it is disabled, since there is no active credential to revoke (disabling by status is not a permission gate — see Permissions). Revoke is applied on click, with no confirmation dialog.

ROTATION AND REVOCATION ARE IMMEDIATE

Regenerate and Revoke invalidate the previous Client Secret in the same operation. Agents that were using the old secret start failing when they request a new token, until you update them. Coordinate the operation with the production agent update. Generate does not apply here: it only exists when the status is already Revoked, meaning there is no active secret in use to invalidate.

The secret and the token are different things. After Regenerate or Revoke, the gateway issues no new access tokens with the previous credential, but an access token that was already issued stays valid until it expires.

Delete AI Agent

In the Actions column of the row you want, click the Delete icon. Confirm the operation in the "Do you want to delete AI agent [agentId]?" dialog.

IMPORTANT

Deletion is permanent and cannot be undone. Credentials associated with the agent are invalidated, and any integration still using the Client ID / Client Secret pair starts failing. An access token that was already issued stays valid until it expires.

Audit Log record

Creating, editing, or deleting an AI Agent generates a queryable record in the Access Control Audit Log, with the date, the author, the outcome of the operation, and the content of the object. Generating, regenerating, and revoking the agent's credential also generate a record. Listing agents, opening the details, and viewing the credential do not: only write operations are audited.

The record can be queried by filtering on AI Agent (the agent) or AI Agent Credential (the credential), values exclusive to AI Gateway, so you do not need to combine them with the Product filter. In the Name column of the Audit Logs screen you see the agent identifier, not its name, except on a failed creation: the identifier only exists once the creation succeeds, so the field stays empty. On an edit, a deletion, or a credential operation, the identifier is the one given in the request, converted to lowercase. Creating and deleting an agent appear only under the AI Agent filter, even though they also issue and remove the credential.

On success, the agent record content is the identifier, name, description, Client ID, and the scope identifiers. The Client Secret never appears in the record, on success or on failure. On success, the credential record states which operation took place (ROTATE, REACTIVATE, or REVOKE) and the previous status, ACTIVE or REVOKED. The operation follows the credential status, not the button label: ROTATE when the credential was active and REACTIVATE when it was revoked. Without the Read AI Agent Credentials permission, the button reads Regenerate client secret even for a revoked credential. A revocation that fails after the status was read carries the same operation (REVOKE) and the previous status, for the attempt. When the status is not known, the record carries only the agent identifier: on a failed generate or regenerate, when the agent does not exist, or when the status could not be read before revocation, even if the revocation then succeeds.

A request refused right at the entry point (for example, a Name that is blank or exceeds 255 characters, a Description above 1024 characters, or more than 100 scopes) generates no record. From the moment the operation is processed, both success and failure generate a record, with the refusal reason and the content that was attempted: a name already used by another agent, a scope that does not exist, and an agent that does not exist all show up in the trail as a failure. When the failure is unexpected, the reason is a generic message.

On a failed creation, the content shows what was sent. On a failed deletion, it is the state of the agent read before removal; when the agent cannot be read before removal, the deletion record carries only the identifier.

In a rare case, the creation failure arrives after the agent already exists, for example when granting the scopes fails. The record is a failure record, with no identifier. Check the agent list before trying again: the agent may already exist, without its scopes granted. If it does, edit that agent instead of creating another.

Querying the Audit Log uses the Audit List and Audit View permissions, which already govern that screen.

Form fields

The table below covers all editable fields in the creation and edit forms. The Credentials section is managed separately (see Manage credentials).

Permissions

Access to each action in the AI Agents journey depends on its own permission. Without the corresponding permission, the screen element does not appear — the interface never shows an unavailable action as disabled.

Permissions are granted in Access Control, on the Roles screen, under the AI Gateway product. The table below lists each one exactly as Access Control displays it.

A control without its permission is not rendered; an AI Agent reached directly by URL without its permission lands on the AI Gateway's own access denied screen, not on Access Control's.

CREDENTIALS ARE A PERMISSION SEPARATE FROM THE RECORD

Viewing and rotating an AI Agent's credentials does not depend on Create and Update AI Agents or Delete AI Agents — whoever administers the agent's record (name, description, scopes) may have no access at all to its identity secret, and vice versa. Read AI Agent Credentials is the only read permission in the entire AI Gateway product that is not part of the Read-Only profile.