Agents

This page lists the fields and state transitions of an Agent record. An Agent is the durable identity Dome authorizes, audits, and attaches credentials and grants to.

Refer to Agents for the identity model. Register and manage Agents on Connect agents.

Identity

Field	Type	Description
`id`	UUID	Stable Agent identifier and the identifier used by `Dome::Agent` in Rules
`name`	string	Display name, unique within the workspace
`tenant_id`	UUID	Tenant that owns the Agent
`workspace_id`	UUID	Workspace that owns the Agent and its generated Rules
`parent_id`	UUID	Optional parent Agent; fixed after registration
`metadata`	map of strings	Customer-defined attributes exposed to Rules as `principal.metadata`
`created_at`	timestamp	Registration time
`updated_at`	timestamp	Last record update
`last_seen_at`	timestamp	Most recent authenticated activity

An Agent hierarchy may be at most 10 levels deep. Parent and child must belong to the same tenant. Hierarchy does not grant access: each Agent keeps its own credentials, grants, and effective Rules.

Lifecycle

Status	Meaning	Allowed transition
`provisioned`	Identity exists but has not yet authenticated	Becomes `active` after successful use
`active`	May authenticate and make governed calls	Suspend or revoke
`suspended`	Temporarily blocked from authenticating	Reactivate or revoke
`revoked`	Permanently blocked	Delete

Suspension can cascade to descendants. Revocation always cascades. Deletion is a hard delete and requires the Agent to be revoked first.

Resource grants

The Agent record exposes grants in two forms:

View	Fields	Behavior
Name view	`allowed_pool_names`, `allowed_direct_model_names`, `allowed_tools`	Authoring input and display projection; reflects current resource names
Canonical view	`allowed_pool_ids`, `allowed_direct_model_ids`, `allowed_tool_ids`	Rename-safe identifiers Dome stores and enforces
Gateway access	`allowed_gateway_ids`	Gateway UUIDs whose endpoints the Agent may use

Tool entries take the form <connection>/<tool>. Canonical tool entries keep the leaf tool name but replace the connection name with its UUID.

Writing these fields generates an Agent-scoped Rule bundle. Pool and model grants permit model actions; tool grants permit mcp:call and mcp:discover; Gateway grants permit the actions reachable through that Gateway. Workspace Rules and explicit forbids still apply.

Delegated identity

The actas_* fields define how Dome verifies the person an Agent acts for and which verified people it may represent.

Field	Description
`actas_method`	Verification method: `none`, `oidc`, `hmac`, or `bound`
`actas_required`	Whether every request must include verified Act-As identity
`actas_verification_provider_id`	Shared verification provider used by this Agent
`actas_oidc_discovery_url`	Inline OIDC issuer material
`actas_config_name`	Label for inline Agent-specific configuration
`actas_allowed_groups`	Verified groups the Agent may represent
`actas_allowed_emails`	Verified email addresses the Agent may represent
`actas_allowed_subjects`	Verified subjects the Agent may represent

When every allow-list is empty, any identity accepted by the effective workspace Act-As policy may be represented. Populating any list generates a forbid-unless Rule against the verified claims.

interactive_access permits authorized humans to ride the Agent through Dome's OAuth flow. It requires at least one allowed email or subject. Groups cannot qualify an interactive login.

Device-bound Agents expose pop_required, actas_bound_identity, and device as read-only fields set by enrollment. They cannot also use interactive access.

Credentials

Credentials are separate records from the Agent identity. Creating an Agent does not issue a key.

Property	Behavior
Agent API key	Long-lived secret exchanged for short-lived Agent access tokens
`token_ttl`	Lifetime of those access tokens; defaults to `10m`, accepted range `1m`–`24h`
Rotation	Revokes the old key and returns a new secret
Revocation	Permanently invalidates one key without changing the Agent's grants

Key secrets are returned once. Dome stores their verification material, not a retrievable plaintext value.