Agent Registry

Agent registry tools manage the full agent lifecycle — from registration through suspension and revocation — plus API key management for agent authentication. These 13 tools require workspace context and appropriate permissions.

Agents List

dome_agents_list List registered agents. Returns agent ID, name, status, and capabilities.

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `active`, `suspended`, `provisioned`, `revoked`
`workspace_id`	string	No	Filter by workspace ID (defaults to active workspace)
`limit`	number	No	Maximum results (default: 100)
`offset`	number	No	Pagination offset

Permission: agent.view

Example tool call

{
  "name": "dome_agents_list",
  "arguments": {
    "status": "active",
    "limit": 25
  }
}

Agents Get

dome_agents_get Get detailed information about a specific agent by ID.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID (UUID)
`gateway_id`	string	No	Gateway ID used to return complete endpoints; required when the agent can access more than one Gateway

Permission: agent.view

Agents Register

dome_agents_register Register a new AI agent on the platform. After registration, create an API key with dome_agents_create_key.

Parameter	Type	Required	Description
`name`	string	Yes	Agent name (unique within workspace)
`capabilities`	array	No	Custom capability strings. System capabilities (`llm:invoke`, `mcp:call`, `mcp:discover`) are derived automatically from the selections below
`parent_id`	string	No	Parent agent ID for hierarchical agents
`workspace_id`	string	No	Workspace to register in (defaults to active workspace)
`metadata`	object	No	Key-value metadata
`allowed_pool_names`	array	No	LLM pools the agent may route to. Emits a `permit` against `Dome::LLMModel` matched via `resource.pool == "<name>"`
`allowed_direct_model_names`	array	No	LLM model connections the agent may invoke directly (advanced). Emits a `permit` against `Dome::LLMModel`
`allowed_tools`	array	No	MCP tools the agent may call, each as `connection/tool`. Emits `mcp:call` and `mcp:discover` permits against `Dome::MCPTool`
`allowed_gateway_ids`	array	No	Gateway IDs the agent may reach. Emits per-Gateway permit rules
`actas_allowed_groups`	array	No	Groups the verified act-as identity may belong to. Emits a `forbid` unless the verified group matches
`actas_allowed_emails`	array	No	Emails the agent may act on behalf of. Emits a `forbid` unless the verified email matches
`actas_allowed_subjects`	array	No	Subjects the agent may act on behalf of. Emits a `forbid` unless the verified subject matches
`actas_method`	string	No	Act-as verification method: `none`, `oidc`, `hmac`
`actas_required`	bool	No	Require act-as header on every request
`actas_provider_id`	string	No	Workspace verification provider ID
`actas_oidc_url`	string	No	Inline OIDC discovery URL
`actas_hmac_secret`	string	No	Inline HMAC shared secret
`actas_config_name`	string	No	Label for agent-specific verification config

Permission: agent.register

Example tool call

{
  "name": "dome_agents_register",
  "arguments": {
    "name": "code-reviewer",
    "capabilities": ["code-review", "pr-comments"],
    "metadata": {
      "team": "platform",
      "owner": "infra@example.com"
    }
  }
}

Agents Update

dome_agents_update Update an existing agent’s capabilities, metadata, or act-as verification config.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID or name
`capabilities`	array	No	Updated custom capability list
`metadata`	object	No	Updated key-value metadata
`allowed_pool_names`	array	No	Replace the agent’s allowed LLM pool list
`allowed_direct_model_names`	array	No	Replace the agent’s allowed direct-model list
`allowed_tools`	array	No	Replace the agent’s allowed MCP tool list, each as `connection/tool`
`allowed_gateway_ids`	array	No	Replace the agent’s allowed Gateway ID list
`actas_allowed_groups`	array	No	Replace the agent’s act-as allowed-groups list
`actas_allowed_emails`	array	No	Replace the agent’s act-as allowed-emails list
`actas_allowed_subjects`	array	No	Replace the agent’s act-as allowed-subjects list
`actas_method`	string	No	Act-as verification method: `none`, `oidc`, `hmac`
`actas_required`	bool	No	Require act-as header on every request
`actas_provider_id`	string	No	Workspace verification provider ID
`actas_oidc_url`	string	No	Inline OIDC discovery URL
`actas_hmac_secret`	string	No	Inline HMAC shared secret
`actas_config_name`	string	No	Label for agent-specific verification config

Permission: agent.register. Changing any pool, model, tool, or actas_allowed_* field regenerates the agent’s rule bundle and additionally requires rules.deploy.

Agents Suspend

dome_agents_suspend Suspend an active agent, preventing it from making requests. Optionally cascade to child agents.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID (UUID)
`reason`	string	No	Reason for suspension
`cascade`	bool	No	Also suspend child agents (default: `false`)

Permission: agent.suspend

Example tool call

{
  "name": "dome_agents_suspend",
  "arguments": {
    "agent_id": "code-reviewer",
    "reason": "Investigating anomalous behavior",
    "cascade": true
  }
}

Agents Reactivate

dome_agents_reactivate Reactivate a previously suspended agent.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID (UUID)

Permission: agent.suspend

Agents Revoke

dome_agents_revoke Permanently revoke an agent. This cannot be undone. Marked destructive.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID (UUID)
`reason`	string	No	Reason for revocation

Permission: agent.revoke

Revocation is permanent and cannot be undone.

Agents Delete

dome_agents_delete Permanently delete a revoked agent and all its data. Agent must already be in the revoked state. Marked destructive.

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID (UUID)
`reason`	string	No	Reason for deletion
`cascade`	bool	No	Also delete descendant agents

Permission: agent.delete

Hard-delete removes all agent data irreversibly. The agent must be revoked first.

Tools List

dome_tools_list List registered agents and their tools/capabilities in the active workspace. Only returns agents in active or provisioned status.

Parameter	Type	Required	Description
—	—	—	No parameters

Permission: agent.view

Agent API Keys

Agents Create Key

dome_agents_create_key Create a new API key for an agent. Returns the token, selected Gateway ID, and complete Gateway endpoints once — save the token immediately.

Parameter	Type	Required	Description
`agent`	string	Yes	Agent name
`name`	string	Yes	Key name (unique per agent)
`gateway_id`	string	No	Gateway ID used to return complete endpoints; required when the agent can access more than one Gateway

Permission: agentkey.manage

Example tool call

{
  "name": "dome_agents_create_key",
  "arguments": {
    "agent": "code-reviewer",
    "name": "production-v1",
    "gateway_id": "{{GATEWAY_ID}}"
  }
}

Store the returned key secret securely. It cannot be retrieved after creation — only rotated or revoked.

Agents List Keys

dome_agents_list_keys List active API keys for an agent.

Parameter	Type	Required	Description
`agent`	string	Yes	Agent name

Permission: agent.view

Agents Rotate Key

dome_agents_rotate_key Rotate an agent’s API key — revokes the old secret and issues a new one with the same name. Returns the new token once.

Parameter	Type	Required	Description
`agent`	string	Yes	Agent name
`key_name`	string	Yes	Name of the key to rotate
`gateway_id`	string	No	Gateway ID used to return complete endpoints; required when the agent can access more than one Gateway

Permission: agentkey.manage

Agents Revoke Key

dome_agents_revoke_key Revoke an agent’s API key. The key is no longer usable for authentication.

Parameter	Type	Required	Description
`agent`	string	Yes	Agent name
`key_name`	string	Yes	Name of the key to revoke

Permission: agentkey.manage

Next steps

Full agent workflows live under Connect. Lifecycle and Rules stay one hop away:

​Agents List

​Agents Get

​Agents Register

​Agents Update

​Agents Suspend

​Agents Reactivate

​Agents Revoke

​Agents Delete

​Tools List

​Agent API Keys

​Agents Create Key

​Agents List Keys

​Agents Rotate Key

​Agents Revoke Key

​Next steps

Agents List

Agents Get

Agents Register

Agents Update

Agents Suspend

Agents Reactivate

Agents Revoke

Agents Delete

Tools List

Agent API Keys

Agents Create Key

Agents List Keys

Agents Rotate Key

Agents Revoke Key

Next steps