Agent Blueprints

An Agent Blueprint is a portable, reviewable declaration of a governed agent. It keeps the agent's identity, access, Rules, checks, and optional local runtime beside the code that carries the agent.

A project can also include a Workspace Blueprint. The two document kinds have different ownership:

• Agent Blueprint (dome-agent.yaml) declares one agent: its name and metadata, Gateway and resource dependencies, entitlements, act-as requirements, Rules, checks, and optional runtime.
• Workspace Blueprint (dome-workspace.yaml) declares shared substrate the project needs: Gateways, MCP server connections, model connections, model pools, and verification providers.

The workspace document runs first because Agent Blueprint entitlements resolve against resources the workspace document may create.

Choose the document that owns the change

Put agent-specific authority in dome-agent.yaml. This includes which Gateway the agent may enter, which tools and models it may use, whether its entitlement lists are exclusive, and the Cedar bundle attached to that agent.

Put shared resource existence and attachment in dome-workspace.yaml. Workspace reconciliation is additive: it creates a missing resource or attachment, but does not rewrite or delete an existing shared resource. Use the imperative dome gateway, dome tool, dome model, and dome verification-providers commands for operational configuration such as routing strategy, failover, caching, quotas, match_when, OAuth, workload identity, updates, and deletion.

Use imperative agent and Rules commands when a change should not become the Agent Blueprint's desired state. A declared rules block is the complete user-authored bundle for that agent; applying it replaces prior user-authored files while preserving integration-managed tool-*.cedar files.

Project files

A single-agent project can use the default names:

dome/
├── dome-workspace.yaml
├── dome-workspace.lock.json
├── dome-workspace.bindings.json
├── dome-agent.yaml
├── dome-agent.lock.json
└── dome-agent.bindings.json

For several agents, add dome-agents.yaml:

schema_version: 1
agents:
  - path: agents/chess-coach/dome-agent.yaml
  - path: agents/opponent-stockfish/dome-agent.yaml

The manifest only lists Agent Blueprint paths. Paths are relative to the manifest, unique, confined to the project, and processed in declaration order. Each listed agent keeps its lockfile and bindings beside its own source. Without a manifest, commands use the single dome-agent.yaml.

Source

Source YAML is the file people edit. It contains names and local aliases, never resolved workspace UUIDs or credential values. The parser is strict: unknown or duplicate fields, YAML aliases, custom tags, nulls, secrets, and workspace UUIDs are rejected.

Environment-backed fields store variable names rather than values. For example, a tool connection can use url_env, and connection authentication can use auth.secret_env. The CLI resolves those variables when assessment or creation needs them; they are not written into generated artifacts.

Lockfile

dome blueprint compile turns source into a canonical, workspace-independent Revision:

• dome-agent.lock.json for an Agent Blueprint
• dome-workspace.lock.json for a Workspace Blueprint

Compilation is local. It does not select a workspace or call Dome. It canonicalizes the document and referenced Cedar, then computes a deterministic digest. Commit the lockfile so review and CI can detect a source change that was not compiled.

Bindings

A bindings file records which workspace resources the Blueprint's names resolved to. It is a rebinding guard, not desired state:

• dome-agent.bindings.json
• dome-workspace.bindings.json

Bindings are specific to one Revision and workspace. If the same name later resolves to a different resource, assessment reports the conflict instead of silently adopting it. Use bind --refresh only after reviewing and accepting the new resolution.

Lifecycle

Use the lifecycle in this order:

1. Initialize or adopt. dome blueprint init creates an Agent Blueprint scaffold. dome blueprint workspace init creates a Workspace Blueprint scaffold. dome blueprint adopt creates an Agent Blueprint from an existing agent.
2. Validate and format locally. validate and fmt read local files only.
3. Compile locally. compile writes deterministic lockfiles. compile --check verifies committed locks without writing.
4. Assess against a workspace. assess resolves names, checks optional bindings and held permissions, validates projected Rules, and returns constraints, checks, operations, and blockers. It never mutates.
5. Apply. apply assesses before mutation, performs authorized stages, and reassesses. There is no cross-endpoint transaction or rollback; partial progress and any handoff remain visible in the final assessment.
6. Check readiness. status reports source/lock freshness, live reconciliation, bindings, and agent runtime preflight. status --check is suitable for CI.
7. Run when appropriate. run starts one Agent Blueprint runtime. up reconciles the workspace and agents first, then can provision a credential and start exactly one runnable agent. Use up --apply-only for multi-agent or externally hosted applications.

The unscoped shared verbs—validate, fmt, compile, diff, bind, assess, apply, and status—fan out over every present document. They process the Workspace Blueprint first, then Agent Blueprints in manifest order. Use dome blueprint agent ... or dome blueprint workspace ... to operate on one document kind.

Local work and workspace calls

The distinction is important:

• init, validate, fmt, compile, and source-to-lock diff are local file operations.
• adopt, bind, assess, apply, status, run, and up use a workspace context because they read or change live resources. run also performs live assessment before starting the child.

bind, assess, apply, run, and up accept repeatable --env-file. Earlier explicit files win over later files, and the process environment wins over every file. With no flag, the CLI searches from each source YAML directory upward to the Git repository root for the nearest .env; no .env is required.

Credentials never enter source, lockfiles, assessments, or bindings. When run or up provisions DOME_AGENT_API_KEY, the value is a long-lived credential envelope that the child exchanges through DOME_API_URL. Do not send that envelope directly to a Gateway as a bearer token.

Next steps

• dome blueprint CLI reference
• Blueprint MCP tools
• Scheduled agent tutorial
• Interactive app tutorial