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.
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:
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:
- The id
ephemeralin thex-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_7xCfrom inside Claude Code iscustom/agent_7xC. - Subagent instance ids change on every spawn, so all Claude Code subagents share the key
claude_code/subagentand their instance ids are logged as runs. - A run id comes from
x-quilr-agent-run-id,metadata.agent_run_idor baggageagent.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.
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.
- In All agents or Review, select Declare (or Open on a declared agent).
- 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.
- 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:
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_7xCorclaude_code/subagent. Family rows such asclaude_code/~climay 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.
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:
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
- Open the control on the Controls tab, for example Gateway Access, and pick a recipe or Add.
- 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.
- 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:
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: refuseon the quota in the technical source or the Budgets API. - A refused request gets
429quota_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.
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.
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
- Select Add rule and give it a name, for example Coding agents: no Claude Code on the support app.
- Add the condition client app is any of
claude_code, then application is any of your app. - 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:
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.
Related
- Agents API
- Agent monitoring
- Gateway access and allowed models
- Budget recipes
- Policy Engine overview
- Console Agents - the estate-wide agent inventory under Observe, separate from this tab.