Agent Blueprints

One reviewed, versioned declaration that installs a whole governed agent (definition, surface, connections, PermissionAssignments, budgets, and automations) from a single package.

Blueprint application is migration-fenced while its inline Agent flow moves from AgentRelease/AgentDeployment to automatic Agent Versions and CMA Session admission. This page is architectural context, not an executable Agent guide.

Standing up a complete agent by hand means coordinating a dozen resources: an Agent version, a harness and model, a SandboxProfile, an installation on a surface, a service principal, connections, PermissionAssignments and ActionApprovals, budgets, automations, memory, and acceptance tests. An AgentBlueprint packages that intent as one reviewed, versioned declaration whose validate, plan, apply, promotion, rollback, and uninstall contracts remain subject to live qualification.

“Blueprint” on this page always means an AgentBlueprint. It is not an Automation Blueprint, which is a console prefill for one Automation and installs nothing.

An AgentBlueprint is a package, never runtime authority. Installing it compiles into the ordinary public contracts of the resources it names. It does not become a second control plane, and the installed resources keep one lifecycle. A persisted installation record tracks what was reconciled; it is read for reproducibility and drift, never on the run path.

The declared harness is resolved as an exact, reused Workspace HarnessProfile. That makes the profile available to an ordinary AgentDefinition use_harness PermissionAssignment in the same package; apply never creates, adopts, or bypasses conformance for a harness profile.

The Checkfu CLI has no self-service public installation channel during private alpha. CLI examples on this page assume access through an explicitly authorized alpha arrangement. See CLI access in private alpha for the source-checkout and HTTP alternatives.

The source posture is alpha / hosted, but the live capability status must clear the Blueprint lifecycle qualification prerequisite before publication, promotion, apply, rollback, or uninstall is executable. Local validation does not clear that release gate.

The package

A Blueprint directory has a closed manifest plus an optional inline agent and its scenarios:

checkfu.json          # the manifest (schema_version 3)
agent/                # optional D19 definition (instructions.md, plus optional manifest.json, tools/, skills/)
scenarios/            # acceptance scenarios that travel with the package

agent/instructions.md is the only entry an inline agent needs. The manifest already declares the harness, model routing profile, and environment, so the inline definition inherits them: a page of markdown is the whole agent, with no agent/manifest.json to keep in sync. Add one when the agent needs tools, skills, or a policy the markdown floor does not carry.

The manifest declares every part of the agent by logical name, so one version installs unchanged across dev, staging, and production. Each declared resource carries an ownership disposition:

create

Blueprint-managed. Apply creates it and reconciles it toward the declared shape on upgrade.

reference

Must already exist in the Workspace. Apply resolves and binds it, but never creates or mutates it.

adopt

Bind one existing resource as if created, and manage it thereafter.

Apply always records which resources it created versus reused, so uninstall and drift can tell them apart.

Schema v3 uses agent_deployment_revision_selection wherever reusable configuration selects what a referenced Agent or Automation target will run. current resolves the AgentDeployment’s current revision once for each admitted Session. pinned selects one exact deployment revision. Neither changes an existing Session after admission:

A referenced agent value:

source: reference
name: claims-agent
agent_deployment_revision_selection:
  type: current

An Automation target value:

agent: claims-agent
agent_deployment_revision_selection:
  type: pinned
  revision_number: 7

Surface identity is explicit. The schema v3 compatibility form { "kind", "selector" } resolves as reference: it names an existing provider scope and never carries ownership. An exact scope declaration names a blueprint-local logical name and the exact provider external_id separately. A created or adopted scope declares the same visibility, membership, and inheritance fields as the ordinary SurfaceScope API, and every non-root scope names its logical parent. A named installation is placed only after its Agent, ExternalInstallation, scopes, acting Principal, runtime bindings, and default governance resolve. The placement’s identity posture is declared on the installation entry: omitting identity_posture means autonomous, acting as the manifest’s service principal, while identity_posture: "delegated" acts as a person named by acted_as — a portable logical reference into the manifest’s people list, never a raw Workspace Principal id.

installation:
  name: claims-placement
  disposition: create
  identity_posture: delegated
  acted_as: owner
people:
  - name: owner
    kind: person
    disposition: reference

The active API path requires an existing ExternalInstallation. Pairing a new installation remains its own short-lived proof operation. Under that installation, exact create declarations are recoverable: parents converge before children, and the AgentInstallation is created last. A referenced Agent preserves its declared current-or-pinned AgentDeployment revision selection. An inline directory is published through the ordinary Agent API; apply ensures its Workspace AgentDeployment and pins the placement to the exact deployment revision produced by that apply. An inline upgrade publishes a new AgentRelease and deployment revision, then repins the placement to that new exact revision. Reapply reconciles mutable scope governance and nonterminal disabled state through the ordinary SurfaceScope API. Archive is terminal operator authority and blocks reapply; provider identity, kind, installation, and parent remain immutable.

Secrets are requirements, never values

A Blueprint declares the credentials it needs (a GitHub token bound to a connection, a model provider key, or a webhook Automation signing value) but never their values. The package and every plan, installation, and apply response are secret-free. Most values travel through the bound resource’s own write-only operation. A webhook Automation is the narrow exception needed for atomic creation and managed signing-value rotation: apply accepts webhook_secret_inputs, a write-only sidecar keyed by an Automation-bound secret requirement. Reconciliation compares that value only against the exact stored Automation version, consumes it through the ordinary create or patch operation, and never copies it into package, plan, installation, audit payload, or response data. An unchanged reapply may omit the sidecar; a changed webhook declaration must supply its exact named requirement before any installation or Automation mutation. A plan lists the missing-credential steps until each exact handoff is satisfied.

The bundled proactive-governed-review example composes a fail-closed DeliveryScreen, signed webhook predicates and admission Check, a bounded Outcome, passive FlowReview, explicit model routing profile, service identity, governance, Budget, and managed sandbox into ordinary authorities. It does not introduce a workflow aggregate.

Connector packages

A Blueprint reaches external providers through Connector packages: versioned, provider-neutral declarations of a provider’s least-privilege scope catalog, the platform capabilities it needs, and the conformance scenarios every implementation must pass. When a Blueprint requests a connection, validation resolves it against the registry: an unregistered provider, a scope outside the provider’s catalog, a mismatched pinned version, or a deprecated package each surfaces as a typed finding, so a package can never quietly request more than a provider offers. Slack, GitHub, generic MCP OAuth, and generic bearer HTTP are registered today.

The lifecycle

1. Validate

   Check the package structure and semantics locally, with no keys, and preview the resolved access.

2. Plan

   Resolve the version against a target Workspace and see the exact ordered actions (create, reuse, update, publish, replace, or blocked) plus the effective release hash, privilege delta, budget impact, and any missing credentials. Planning never changes anything.

3. Apply

   Reconcile idempotently and resumably. A partial failure resumes to one correct installation; apply never deletes a resource it did not create.

4. Promote and roll back

   Promotion is currently fail-closed until Checkfu publishes a platform-issued receipt authority. Caller-reported checkfu eval output remains unverified and cannot authorize the transition. Roll back by re-applying an immutable prior release.

5. Uninstall

   Remove Blueprint-owned PermissionAssignments and ActionPolicies, and disable, detach, or pause the remaining exposure the Blueprint owns. Uninstall retains Connections, Principals, MemoryStores, transcripts, and artifacts; erasure is a separate, explicit request.

Validate locally today

The package format, validation, and local checks are available now through the CLI. Reading a directory checks its structure and package-intrinsic semantics (excessive privilege, scope conflicts, duplicate names, missing governance) and prints a resolved preview:

checkfu blueprint validate ./my-blueprint

blueprint tag-assistant (directory)
  model default-model · sandbox tag-secure · surface slack
  connection github-main → github [repo:read, pr:write]
✓ valid (0 warnings)

For an Agent-centered project using agent/agent.json, path-owned tools and skills, and declared scenarios, start with Author an Agent project. That local frontend compiles to this same package authority; its source and .checkfu artifacts never become runtime authority.

The live API defines planning and the fail-closed lifecycle for applying a published package, promotion, rollback, and uninstall. Those operations are not generally executable until the support projection reports the Blueprint lifecycle prerequisite and release evidence satisfied. Planning remains non-mutating, and apply never trusts caller-supplied resource or credential hints: when admitted, the server re-reads the immutable package and proves each concrete Workspace resource and exact custody slot before adopting it.