Skip to main content

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.

Agent identity is a label

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.

Observed
Seen in traffic
Last 30 days
Declared
Display name, owner
Description, tags
Agent groups
Listed keys
Match rules
Built-in groups
QuilrAI
CallWhat it doesScope
GET /agentsList agents seen in the last 30 days and every declared agent.read
POST /agents/_declareDeclare up to 500 agents at once with the same owner and tags.agents:write
GET /agents/{key}Read one agent.read
POST /agents/{key}/effectiveWhat the live policy applies to the agent for a sample request.read
PUT /agents/{key}Declare an agent, or replace its declaration.agents:write
PATCH /agents/{key}Change some fields of a declared agent.agents:write
DELETE /agents/{key}Remove a declaration. The agent stays listed while it appears in traffic.agents:write
GET /agent-groupsList built-in and custom agent groups.read
GET /agent-groups/{group_id}Read one group.read
PUT /agent-groups/{group_id}Create or replace a group.agents:write
PATCH /agent-groups/{group_id}Change some fields of a group.agents:write
DELETE /agent-groups/{group_id}Delete a group. Refused while rules name it, unless force=true.agents:write
GET /agent-groups/{group_id}/membersList a group's current members and how each one matched.read
GET /agent-familiesList families with their surfaces and 30-day counts.read

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:

QueryMeaning
qText in the key, name or owner.
familyOnly this family (custom, claude_code, ...).
statusdeclared or observed.
groupOnly members of this agent group (422 agent_group_unknown if no group has that id).
appOnly agents seen under this application.
limit, cursorPage size (1-500, default 100) and the next_cursor of the previous page.

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.

Agent fieldMeaning
key, family, surface, idThe agent key and its parts. surface is set for family rows and subagents, for example cli.
name, observed_nameThe display name (the declared one when set) and the name the client sent.
statusdeclared or observed.
owner, description, tagsFrom the declaration; null / empty when not declared. owner is a label only and never changes who a request is charged to.
groupsIds of the agent groups it is in now.
appsApplications it was seen under in 30 days.
first_seen, last_seen, requests_30d, users_30d30-day activity. users_30d is null when not yet known.
version, updated_at, updated_byDeclared agents only. Send version as If-Match. A Management API write is recorded as management_key:<key_id>.
{
"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} takes display_name, owner, description and tags (up to 20) and replaces the whole declaration. It answers 201 for a new declaration and 200 for 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 warning agent_not_seen under warnings.
  • PATCH /agents/{key} changes only the fields you send; null clears one. It answers 404 agent_not_declared when the agent is not declared yet.
  • DELETE /agents/{key} removes the declaration and answers {deleted: true, key, registry_version}. The agent stays listed as observed while it appears in traffic.
  • POST /agents/_declare declares 1-500 keys at once: {"keys": [...], "owner": "...", "tags": [...]} (display_name and description are 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):

idMembers
all-agentsEvery agent that is named. Family rows (<family>/~<surface>) are not members.
undeclared-agentsAgents seen in traffic that nobody has declared.
coding-toolsDetected coding-tool families such as Claude Code, Codex and OpenCode.

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}}'
Group fieldMeaning
display_name, descriptionWhat the console shows.
keysAgent keys that are always members. Family rows may be listed.
exclude_keysKeys that are never members. An exclusion beats keys and match.
matchRules that add agents automatically, below.
id, builtin, version, updated_at, updated_byReturned on reads. Send version as If-Match.
match fieldMatches
familiesA family (claude_code) or a family and surface (claude_code/desktop).
surfacesA surface such as cli, desktop or subagent.
name_globs, id_globsCase-insensitive patterns on the agent name ("KYC *") or id ("agent_*").
apps, app_tagsApplication names (patterns allowed) the agent was seen under, or their tags.
tagsTags set when the agent was declared.
declaredtrue, false or null (either).
max_users_30dAt most this many people in 30 days. An agent with no people figure yet never matches.

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.

  • PUT answers 201 for a new group and 200 for a replaced one, with {agent_group, registry_version, applies_within_seconds}.
  • PATCH changes only the fields you send; 404 agent_group_not_found when the group does not exist.
  • DELETE answers {deleted: true, id, registry_version}. While a published rule, control or budget names the group, it answers 409 group_in_use with references, one entry per rule (kind, policy, rule_index, priority). Change those first, or send ?force=true to 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, user and requested_model are optional strings. Unknown fields answer 400 invalid_request.
  • agent_scope is agent, agent_group or agent_family when the deciding rule is scoped to the agent, one of its groups or its family, else null. managed is true for Management API controls.
  • allow_mode is replace when an agent-scoped list replaced the other allowed-model lists, union when the lists combine. requested_model_allowed is set when you send requested_model.
  • 503 policy_unavailable when 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:

FieldValuesPriority
agentsAgent keys, such as custom/kyc_reviewer.940
agent_groupsAgent group ids, built-in ids included.930
agent_familiesA family (claude_code) or a family and surface (claude_code/cli).920

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 (or agent.key), agent_family and agent.run_id. A request that names no agent is not counted by such a budget; "missing_id": "refuse" refuses it instead. The agent alias still means the legacy request.metadata.agent_id.
  • Reads return the lists back, for example a budget's applies_to.agent_groups.
  • 422 agent_key_invalid for a malformed key, 422 agent_group_unknown for a group id that does not exist.

Writes and errors​

  • PUT, PATCH and DELETE take an optional If-Match: "<version>" with the version a read returned. A stale version answers 412 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.
StatusCodeWhen
400invalid_requestThe body is not a JSON object, or a query value (status, limit, cursor) is not valid.
403insufficient_scopeThe key lacks read (reads) or agents:write (writes).
404agent_not_foundThe agent was neither declared nor seen in 30 days.
404agent_not_declaredPATCH or DELETE of an agent that is not declared.
404agent_group_not_foundNo group has this id.
409builtin_group_read_onlyA write to a built-in group.
409agent_group_limitThe organization already has 200 groups.
409group_in_useDELETE of a group that published rules still name. The body lists references; retry with ?force=true to delete anyway.
412version_conflictIf-Match is stale. Read again and retry.
422agent_key_invalidThe key is not <family>/<id>.
422agent_key_family_onlyA family key (<family>/~<surface>) was declared.
422agent_group_unknownGET /agents?group=, a control scope or a budget's applies_to names no group.
422validation_failedAn unknown field, a bad group id, too many tags, keys or patterns, or a value of the wrong type. field names it.
503central_service_requiredA write on an isolated deployment. Make the change on the central service.
503management_storage_unavailableThe change could not be saved. Retry.
503policy_unavailableThe live policy could not be read in time (effective check, or the in-use check before a group delete). Retry; a delete can also use ?force=true.