Agents

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:

Register the agent to create the identity.
Get the agent to confirm the record and note the workspace gateway endpoint.
Allow the resources it needs.
Create an API key for the runtime.
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. Dome derives the agent’s capabilities (the strings its rules can test) from the same selections:

You allow	Capabilities Dome derives
Model pool or model	`llm:invoke`
Tool	`mcp:call`, `mcp:discover`
Gateway	`llm:invoke`, `mcp:call`, `mcp:discover`

You set a capability yourself only when one of your rules tests a string Dome would not derive, such as read-data. 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.

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.

Default roles	Permission	Grants
All workspace roles	`agent.view`	Get and list agents and keys
`admin`, `operator`, `developer`	`agent.register`	Register and update agents
`admin`, `operator`, `security`, `developer`	`agent.suspend`	Suspend and reactivate agents
`admin`, `operator`, `developer`	`agent.revoke`	Revoke agents
`admin`, `operator`	`agent.delete`	Delete agents
`admin`, `operator`, `developer`	`agentkey.manage`	Create, rotate, or revoke agent keys
`admin`, `operator`, `security`	`rules.deploy`	Change allowed resources or end-user identity (with `agent.register`)
All workspace roles	`rules.view`	View generated rule bundles

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, and a parent in the same call.

Requires agent.register, plus rules.deploy if you set allowed resources or end-user identity in the same call.

CLI
MCP
API
Agent

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

Add --parent-id to place the agent in a hierarchy, --metadata key=value for your own labels, and --if-not-exists to return the existing agent instead of failing when the name is taken.

Reference: dome agents register

Tool: dome_agents_register

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

Reference: dome_agents_register

POST /dome.agent.v1.AgentRegistry/RegisterAgent HTTP/1.1
Content-Type: application/json

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

Reference: RegisterAgent

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

Response

{
  "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.

agent.yaml

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

dome agents register --file agent.yaml

Reference: dome agents register --file

Update agent

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

Requires agent.register.

CLI
MCP
API
Agent

dome agents update data-pipeline-agent \
  --metadata environment=production

Reference: dome agents update

Tool: dome_agents_update

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

Reference: dome_agents_update

POST /dome.agent.v1.AgentRegistry/UpdateAgent
Content-Type: application/json

{
  "agent_id": "{{AGENT_ID}}",
  "workspace_id": "{{WORKSPACE_ID}}",
  "capabilities": ["read-data", "write-reports"]
}

Reference: UpdateAgent

Update an agent

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.

Requires agent.register and rules.deploy, because every change regenerates the agent’s rule bundle.

CLI
MCP
API
Agent

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

Tool names take the form <connection-name>/<tool-name>. When a pool is not appropriate, --model allows a specific model connection, and --capabilities sets custom capability strings.

Reference: dome agents update

Tool: dome_agents_update

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

Reference: dome_agents_update

POST /dome.agent.v1.AgentRegistry/UpdateAgent
Content-Type: application/json

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

Reference: UpdateAgent

Change allowed resources

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. In the dashboard, the agent detail page hides the edit controls on Capabilities and Delegation when the caller lacks rules.deploy, and the edit dialog shows a banner explaining the limit.

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.

Requires agent.register and rules.deploy.

Setting	Flag
Verification method	`--actas-method` (`none`, `oidc`, `hmac`, or `bound`)
Mandatory claim	`--actas-required`
Workspace provider	`--actas-provider`
Inline OIDC or HMAC credentials	`--actas-oidc-url`, `--actas-hmac-secret`
Acceptable identities	`--actas-allowed-group`, `--actas-allowed-email`, `--actas-allowed-subject`

CLI
MCP
API
Agent

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

Reference: dome agents update

Tool: dome_agents_update

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

Reference: dome_agents_update

POST /dome.agent.v1.AgentRegistry/UpdateAgent
Content-Type: application/json

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

Reference: UpdateAgent

Require verified end-user identity

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.

Requires agent.view.

CLI
MCP
API
Agent

dome agents get data-pipeline-agent

Reference: dome agents get

Tool: dome_agents_get

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

Reference: dome_agents_get

POST /dome.agent.v1.AgentRegistry/GetAgent
Content-Type: application/json

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

Reference: GetAgent

Get an agent

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.

Response

{
  "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.

Requires agent.view.

CLI
MCP
API
Agent

dome agents list --status active

A list returns 100 agents unless --limit says otherwise.

Reference: dome agents list

Tool: dome_agents_list

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

offset pages through results beyond the limit.

Reference: dome_agents_list

POST /dome.agent.v1.AgentRegistry/ListAgents
Content-Type: application/json

{
  "workspace_id": "{{WORKSPACE_ID}}",
  "status": "active"
}

Reference: ListAgents

List agents

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.

State	Traffic	How it leaves this state
`provisioned`	Allowed	Becomes `active` automatically on the first gateway request
`active`	Allowed	An operator suspends or revokes it
`suspended`	Denied	An operator reactivates or revokes it
`revoked`	Denied	Terminal. You can delete the record, but you cannot undo revocation

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

Operation	Reach
Suspend	The agent alone, or the agent plus its active descendants when you pass `--cascade`
Reactivate	The agent alone. Undoing a cascaded suspension takes one call per agent
Revoke	The agent and every descendant, always, depth-first, any state
Delete	The agent alone, or the agent plus its descendants when you request a cascade

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.

Requires agent.suspend.

CLI
MCP
API
Agent

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

Reference: dome agents suspend

Tool: dome_agents_suspend

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

Reference: dome_agents_suspend

POST /dome.agent.v1.AgentRegistry/SuspendAgent
Content-Type: application/json

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

Reference: SuspendAgent

Suspend an agent

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.

Requires agent.suspend.

CLI
MCP
API
Agent

dome agents reactivate data-pipeline-agent

Reference: dome agents reactivate

Tool: dome_agents_reactivate

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

Reference: dome_agents_reactivate

POST /dome.agent.v1.AgentRegistry/ReactivateAgent
Content-Type: application/json

{
  "agent_id": "{{AGENT_ID}}",
  "workspace_id": "{{WORKSPACE_ID}}"
}

Reference: ReactivateAgent

Reactivate an agent

Reactivate agent "data-pipeline-agent".

Revoke

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

Requires agent.revoke.

Revocation cannot be reversed and always cascades to every descendant agent.

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

Reference: dome agents revoke

Tool: dome_agents_revoke

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

Reference: dome_agents_revoke

POST /dome.agent.v1.AgentRegistry/RevokeAgent
Content-Type: application/json

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

Reference: RevokeAgent

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.

Requires agent.delete.

Deletion removes the agent record and its data irreversibly, including its keys. Revoke instead when you need the record retained.

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

Deletion covers one agent, and it fails when that agent still has descendants. Adding --cascade deletes the agent and its descendants in one call, deepest first, and every descendant must already be revoked.

dome agents delete data-pipeline-agent --cascade

Reference: dome agents delete

Tool: dome_agents_delete

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

Reference: dome_agents_delete

POST /dome.agent.v1.AgentRegistry/DeleteAgent
Content-Type: application/json

{
  "agent_id": "{{AGENT_ID}}",
  "workspace_id": "{{WORKSPACE_ID}}",
  "reason": "offboarded"
}

Reference: DeleteAgent

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.

Requires agentkey.manage to create, rotate, or revoke a key, and agent.view to list them.

The token is returned once, when you create or rotate a key. Store it immediately, because it cannot be retrieved again.

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.

CLI
MCP
API
Agent

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

Reference: dome agents create-key

Tool: dome_agents_create_key

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

Reference: dome_agents_create_key

POST /dome.agent.v1.AgentRegistry/CreateAgentKey
Content-Type: application/json

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

Reference: CreateAgentKey

Create an API key

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

Response

{
  "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.

CLI
MCP
API
Agent

dome agents list-keys data-pipeline-agent

Reference: dome agents list-keys

Tool: dome_agents_list_keys

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

Reference: dome_agents_list_keys

POST /dome.agent.v1.AgentRegistry/ListAgentKeys
Content-Type: application/json

{
  "agent_id": "{{AGENT_ID}}",
  "workspace_id": "{{WORKSPACE_ID}}"
}

Reference: ListAgentKeys

List an agent's API keys

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.

CLI
MCP
API
Agent

dome agents rotate-key data-pipeline-agent production

Reference: dome agents rotate-key

Tool: dome_agents_rotate_key

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

Reference: dome_agents_rotate_key

POST /dome.agent.v1.AgentRegistry/RotateAgentKey
Content-Type: application/json

{
  "agent_id": "{{AGENT_ID}}",
  "workspace_id": "{{WORKSPACE_ID}}",
  "key_name": "production"
}

Reference: RotateAgentKey

Rotate an agent key

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.

CLI
MCP
API
Agent

dome agents revoke-key data-pipeline-agent production

Reference: dome agents revoke-key

Tool: dome_agents_revoke_key

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

Reference: dome_agents_revoke_key

POST /dome.agent.v1.AgentRegistry/RevokeAgentKey
Content-Type: application/json

{
  "agent_id": "{{AGENT_ID}}",
  "workspace_id": "{{WORKSPACE_ID}}",
  "key_name": "production"
}

Reference: RevokeAgentKey

Revoke an agent key

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.

Requires rules.deploy.

CLI
MCP
Agent

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

Reference: dome agents assign-policy

Tool: dome_agents_assign_policy

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

Reference: dome_agents_assign_policy

Assign agent-scoped rules

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.

Requires rules.view.

CLI
MCP
Agent

dome agents get-policies data-pipeline-agent

Reference: dome agents get-policies

Tool: dome_agents_get_policies

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

Reference: dome_agents_get_policies

View agent-scoped rules

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

Get started

Core concepts

Connect

Govern

Operate

Manage

Develop

Reference

Overview

Allowed resources

Delegated identity

Hierarchy

Requirements

Permissions

Register agent

Register from a file

Update agent

Change allowed resources

Change end-user identity

Get agent

List agents

Manage lifecycle

Suspend

Reactivate

Revoke

Delete

Manage API keys

Create key

List keys

Rotate key

Revoke key

Manage agent-scoped rules

Assign rules

View rules

Next steps

​Overview

​Allowed resources

​Delegated identity

​Hierarchy

​Requirements

​Permissions

​Register agent

​Register from a file

​Update agent

​Change allowed resources

​Change end-user identity

​Get agent

​List agents

​Manage lifecycle

​Suspend

​Reactivate

​Revoke

​Delete

​Manage API keys

​Create key

​List keys

​Rotate key

​Revoke key

​Manage agent-scoped rules

​Assign rules

​View rules

​Next steps

Overview

Allowed resources

Delegated identity

Hierarchy

Requirements

Permissions

Register agent

Register from a file

Update agent

Change allowed resources

Change end-user identity

Get agent

List agents

Manage lifecycle

Suspend

Reactivate

Revoke

Delete

Manage API keys

Create key

List keys

Rotate key

Revoke key

Manage agent-scoped rules

Assign rules

View rules

Next steps