Agents

An agent is an identity in Dome that represents an application, assistant, or automated process making requests. Dome authenticates, authorizes, and audits each agent's calls to tools and models.

Refer to Agents concept for how agent identity works.

Overview

Dome separates an agent's identity from its credentials and access. Registering an agent creates a durable identity for the application or process, but does not grant access. An API key lets the runtime authenticate as that identity. Allowed resources, Gateway membership, and Rules determine what requests Dome permits.

Because credentials and access are separate, you can rotate a key without changing permissions or change permissions without issuing a new key.

The typical workflow is:

1. Register the agent to create the identity.
2. Get the agent to confirm the record and note the workspace gateway endpoint.
3. Allow the resources it needs.
4. Create an API key for the runtime.
5. Point the client at Dome. Refer to Develop.

When access must depend on the person the agent acts for, configure delegated identity. When one agent spawns others, set a parent at register time.

Allowed resources

An agent reaches only the resources you allow it: model pools, individual models, MCP tools, and Gateways. When an agent allows a Gateway, Dome lets it use that endpoint.

Allowing a resource is shorthand for creating a rule. Each entry generates a rule in the agent's rule bundle which the gateway enforces on the next request without a separate deploy. Because it creates rules, allowing a resource needs rules.deploy in addition to the permission to edit the agent, so someone with the developer role can register an agent and change its metadata but cannot change which resources it reaches.

Each selection generates the actions it implies:

When the shorthand cannot express a condition, such as a time window, a PII field, or an act-as claim, create Rules directly. A generated bundle adds to workspace defaults rather than replacing them.

You can allow resources when you register an agent or change them later.

Delegated identity

An agent can act for a person rather than only for itself. When it presents an act-as claim, Dome verifies the claim before authorizing the request, and the audit trail records the end user alongside the agent.

On the agent you choose the verification method (oidc, hmac, bound, or none), whether a claim is mandatory on every request, which provider to use, and optional allow-lists by group, email, or subject. An agent with no restrictions accepts any verified identity. Like allowed resources, these settings generate rules, so changing them needs rules.deploy.

Workspace providers, the workspace floor, and claim-aware Rules are on Delegated agents. You can configure per-agent settings when you register or update the agent.

Hierarchy

An agent can have a parent. The parent and its descendants form a hierarchy, which helps when one agent spawns or manages others and you want to act on them together. A hierarchy grants no access on its own, and each agent reaches only what you allow it.

A hierarchy can be at most 10 levels deep, and a parent and child must belong to the same tenant. You can set an agent's parent when you register it. An update cannot change it afterward. How lifecycle operations reach descendants is under Manage lifecycle.

Token lifetime

Each agent carries its own access-token lifetime. Set it on register or update with --token-ttl (CLI) or token_ttl (MCP and API), as a duration such as 15m. The default is 10m and the accepted range is 1m to 24h.

Shorten the lifetime for ephemeral jobs. Lengthen it only when refresh overhead justifies the larger exposure window. Clearing the value returns the agent to the 10m default.

Requirements

Before you begin:

• Install and authenticate the Dome CLI, then select a workspace context
• Create or select a Gateway, attach the required resources, and grant the agent access

Permissions

Agent registry, lifecycle, and key operations require platform permissions. Each operation states the permission it requires. For exhaustive flags, tool parameters, and endpoint contracts, refer to the CLI, MCP, and API references.

Register agent

Register an agent to create the record that credentials, allowed resources, and lifecycle operations attach to. You can set allowed resources, end-user identity, a parent, and a token lifetime in the same call.

dome agents register \
  --name "data-pipeline-agent"

{
  "name": "data-pipeline-agent"
}

POST /v1/agents
Content-Type: application/json

{
  "name": "data-pipeline-agent",
  "workspace_id": "{{WORKSPACE_ID}}"
}

Register an agent named "data-pipeline-agent".

{
  "id": "a1b2c3d4-...",
  "name": "data-pipeline-agent",
  "status": "provisioned"
}

A new agent starts in provisioned and becomes active on its first gateway request. Refer to Manage lifecycle for the full state model.

Register from a file

Register an agent from a YAML or JSON file when a reviewable definition is clearer than a long flag list, such as in CI. The file shape mirrors RegisterAgentRequest, the same schema the SDKs and Terraform provider consume, so a misspelled field fails fast instead of dropping silently. The workspace always comes from the active context. A workspace_id in the file is ignored.

name: data-pipeline-agent
allowed_pool_names: [openai-prod]
allowed_tools: [github/list_repos]

dome agents register --file agent.yaml

Update agent

Update an agent to change its metadata or token lifetime. Only the fields you send change, and list fields replace rather than merge.

dome agents update data-pipeline-agent \
  --metadata environment=production \
  --token-ttl 15m

{
  "agent_id": "data-pipeline-agent",
  "metadata": { "environment": "production" },
  "token_ttl": "15m"
}

PATCH /v1/agents/{{AGENT_ID}}
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "metadata": { "environment": "production" }
}

Update agent "data-pipeline-agent" to add metadata environment=production.

Change allowed resources

You can change which pools, models, tools, and Gateways the agent may reach. Refer to Allowed resources for what these grants mean. When you allow models, a pool is usually the better choice than an individual model, because a pool can fail over and load-balance.

dome agents update data-pipeline-agent \
  --pool "gpt-4-prod" \
  --tool "github/list-issues" \
  --tool "github/create-comment" \
  --gateway "{{GATEWAY_ID}}"

{
  "agent_id": "data-pipeline-agent",
  "allowed_pool_names": ["gpt-4-prod"],
  "allowed_tools": ["github/list-issues", "github/create-comment"]
}

PATCH /v1/agents/{{AGENT_ID}}
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "allowed_pool_names": ["gpt-4-prod"],
  "allowed_direct_model_names": [],
  "allowed_tools": ["github/list-issues", "github/create-comment"]
}

Restrict agent "data-pipeline-agent" to pool "gpt-4-prod" and tools github/list-issues and github/create-comment.

When you change one of these fields, the value you send replaces the existing list rather than merging into it, so a partial list drops whatever it omits and an empty value clears the list. API clients may use the canonical ID forms allowed_pool_ids, allowed_direct_model_ids, and allowed_tool_ids; they have the same rules.deploy requirement as the name forms, including during registration. Supply names or IDs rather than conflicting versions of both. In the dashboard, the agent detail page hides the edit control on Delegation when the caller lacks rules.deploy, and the edit form shows a banner explaining the limit.

The generated rules propagate through rule sync. Until an agent's generated rules match its saved access configuration, Dome withholds the affected Gateway admission rather than applying a partial grant.

Change end-user identity

You can also change how Dome verifies the end user an agent acts for, and which identities it may present. Refer to Delegated identity and Delegated agents for providers and the workspace floor.

dome agents update support-bot \
  --actas-method oidc \
  --actas-required \
  --actas-allowed-group "support-engineers"

{
  "agent_id": "support-bot",
  "actas_method": "oidc",
  "actas_required": true,
  "actas_allowed_groups": ["support-engineers"]
}

PATCH /v1/agents/{{AGENT_ID}}
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "actas_method": "oidc",
  "actas_required": true,
  "actas_allowed_groups": ["support-engineers"]
}

Require OIDC-verified act-as identity on agent "support-bot" and allow only the support-engineers group.

Populating an acceptable-identity list denies any request whose verified claim is not on the list. Leaving all three empty accepts any verified identity, and workspace-level act-as enforcement still applies.

Get agent

Retrieve an agent by name or UUID. Before you configure a runtime, you should retrieve an agent's information to confirm its status and the endpoint its traffic should reach.

Agent credentials cannot list the workspace roster, even when the agent can read its own record by ID. Use a platform user or platform key with agents.view for this operation.

dome agents get data-pipeline-agent

{
  "agent_id": "{{AGENT_ID}}",
  "gateway_id": "{{GATEWAY_ID}}"
}

GET /v1/agents/{{AGENT_ID}}?workspace_id={{WORKSPACE_ID}}&gateway_id={{GATEWAY_ID}}

Get "data-pipeline-agent" for Gateway "{{GATEWAY_ID}}" and confirm its status and connection endpoints.

When gateway_id is supplied, the response includes the agent record and that accessible Gateway's complete protocol endpoints. Omit it for metadata only.

{
  "agent": {
    "id": "a1b2c3d4-…",
    "name": "data-pipeline-agent",
    "status": "active"
  },
  "gateway_id": "{{GATEWAY_ID}}",
  "gateway_endpoints": {
    "gateway_id": "{{GATEWAY_ID}}",
    "gateway_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}",
    "mcp_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp",
    "openai_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/v1",
    "anthropic_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}"
  }
}

The dashboard shows the same pair on the agent detail page's Identity card, each with a copy button.

List agents

Retrieve a list of agents in a workspace. You can narrow the results by filtering on status, such as to find every suspended agent.

dome agents list --status active

{
  "status": "active",
  "limit": 25
}

GET /v1/agents?workspace_id={{WORKSPACE_ID}}&status=active

List the active agents in this workspace.

Manage lifecycle

An agent moves through four states. Provisioned and active agents can send traffic. Suspended and revoked agents are denied.

When agents are in a hierarchy, lifecycle operations reach descendants differently:

Parent and child must already share a tenant. Hierarchy does not grant access. Full transition detail is on the Agent Lifecycle concept.

Suspend

Suspend an agent to deny its requests until you reactivate it. Suspension is reversible. With cascade, it also suspends active descendants.

dome agents suspend data-pipeline-agent --reason "maintenance window"

{
  "agent_id": "data-pipeline-agent",
  "reason": "maintenance window",
  "cascade": false
}

POST /v1/agents/{{AGENT_ID}}/suspend
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "reason": "maintenance window"
}

Suspend agent "data-pipeline-agent" for a maintenance window.

Reactivate

Reactivate a suspended agent to restore its traffic. Reactivation applies only to an agent in the suspended state, and it covers one agent, so a cascaded suspension takes one reactivation per agent.

dome agents reactivate data-pipeline-agent

{
  "agent_id": "data-pipeline-agent"
}

POST /v1/agents/{{AGENT_ID}}/reactivate
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}"
}

Reactivate agent "data-pipeline-agent".

Revoke

Revoke an agent to decommission it permanently. Its record and audit history remain readable.

dome agents revoke data-pipeline-agent --reason "decommissioned"

{
  "agent_id": "data-pipeline-agent",
  "reason": "decommissioned"
}

POST /v1/agents/{{AGENT_ID}}/revoke
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "reason": "decommissioned"
}

Delete

Delete a revoked agent to remove it and all of its data. Deletion works only on a revoked agent and rejects an agent in any other state.

dome agents delete data-pipeline-agent --reason "offboarded"

dome agents delete data-pipeline-agent --cascade

{
  "agent_id": "data-pipeline-agent",
  "reason": "offboarded",
  "cascade": false
}

DELETE /v1/agents/{{AGENT_ID}}?workspace_id={{WORKSPACE_ID}}&reason=offboarded

Manage API keys

An API key is the credential the agent runtime presents to Dome. An agent can hold several keys, so you can rotate a credential or keep one key per environment. Keys scope to the agent's tenant and workspace.

Create key

Create a key to receive the one-time token, selected gateway_id, and complete gateway_endpoints. Supply a Gateway when the agent can access more than one.

dome agents create-key data-pipeline-agent --name "default" --gateway "{{GATEWAY_ID}}"

{
  "agent": "data-pipeline-agent",
  "name": "default",
  "gateway_id": "{{GATEWAY_ID}}"
}

POST /v1/agents/{{AGENT_ID}}/keys
Content-Type: application/json

{
  "name": "default",
  "workspace_id": "{{WORKSPACE_ID}}",
  "gateway_id": "{{GATEWAY_ID}}"
}

Create an API key named "default" for agent "data-pipeline-agent" using Gateway "{{GATEWAY_ID}}".

{
  "token": "dome_…",
  "key": { "id": "k_…", "name": "default", "createdAt": "…" },
  "gateway_id": "{{GATEWAY_ID}}",
  "gateway_endpoints": {
    "gateway_id": "{{GATEWAY_ID}}",
    "gateway_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}",
    "mcp_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/mcp",
    "openai_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}/v1",
    "anthropic_base_url": "https://gateway.example.dome.dev/gateways/{{GATEWAY_ID}}"
  }
}

A separate key for each runtime or environment lets you revoke one without disrupting the others.

List keys

Retrieve an agent's active keys with their names and creation times. A list never returns tokens, because Dome returns a token only when you create or rotate a key.

dome agents list-keys data-pipeline-agent

{
  "agent": "data-pipeline-agent"
}

GET /v1/agents/{{AGENT_ID}}/keys?workspace_id={{WORKSPACE_ID}}

List the API keys for agent "data-pipeline-agent".

Rotate key

Rotate a key to revoke the old secret and issue a new one under the same name. Dome returns the new token and the gateway endpoint. The old secret stops authenticating as soon as you rotate, so deploy the new token promptly.

dome agents rotate-key data-pipeline-agent production

{
  "agent": "data-pipeline-agent",
  "key_name": "production"
}

POST /v1/agents/{{AGENT_ID}}/keys/production/rotate
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}"
}

Rotate the "production" API key for "data-pipeline-agent".

Revoke key

Revoke a key to retire it without affecting the agent's other keys. A revoked key stops authenticating immediately, so confirm the runtime holds a working key before you revoke this one.

dome agents revoke-key data-pipeline-agent production

{
  "agent": "data-pipeline-agent",
  "key_name": "production"
}

DELETE /v1/agents/{{AGENT_ID}}/keys/production?workspace_id={{WORKSPACE_ID}}

Revoke the "production" API key for agent "data-pipeline-agent".

Manage agent-scoped rules

Agent-scope rules apply to one agent, for conditions allowed resources cannot express. They evaluate in addition to organization, tenant, and workspace rules, and a deny at the workspace scope overrides an allow at the agent scope. Refer to Authorize Access for creating rules, inherited scopes, and deployment.

Assign rules

Assign rule files to the agent scope, where the gateway evaluates them alongside the rules the agent inherits from higher scopes.

dome agents assign-policy data-pipeline-agent agent-policy.cedar

{
  "agent_id": "data-pipeline-agent",
  "files": [
    {
      "name": "agent-policy.cedar",
      "content": "permit(principal, action == Dome::Action::\"mcp:call\", resource == Dome::MCPTool::\"github/list-issues\");"
    }
  ]
}

Assign the rules in agent-policy.cedar to agent "data-pipeline-agent".

View rules

Retrieve the rules assigned at the agent scope. The result excludes the organization, tenant, and workspace rules the agent also inherits.

dome agents get-policies data-pipeline-agent

{
  "agent_id": "data-pipeline-agent"
}

Show the rules currently assigned to agent "data-pipeline-agent".

Next steps

• Delegated agents when access must depend on the person
• Tools and Models an agent can call
• Gateways for membership and grants
• Develop to authenticate and route runtime traffic
• Agent Lifecycle concept for states and cascades