> ## Documentation Index > Fetch the complete documentation index at: https://checkfu.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](/concepts/agents) version, a harness and model, a SandboxProfile, an [installation](/concepts/installations) on a surface, a service principal, [connections](/concepts/capabilities), PermissionAssignments and [ActionApprovals](/concepts/action-approvals), [budgets](/concepts/automations#budgets), [automations](/concepts/automations), [memory](/concepts/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 starter](/concepts/automations#automation-starters-and-packaged-guardrails), 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](/getting-started/cli-access) for the source-checkout and HTTP alternatives. The source posture is `alpha` / `hosted`, but the live [capability status](/getting-started/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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/concepts/agents#a-page-of-markdown-is-an-agent) 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**: Blueprint-managed. Apply creates it and reconciles it toward the declared shape on upgrade. Must already exist in the Workspace. Apply resolves and binds it, but never creates or mutates it. 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: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} source: reference name: claims-agent agent_deployment_revision_selection: type: current ``` An Automation `target` value: ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 Check the package structure and semantics locally, with no keys, and preview the resolved access. 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. Reconcile idempotently and resumably. A partial failure resumes to one correct installation; apply never deletes a resource it did not create. 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. 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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} checkfu blueprint validate ./my-blueprint ``` ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/guides/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](/getting-started/status) 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.