Skip to main content

Agents and coding tools

Updated on 20 November 2026.

The LLM Gateway works out which agent or coding tool sent each request. The Agents tab lists every agent seen in the last 30 days, lets you declare the ones you know and gather them into agent groups. Controls and policy rules then allow or block, budget, rate limit, route and limit the models of one agent, an agent group or a whole family, and Effective controls shows what applies to an agent and why.

Go toQuilrAI consoleGovernPolicy EngineLLM GatewayAgents
Agent identity is a label, not authentication

The gateway authenticates the caller by its API key or token. The agent is then worked out from what that caller sends, so every agent signal comes from the client: a caller can send any agent id, copy another agent's id or leave the headers out. Agent controls apply to whatever agent a request names, exactly like user and app controls, so use them to govern normal traffic. Use gateway keys, identity and network trust and gateway access when you need to know who called.

What counts as an agent​

The gateway sorts what it finds into three levels:

LevelWhat it isExample key
FamilyThe kind of client: your own agents (custom), a coding tool or an agent platform.claude_code, codex, custom, copilot_studio
AgentOne named agent within a family.custom/agent_7xC, claude_code/subagent
RunOne run of an agent. Runs are logged, not listed.A run id from x-quilr-agent-run-id

Every agent has a key, <family>/<id>. Your own agents use custom/<id>, for example custom/agent_7xC. Characters other than letters, digits, -, . and _ are percent-encoded in the key, which is at most 320 characters. A very long id gets a hashed key, <family>/~h.<hash>.

A request from a coding tool that names no agent shows as a family row, <family>/~<surface>: for example claude_code/~cli for Claude Code in the terminal or claude_code/~desktop for the desktop app. A family row is a detected client, not an agent. You cannot declare it, but you can list it in an agent group.

How the gateway identifies agents​

The gateway checks these sources in order and uses the first id it finds:

OrderSourceFamily
1x-quilr-agent-id header, or metadata.agent_id in the request body. The header wins. Name: x-quilr-agent-name / metadata.agent_name; type: x-quilr-agent-type.custom
2W3C baggage entry agent.id or gen_ai.agent.id (name: agent.name or gen_ai.agent.name).custom
3x-agent-id header.custom
4LiteLLM x-litellm-agent-id header.litellm
5Microsoft Copilot Studio agent metadata.copilot_studio
6OpenClaw cron jobs.openclaw
7A coding tool's subagent marker: Claude Code x-claude-code-agent-id, Codex x-openai-subagent.claude_code/subagent, codex/subagent
8The coding tool itself, detected from its client headers (Claude Code, Codex, OpenCode, Cline, Gemini CLI and others).Family row such as claude_code/~cli
  • The id ephemeral in the x-quilr-agent-* headers means "no agent": the gateway moves on to the next source.
  • A declared id wins over a detected tool. An agent that sends x-quilr-agent-id: agent_7xC from inside Claude Code is custom/agent_7xC.
  • Subagent instance ids change on every spawn, so all Claude Code subagents share the key claude_code/subagent and their instance ids are logged as runs.
  • A run id comes from x-quilr-agent-run-id, metadata.agent_run_id or baggage agent.run_id, among others. See Agent monitoring for every tracing signal the gateway logs.

The Agents tab​

The tab has four views: All agents, Review, Agent groups and Families. Use Search name, key, owner or tag to filter a list.

New traffic shows up within about 5 minutes, because the list is cached.

All agents​

Agents seen in the last 30 days and every declared agent, most recently active first.

ColumnMeaning
AgentThe display name and the key.
FamilyCustom agent, Claude Code, Codex, Copilot Studio and so on.
Statusobserved (seen in traffic) or declared (an administrator declared it).
GroupsThe agent groups it is in now.
People 30dDistinct people who sent its requests in the last 30 days.
Requests 30dIts requests in the last 30 days.
Last seenIts most recent request.

Select Open to see an agent, or Declare on an observed agent.

Review​

Observed agents first seen in the last 7 days that nobody has declared. Declare them one by one with Declare, or all at once with Declare all.

Declare an agent​

Declaring records what an agent is and who owns it. It does not change how its requests are handled.

  1. In All agents or Review, select Declare (or Open on a declared agent).
  2. Fill in the drawer:
    • Display name: shown instead of the name the client sends.
    • Owner: a label only. It never changes who a request is charged to.
    • Description.
    • Tags: comma separated. Agent group rules can match tags.
  3. Select Save.

Remove declaration turns the agent back into an observed one. It stays listed while it appears in traffic.

The drawer of a family row such as Claude Code · cli shows the same activity but has nothing to declare, since the client named no agent. Set controls on it with the agent family scope.

Effective controls​

The Effective controls tab of an agent's drawer shows what the gateway applies to that agent now. Optionally fill in an App, a Person and a Requested model to see what applies to that request, then select Check.

With a Requested model, a Requested model row says whether that model would be refused, for example "gpt-5.4 would be refused", and which rule decides it. When an agent's own model list applies, Allowed models notes that it replaces every app and person list. Each row names the rule that decided it, its priority and rule number. Agent, Agent group and Agent family tags mark rules scoped to the agent, one of its groups or its family; API managed marks controls set through the Management API. The check evaluates the live policy for a sample request: access, allowed and rejected models, routing and quotas. Data protection, Guardian and content routing depend on the prompt and are not shown.

Agent groups​

Agent groups collect agents so that you can find and review them together. Membership is worked out on every request, so a new agent joins on its first request.

Built-in groups are kept up to date by the gateway and can't be edited:

GroupMembers
All agentsEvery request that names an agent. Family rows are not members.
Undeclared agentsAgents seen in traffic that nobody has declared.
Coding toolsDetected coding tools such as Claude Code, Codex and OpenCode, including their family rows and subagents.

To create a group, select New agent group and fill in:

  • Group id: lower-case letters, digits, - and _. It can't be changed later.
  • Name and an optional Description.
  • Agents in this group: agent keys, one per line or comma separated, for example custom/agent_7xC or claude_code/subagent. Family rows such as claude_code/~cli may be listed.
  • Never in this group: keys that never join, even when they match. An exclusion always wins.
  • Match rules: add an agent automatically when it matches.
Match ruleMatches
FamiliesA family (claude_code, custom) or a family and surface (claude_code/desktop).
Agent namesName patterns such as KYC *. Case-insensitive; * and ? are wildcards.
Agent idsId patterns such as agent_*.
AppsApplications the agent was seen under (patterns allowed).
App tagsTags of those applications.
Agent tagsTags set when the agent was declared.
At most this many people in 30 daysAgents used by few people, for example personal experiments. An agent with no people figure yet never matches.
DeclaredAny, Declared or Not declared.

Every rule you fill in must match (AND). Within one rule, any value may match (OR). A group with no listed keys and no rules has no members.

Select Create group (Save when editing). To delete a group, open it and select Delete, then Delete group.

If a published rule, control or budget still names the group, the dialog lists them, for example Budgets · Management API, rule 7, and asks again. Delete anyway deletes the group, and those rules then match no agent. Remove or change them first if they should keep applying.

Limits: 200 groups per organization, 5,000 listed keys per group, 50 name and id patterns per group, and an agent counts in at most 64 groups.

Families​

Every family seen in the last 30 days, with its surfaces and their request counts, and the number of agents and requests per family.

Permissions​

Viewing the tab needs LLM Gateway read access. Declaring agents and creating or editing groups needs update access. Removing a declaration or deleting a group needs delete access.

Control agents, agent groups and families​

Agents are a scope, like people, groups and apps. Every control that has an Applies to section can target:

ScopeMatchesPriority it gets
AgentsOne or more agent keys, such as custom/kyc_reviewer or claude_code/subagent.940
Agent groupsEvery agent in one of the groups, built-in groups included.930
Agent family (under More targeting options)A whole family such as claude_code, or one surface such as Claude Code · cli.920

The most specific scope wins: an agent rule beats an agent-group rule, which beats a family rule, which beats every person, group and app rule (900 and below). So you can block Claude Code for an app and still allow one approved agent, or give one agent a tighter model list than its app. An agent rule can loosen as well as tighten, exactly like a person rule. Budgets are the exception: every matching budget counts, so an agent's budget adds to the app's budget instead of replacing it.

A request that names no agent never matches an agent scope.

Scope a control to agents​

  1. Open the control on the Controls tab, for example Gateway Access, and pick a recipe or Add.
  2. Under Applies to, select Agents or Agent groups, or open More targeting options and select Agent family. Pick values from the list: it is filled from your agents, groups and families, and you can type a key or a pattern.
  3. Choose the outcome, then Save to draft and Review & publish.

The form shows the priority the scope sets, for example "Priority 930 (set from who it applies to)". Change it in the full editor if you need to.

The Controls overview counts agent scopes, for example "On for 2 apps, 3 people and 1 agent".

Budget each agent​

In Budgets & Usage Limits, the Who list of a budget or rate limit has four agent choices:

WhoCounts
Agent groupOne shared allowance for every agent in the groups you pick.
Each agent in a groupA separate allowance for every agent in the groups you pick.
Each agentA separate allowance for every agent.
Each agent runA separate allowance for every run of an agent.

The budget list shows how many agents each budget counted and which are closest to their limit:

  • Requests that name no agent are not counted by a per-agent budget. To refuse them instead, tick Refuse requests that have no agent id under Each agent, or set missing_id: refuse on the quota in the technical source or the Budgets API.
  • A refused request gets 429 quota_exceeded, with the budget's label in the message, for example "Request limit 'QA p2: 2 requests per agent per day' (rolling day) reached (2 requests)".
  • Agent ids come from the client, so a caller that sends a new id on every request starts a new allowance each time. Prefer Each agent in a group with a group of declared agents, and keep a shared budget on the app as a ceiling.

Limit an agent's models​

On Allowed Models, an allowed-models list scoped to an agent, agent group or family replaces the lists from its app, people and groups: the agent can use only the models in its own list. Lists at the same level (two agent groups, say) combine. Rejected models always apply.

For example, with the app allowing gpt-5.4 and claude-haiku-5-5 and an agent rule allowing only claude-haiku-5-5, the agent gets 403 policy_model_not_allowed for gpt-5.4, while the app's other traffic keeps both models. Use Effective controls with a Requested model to check.

Agent fields in rules​

In Policies > Add rule, the field list has an Agent section. Values are filled from your traffic and registry.

FieldVisual builderHolds
agent.keyAgentThe agent key, such as custom/kyc_reviewer or claude_code/~cli.
agent.groupsAgent groupsGroup ids the agent is in now, built-in groups included.
agent.familyAgent familyclaude_code, codex, custom and so on.
agent.surfaceAgent surfacecli, desktop, subagent and so on.
agent.id, agent.name, agent.typeAgent ID, Agent name, Agent typeWhat the client sent.
agent.run_idAgent run IDThe run id.
agent.declared, agent.tagsAgent is declared, Agent tagsFrom your declaration.
agent.presenceAgent presenceagent, family_only (a detected tool that named no agent) or none.
request.client.nameClient appThe detected coding tool: claude_code, codex, cline, gemini_cli and so on.

Family, surface, groups and tags compare case-insensitively.

To block one agent: Add rule, condition agent is any of the agent key, outcome Request access → deny.

The same rules in the technical source:

policy block_one_agent priority 940 {
request where agent.key in ["custom/kyc_reviewer"] then { access.action = deny; }
}

policy regulated_agents_models priority 930 {
request where arrayAny(agent.groups, g => g in ["regulated-workflows"]) then {
routing.model_allowlist = ["claude-sonnet-4-5", "gpt-4.1-mini"];
}
}

policy per_agent_daily priority 930 {
request where arrayAny(agent.groups, g => g in ["regulated-workflows"]) then {
limits.quotas = [{ id: "regulated_daily", metric: requests, limit: 1000, group_by: ["agent.key"], window: { kind: rolling, unit: day } }];
}
}

routing.model_allowlist is the replacing list described above; routing.allowed_models adds to the other lists. Quotas can group by agent.key, agent.family or agent.run_id.

Client app is not a security boundary

request.client.name comes from the headers the tool sends. It controls normal tool traffic, but a caller that strips those headers is not matched: the same key without Claude Code headers is allowed.

Coding tool recipes​

The recipes below match the coding tool with Client app. agent.family works the same way and also covers subagents and family scopes.

Block Claude Code for an app​

  1. Select Add rule and give it a name, for example Coding agents: no Claude Code on the support app.
  2. Add the condition client app is any of claude_code, then application is any of your app.
  3. Add the outcome Request access → deny, then Add rule.

The same rule in the technical source:

policy no_claude_code_support priority 500 {
request where
request.client.name in ["claude_code"]
and application.group_key in ["zz-docs-support-bot"]
then {
access.action = deny;
}
}

A blocked request gets 403 with code policy_access_denied and the message "request is denied by LLM Gateway policy".

Allow Claude Code only for one group​

Deny Claude Code to everyone outside the engineering smart group:

policy claude_code_engineering_only priority 500 {
request where request.client.name == "claude_code" and not arrayContains(user.smart_groups, "engineering") then { access.action = deny; }
}

Give a group a Claude Code budget​

$200 a calendar month for each person in engineering, for Claude Code traffic only:

policy claude_code_engineering_budget priority 500 {
request where request.client.name == "claude_code" and arrayContains(user.smart_groups, "engineering") then {
limits.quotas = [{ id: "cc_eng_monthly", metric: spend_usd, limit: 200, group_by: ["user.email"], window: { kind: calendar, unit: month } }];
}
}
  • For one pool shared by the whole group, use group_by: [].
  • Spend budgets need model prices. The safety check warns when a model has no price in Model pricing, and unpriced requests are blocked. See Rate, token and budget limits.

Cap a coding tool's requests​

At most 2 Codex requests a day on one app, shared by everyone:

policy codex_daily_cap priority 500 {
request where request.client.name in ["codex"] and application.group_key in ["zz-docs-support-bot"] then {
limits.quotas = [{ id: "codex_daily", metric: requests, limit: 2, group_by: [], window: { kind: rolling, unit: day } }];
}
}

Each allowed request carries x-quilr-quota-remaining. Once the cap is reached, the gateway answers 429 with code quota_exceeded ("Request limit (rolling day) reached (2 requests)...") and the headers x-quilr-quota-blocked-by (the quota id), x-quilr-quota-id, x-quilr-quota-remaining: 0, x-quilr-quota-reset and x-ratelimit-limit.

More caps​

Use the same limits.quotas shape with a different condition or group_by:

CapConditionQuota
$20 per person per Claude Code sessionrequest.client.name == "claude_code"metric: spend_usd, limit: 20, group_by: ["user.email", "request.metadata.conversation_id"], window: { kind: lifetime }
Claude Code subagents onlyagent.key == "claude_code/subagent"Any metric and window
Each agent in a grouparrayAny(agent.groups, g => g in ["regulated-workflows"])group_by: ["agent.key"]

See also Cap a conversation or an agent.

Manage agents with the API​

The Agents API lists agents, declares them in bulk, creates and edits agent groups, and shows an agent's effective controls, with the agents:write management scope.

Every Management API control scope (/controls/*) and every budget's applies_to also take agents, agent_groups and agent_families lists, with the same precedence as the console. See Agent scopes.