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 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 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.

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.

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.