Agents API
Read the agents the LLM Gateway has seen in the last 30 days, declare the ones you know with an owner and tags, gather agents into agent groups, scope controls and budgets to them, and check what applies to an agent. The same data appears on the Agents tab under Govern > Policy Engine > LLM Gateway in the console. See Agents and coding tools for how the gateway identifies agents.
Agents are identified from what the client sends (x-quilr-agent-id and related headers, request metadata, W3C baggage or a detected coding tool such as Claude Code). The caller is authenticated by its API key or token; the agent is worked out from what it sends. A caller can send any id, so treat an agent as a label, never as authentication.
Every path is relative to https://<your-gateway-host>/llmgateway/management/v1 and takes Authorization: Bearer <management key>. Bodies and responses are snake_case JSON. Issue a key with the Manage agents scope (agents:write) on the console Management API tab, like the other scopes; see Management API.
Agent keys
An agent key is <family>/<id>, for example custom/agent_7xC or claude_code/subagent. The family is lower-case letters, digits and _. The id keeps letters, digits, -, . and _ and percent-encodes everything else. A key is at most 320 characters; a very long id gets a hashed key <family>/~h.<hash>, which can be declared.
<family>/~<surface> and <family>/~any (for example claude_code/~cli) name a detected client that sent no agent id. They are listed and can go in a group, but declaring one answers 422 agent_key_family_only.
In a path, URL-encode the key: custom%2Fagent_7xC.
Agents
export API="https://<your-gateway-host>/llmgateway/management/v1"
curl "$API/agents?status=observed&family=custom&limit=50" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
GET /agents lists agents most recently active first. Filters:
The response is {agents, total, next_cursor, registry_version, observed_available, observed_complete, window_days}. next_cursor is present only when another page exists. observed_available is false where traffic can't be read; declared agents are still listed. window_days is 30.
{
"key": "custom/agent_7xC",
"family": "custom",
"surface": null,
"id": "agent_7xC",
"name": "FinSight Auditor",
"observed_name": "FinSight Auditor",
"status": "declared",
"owner": "finance-platform@example.com",
"description": null,
"tags": ["finance"],
"groups": ["all-agents", "finance-agents"],
"apps": ["zz-docs-finance"],
"first_seen": "2026-10-21T08:00:00Z",
"last_seen": "2026-11-19T07:58:00Z",
"requests_30d": 1240,
"users_30d": 5,
"version": "3f1c...",
"updated_at": "2026-11-19 08:00:00.000",
"updated_by": "management_key:mk_example"
}
GET /agents/{key} returns {agent, registry_version}, or 404 agent_not_found when the key was neither declared nor seen in 30 days.
Declare agents
Declare one agent with PUT:
curl -X PUT "$API/agents/custom%2Fagent_7xC" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"display_name": "FinSight Auditor", "owner": "finance-platform@example.com", "tags": ["finance"]}'
PUT /agents/{key}takesdisplay_name,owner,descriptionandtags(up to 20) and replaces the whole declaration. It answers201for a new declaration and200for a replaced one, with{agent, registry_version, applies_within_seconds}. Any well-formed key can be declared, seen or not; a key with no traffic in 30 days adds the warningagent_not_seenunderwarnings.PATCH /agents/{key}changes only the fields you send;nullclears one. It answers404 agent_not_declaredwhen the agent is not declared yet.DELETE /agents/{key}removes the declaration and answers{deleted: true, key, registry_version}. The agent stays listed asobservedwhile it appears in traffic.POST /agents/_declaredeclares 1-500 keys at once:{"keys": [...], "owner": "...", "tags": [...]}(display_nameanddescriptionare accepted too). Keys already declared are left as they are. The response is{declared, already_declared, registry_version}.
{"keys": ["custom/agent_7xC", "custom/invoice_extractor"], "owner": "finance-platform@example.com", "tags": ["finance"]}
Agent groups
GET /agent-groups returns {agent_groups, registry_version, limits}, built-in groups first. The built-in groups are computed by the gateway and read only (409 builtin_group_read_only):
Create or replace a group with PUT /agent-groups/{group_id}. The id is 1-64 lower-case letters, digits, - and _.
curl -X PUT "$API/agent-groups/personal-agents" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"display_name": "Personal agents", "exclude_keys": ["custom/support_triage"], "match": {"families": ["custom"], "max_users_30d": 1}}'
Every match field you send must hold (AND); any value in one list may match (OR). A group with no keys and an empty match has no members. Membership is worked out on every request, so a new agent joins on its first request.
PUTanswers201for a new group and200for a replaced one, with{agent_group, registry_version, applies_within_seconds}.PATCHchanges only the fields you send;404 agent_group_not_foundwhen the group does not exist.DELETEanswers{deleted: true, id, registry_version}. While a published rule, control or budget names the group, it answers409 group_in_usewithreferences, one entry per rule (kind,policy,rule_index,priority). Change those first, or send?force=trueto delete anyway; the rules then match no agent.
{"error": {"code": "group_in_use", "message": "1 policy rule(s) name this agent group; change them first, or delete with ?force=true (those rules then match no agent)",
"references": [{"kind": "managed", "policy": "quilr_managed_budgets", "rule_index": 6, "priority": 50}]}}
Limits: 200 groups per organization, 5,000 keys per group, 50 name_globs and id_globs combined per group, and an agent counts in at most 64 groups.
Members
GET /agent-groups/{group_id}/members (with limit and cursor) returns {members, total, next_cursor, observed_available, registry_version}. Each member is {key, name, family, status, last_seen, matched_by}, where matched_by is key (listed), match (a match rule) or builtin. A listed key that was never seen or declared has status: "not_seen".
{
"members": [
{"key": "custom/agent_7xC", "name": "FinSight Auditor", "family": "custom", "status": "declared", "matched_by": "match", "last_seen": "2026-11-19T07:58:00Z"}
],
"total": 1,
"observed_available": true,
"registry_version": 1763539200000
}
Agent families
GET /agent-families returns every family the gateway recognizes with its surfaces and 30-day counts:
{
"agent_families": [
{"family": "claude_code", "agents_30d": 2, "requests_30d": 50210,
"surfaces": [{"surface": "cli", "agents": 2, "requests_30d": 48000}]}
],
"observed_available": true,
"window_days": 30
}
Effective controls
POST /agents/{key}/effective evaluates the live policy for a sample request from the agent and says what applies and which rule decided it. It is a simulation: nothing is logged or charged. The body is optional:
curl -X POST "$API/agents/custom%2Fkyc_reviewer/effective" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"app": "onboarding-service", "user": "dev@example.com", "requested_model": "gpt-5.4"}'
{
"agent": {"key": "custom/kyc_reviewer", "family": "custom", "presence": "agent", "declared": true,
"groups": ["all-agents", "regulated-workflows"]},
"revision": 7, "policy_enabled": true,
"access": {"action": "allow", "decided_by": {"policy": "kyc_allow", "rule_index": 0, "priority": 940, "managed": false, "agent_scope": "agent"}},
"models": {"allowed_models": ["claude-sonnet-4-5"], "denied_models": ["gpt-4o"], "allow_mode": "replace",
"requested_model_allowed": false, "decided_by": {"policy": "quilr_managed_agent_model_access_930", "rule_index": 0, "priority": 930, "managed": true, "agent_scope": "agent_group"}},
"routing": {"group": null, "targets": null, "decided_by": null},
"quotas": [{"id": "regulated_daily", "metric": "requests", "limit": 1000, "window": {"kind": "rolling", "unit": "day"},
"group_by": ["agent.key"], "mode": "enforce", "decided_by": {"policy": "quilr_managed_budgets", "rule_index": 3, "priority": 50, "managed": true, "agent_scope": "agent_group"}}],
"rules": [{"policy": "kyc_allow", "rule_index": 0, "priority": 940, "agent_scope": "agent", "effects": ["access.action"]}],
"simulated": ["access", "models", "routing", "quotas"],
"not_simulated": ["data protection", "guardian", "content routing"]
}
app,userandrequested_modelare optional strings. Unknown fields answer400 invalid_request.agent_scopeisagent,agent_grouporagent_familywhen the deciding rule is scoped to the agent, one of its groups or its family, elsenull.managedistruefor Management API controls.allow_modeisreplacewhen an agent-scoped list replaced the other allowed-model lists,unionwhen the lists combine.requested_model_allowedis set when you sendrequested_model.503 policy_unavailablewhen the live policy could not be loaded within 10 seconds. Retry.
Agent scopes
Every scope in the managed controls (/controls/access, /controls/model-access, /controls/routes, /controls/rate-limits and the others) and every budget's applies_to take three agent lists next to apps, smart_groups and users:
The most specific scope wins: agent 940, agent group 930, agent family 920, then person, group and app rules. Budgets all count: every matching budget is charged. Agent rows can loosen as well as tighten. On access controls, block: false (or require_identity / require_conversation_id: false) is accepted only on agent scopes and lets the agent through an app or person block; see Access controls. An allowed-models list scoped to agents replaces the app, person and group lists (allow_mode: replace); lists at the same level combine, and denied models always apply.
# Only claude-haiku-5-5 for one agent
curl -X PUT "$API/controls/model-access/kyc-models" \
-H "Authorization: Bearer $MANAGEMENT_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"scope": {"agents": ["custom/kyc_reviewer"]}, "allow": ["claude-haiku-5-5"]}'
# Let one approved agent through when its app is blocked
curl -X PUT "$API/controls/access/kyc-allowed" \
-H "Authorization: Bearer $MANAGEMENT_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"scope": {"agents": ["custom/kyc_reviewer"]}, "settings": {"block": false}}'
# 1,000 requests a day for each agent in a group
curl -X POST "$API/budgets" \
-H "Authorization: Bearer $MANAGEMENT_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"id": "regulated_daily", "label": "1,000 requests per agent per day", "metric": "requests", "limit": 1000,
"window": {"kind": "rolling", "unit": "day"}, "per": ["agent_key"],
"applies_to": {"agent_groups": ["regulated-workflows"]}}'
- Budgets and rate limits can count per
agent_key(oragent.key),agent_familyandagent.run_id. A request that names no agent is not counted by such a budget;"missing_id": "refuse"refuses it instead. Theagentalias still means the legacyrequest.metadata.agent_id. - Reads return the lists back, for example a budget's
applies_to.agent_groups. 422 agent_key_invalidfor a malformed key,422 agent_group_unknownfor a group id that does not exist.
Writes and errors
PUT,PATCHandDELETEtake an optionalIf-Match: "<version>"with theversiona read returned. A stale version answers412 version_conflict.- Writes are audited and reach every gateway server within
applies_within_seconds(about 2 minutes). - Writes run on the central gateway service only.
Related
- Agents and coding tools - the Agents tab, agent scopes in the console and policy rules for coding tools and agents.
- Budgets API - budget fields, including
applies_toandper. - Agent monitoring - the agent and tracing signals the gateway logs.
- Management API - authentication, errors and retry rules for every endpoint.