> ## Documentation Index > Fetch the complete documentation index at: https://docs.domesystems.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agent Registry > Register agents, manage lifecycle states, and control API keys 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` ```json title="Example tool call" theme={"system"} { "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 == ""` | | `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` ```json title="Example tool call" theme={"system"} { "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` ```json title="Example tool call" theme={"system"} { "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` ```json title="Example tool call" theme={"system"} { "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: * [Register Agents](/connect/agents) * [Agent Lifecycle](/concepts/agents/agent-lifecycle) concept * [Rules](/reference/mcp/rules)