Skip to navigation

Agent Audit plugin

The Agent Audit plugin writes one audit event for each request from a caller with an agent identity, whether the request was allowed or refused. The event is an agent.decision log line at INFO level on the data plane. The plugin never changes a request or response, and it passes every value through the gateway’s secret redaction first.

A caller has an agent identity when JWT Auth, Postman API key auth, or API key to access token identified it. Users identified that way are recorded without emit_for_humans. Callers identified by Key Auth are recorded only with emit_for_humans on.

Where it runs

ProtocolsThe console offers it for MCP routes. The gateway itself runs it on any protocol, so a global instance also applies to HTTP and LLM routes.
Scope kindsglobal, route, on MCP routes
PhaseAfter the response, or after a failed forward

Set up the plugin

Set up Agent Audit to log one agent.decision event for every request from an agent, so that you can review what agents did and what the gateway decided.

Prerequisites

Before you begin, make sure you have the following:

  • Permission to create plugin instances.
  • An MCP route whose callers are agents. The console offers this plugin for MCP routes.
  • An authentication plugin on the route that attaches an agent identity, such as JWT Auth. Callers without an agent identity are recorded only when emit_for_humans is on.
  • Access to the data plane’s logs, because the events are log lines and not console records.

Steps

To add an Agent Audit instance, do the following:

  1. In the sidebar, select Plugins.
  2. On the All tab, find Agent Audit, and then select Use. The New plugin instance form opens.
  3. In Apply to, select Global to record every MCP route, or Route to record specific routes. If you select Route, use Routes to select one or more routes. Fabric creates one instance for each route.
  4. In Instance name, enter a name. If you select several routes, the field is Base name, and Fabric builds each instance name from it.
  5. (Optional) To change what the events contain, under Configuration, select Edit as JSON, and set emit_for_humans, include_request, or include_scopes. The console has no dedicated form for this plugin. With no configuration, the plugin records agents with the request’s method and path and the caller’s scopes.
  6. (Optional) Expand Match conditions (optional) to limit when the instance runs. The conditions are Path prefix, Methods, Consumer, and Consumer group. All conditions must match.
  7. Confirm that Enabled is selected. Fabric saves a disabled instance but doesn’t run it.
  8. Select Create instance.

Verify it works

To check that the plugin records events, do the following:

  1. Send a request through the route as an agent.
  2. In the data plane’s logs, find the line with the message agent.decision. It’s written at INFO level after the response, and it names your route and principal_id. For where to read the logs, see Monitor a data plane.
  3. Send a request that the gateway refuses, such as one without a required scope. The event has decision set to deny and forwarded set to false.

Fix common problems

ProblemCauseFix
No agent.decision event appears.The caller has no agent identity and emit_for_humans is off, the instance is disabled, or the route isn’t in the instance’s scope.Check the authentication plugin, the Enabled setting, and the scope. To record every caller, set emit_for_humans to true.
The event shows decision: deny for a request that succeeded.The gateway answered the request itself, such as an MCP initialize or ping, so nothing was forwarded.Check forwarded and dispatch_path together with decision.
The event has no request ID.The plugin doesn’t add one.Match the event to the access log by route, timestamp, and principal_id.
Users show up in the log.Users identified by JWT Auth or Postman API key auth carry an agent identity, so the plugin records them.Filter on principal_type.

The console doesn’t show agent.decision events. The data plane writes them only to its log.

Configuration

FieldTypeDefaultDescription
emit_for_humansbooleanfalseAlso records callers with no agent identity.
include_requestbooleantrueAdds method and path to the event. The path is the one sent to the upstream, after the route rewrites it.
include_scopesbooleantrueAdds the caller’s scopes to the event, as one comma-separated scopes value.

The gateway also reads a logger field and ignores it. Every event goes to the data plane’s default logger.

Each event has event, timestamp, protocol, decision (allow or deny), and forwarded. For a caller with an agent identity, it also has auth_mode, principal_id, principal_type, subject_id, tenant_id, user_id, and session_id, and consumer_type and installation_uid when the identity carries them. tenant_id is the caller’s own team, not your gateway tenant. The event has the route and service when a route matched, and on MCP tools/call the mcp_tool and the upstream. When the gateway answers a Tool Search meta-tool itself, the event has dispatch_path and dispatch_meta_tool. The event has no request ID, status, or duration.

Some requests leave no event: requests that fail before any plugin runs, such as an unmatched route, and requests that fail authentication, because no agent identity exists yet and emit_for_humans is off.

Example

{
"name": "audit-agents",
"plugin_id": "agent-audit",
"scope": { "kind": "global" },
"config": { "include_scopes": true }
}
⌂ 换网址