Author an Agent project

An Agent authoring project is a local source frontend for the governed Agent model. It makes desired Agent configuration inspectable and repeatable. It does not become runtime authority.

The Checkfu CLI has no self-service public installation channel during private alpha. Every command below assumes a source checkout or an explicitly authorized alpha artifact. Read CLI access before continuing.

The commands here cover Agent configuration only. checkfu agent apply writes an Agent and nothing else. No command applies Budgets, PermissionAssignments, ActionPolicies, Connections, Automations, or Memory declarations from a file. Create those through the ordinary API, SDK, CLI, or console. See Agent Blueprints for what replaces the retired package lifecycle. For customer-owned Custom-tool or embedded UI code, inspect the integration catalog first:

This flow runs from a Checkfu source checkout. Part of this flow is behind a rollout fence; a deployment that has not enabled it refuses the request rather than running it. Confirm capability status before making availability part of your application’s contract.

checkfu add --list

Recipes print instructions and write nothing. This guide covers only the local Agent project.

Directory layout

checkfu.json
agent/
  manifest.json
scenarios/<name>.json

agent/manifest.json is the complete inline Agent configuration. Put instructions in system and declare tools and Skills in the tools and skills arrays. agent/manifest.json may also declare skill_selection, the Skills the agent can activate during a Session ({"type": "listed", "skills": [...]} with exact versions, or {"type": "workspace"}). Leave the key out and a selection saved another way is left alone; set it to null to remove one. The Agent directory contains exactly this one file; separate instruction, tool, and Skill files are not accepted in this project shape. From the source checkout root, copy the example package into a new directory:

cp -R packages/blueprint/templates/tag-assistant ./my-agent
cd my-agent

Replace agent/manifest.json with this complete local-validation example:

agent/manifest.json

{
  "schema_version": 2,
  "model": { "id": "claude-sonnet-4-5" },
  "harness": "checkfu-mock",
  "name": "Tag Assistant",
  "description": null,
  "mcp_servers": [],
  "skills": [],
  "system": "Respond to mentions and summarize the request.",
  "tools": []
}

The mock harness demonstrates local authoring only. Choose an admitted harness, model, and referenced resources before applying to a live Workspace. checkfu.json describes the project boundary. Declared scenarios travel with the project as authoring and evaluation inputs. Keep credentials out of every source file. Source may declare a governed Connection or credential requirement, but never the value.

Inspect before editing

Run inspection and retain the machine-readable output for comparison:

checkfu agent info . --json

Inspection normalizes the project, reports diagnostics, and shows the Agent, tools, Skills, scenarios, required Connections, and compatibility requirements the compiler sees. It does not contact a live Workspace or claim any resource. Inspect before editing. Do not repair a project from filenames or prose alone when the installed compiler can show the normalized input.

Compile an immutable generation

checkfu agent compile .
jq . .checkfu/current.json

Compilation writes an operation-specific generation under .checkfu and atomically updates .checkfu/current.json to point at the current result. Follow that pointer and review the compiled output, diagnostics, inspection, and compatibility artifacts. The compiled files are local authoring evidence. They are not an AgentVersion, Session transcript, admission record, or runtime authority. A behavior change becomes live only when an authorized canonical Agent mutation creates the next immutable Agent version and a later Session admits it. Compilation fails closed on unsupported capabilities, path/name drift, malformed input, unsafe artifact roots, or staging failure. A partially written directory is not success.

Plan and apply the Agent

Plan and apply work on a checked-in Agent directory. It holds agent.yaml (or agent.json) and an optional instructions.md. The file is the final Agent configuration, so every source-owned field is present:

support-agent/agent.yaml

model:
  id: claude-opus-5
harness: claude-code
name: Support Agent
description: null
mcp_servers: []
skills: []
system: null
tools: []

Declare system in the file or in instructions.md, not both. Set the Agent harness to one your Workspace can admit.

checkfu agent plan ./support-agent
checkfu agent apply ./support-agent

plan compiles the directory, reads the live Agent, and prints the fields that differ. It writes nothing. apply writes the differences through the ordinary Agent create and update operations. Without --agent-id, apply creates a new Agent and prints its ID. Record that ID and pass it on later runs, because a definition file names no Agent:

checkfu agent plan ./support-agent --agent-id <agent-id>
checkfu agent apply ./support-agent --agent-id <agent-id>

Reapplying an unchanged directory creates no new AgentVersion. An edit to a field such as system or tools creates the next AgentVersion. The harness field is fixed when the Agent is created, so changing it is reported as a blocked difference and the apply is refused.

What apply does not create

agent apply does not create or change the following. Create each one through its own API, SDK, CLI command, or console page, then reference it from the Agent or Session that needs it:

Budgets
PermissionAssignments and ActionPolicies, including the use_environment and act_as grants an Agent needs
Connections and their credentials
Automations and AutomationGraphs
MemoryStores and their mounts

Attach an authorized MemoryStore through a Session’s resources, as shown in Coming from Claude Managed Agents. The quickstart shows how to add a PermissionAssignment through REST, CLI, or SDK. To make a harness runnable for a Session, the Workspace HarnessProfile also needs current, passing signed conformance evidence. Check it with checkfu harness verify <profile> --sandbox <environment-key> --model <model-profile-key> --wait.

Understand authoring authority

Compiling a project claims nothing. Agent apply invokes the ordinary Agent create and update operations; repository CI owns review and merge policy. Authentication, authorization, optimistic concurrency, and resource-specific policy remain server-enforced. Checkfu keeps no server-side record of the directory. Keep source changes coordinated with direct edits, and inspect typed conflicts before retrying. Read Authoring authority.

Plan and evaluate scenarios

Materialize the scenario plan bound to the current compiled package:

checkfu eval .

Run every declared scenario against the intended authorized target. Settlement comes from the Session event log and the platform authorities involved. Response timing is not a verdict, and a failed scenario is a failed evaluation. Record exactly one observation for every declared scenario, then bind the closed observation document to the current plan:

checkfu eval . --observations observations.json --json

The resulting evidence is labeled unverified-caller-reported. The CLI validates document shape, complete scenario coverage, and binding to the compiled package, but it does not independently re-read the target event log or authorize an apply or any other change. A minimal observation document has this shape:

{
  "kind": "checkfu-agent-eval-observations",
  "version": 1,
  "release_hash": "sha256:<compiled-package-digest>",
  "scenarios": [
    {
      "name": "scenario-name",
      "passed": true,
      "cost_tokens": 120,
      "latency_ms": 950,
      "source_report": {
        "kind": "checkfu-unverified-scenario-report",
        "version": 1,
        "target": { "kind": "worker", "name": "authorized-target" },
        "session": "sess_<id>",
        "run": "run_<id>",
        "events": {
          "from_sequence": 1,
          "to_sequence": 12,
          "digest": "sha256:<event-log-digest>"
        }
      }
    }
  ]
}

Treat source_report as a caller assertion. Preserve a platform Outcome verdict when the scenario declares one; do not invent another grader or retry authority.

Git and YAML are source forms

It is safe to keep human-authored project source in Git when your repository policy allows it. Git does not become the reconciler. A CI job may inspect, compile, and plan the source, then run checkfu agent apply --agent-id <agent-id> with a Workspace API key. Apply uses the same authenticated Agent operations as every other authoring surface, with their authorization and concurrency checks.

Agent contract

Inspect before editing, and compare the compiled generation with intent.
Keep Agent configuration in agent/manifest.json for the inspect and compile loop, and in agent.yaml or agent.json for plan and apply.
Never weaken compatibility epochs merely to make compilation pass.
A failed scenario is a failed evaluation.
Keep credentials out of source, artifacts, and observations.
Never run local authoring code in the Checkfu control plane, Runner, or sandbox.
Never mutate a live Session to adopt source changes. Create a new immutable Agent version through the canonical Agent operation and let later Session admission pin it.
Never commit or upload .checkfu without explicit authorization. The directory may contain local paths, diagnostics, observations, and evidence that your repository or data policy does not permit sharing.

Locate the version-matched bundled guide and skill without fetching remote instructions:

checkfu agent docs --json

To install a coding agent, continue to Use Checkfu with your coding agent.

Get started

Agents

Sessions

Environments

Tools

Context

Automations

Permissions

Security

Billing

Deployment

Author an Agent project

Directory layout

Inspect before editing

Compile an immutable generation

Plan and apply the Agent

What apply does not create

Understand authoring authority

Plan and evaluate scenarios

Git and YAML are source forms

Agent contract

​Directory layout

​Inspect before editing

​Compile an immutable generation

​Plan and apply the Agent

​What apply does not create

​Understand authoring authority

​Plan and evaluate scenarios

​Git and YAML are source forms

​Agent contract

Directory layout

Inspect before editing

Compile an immutable generation

Plan and apply the Agent

What apply does not create

Understand authoring authority

Plan and evaluate scenarios

Git and YAML are source forms

Agent contract