Author an Agent project

Inspect, compile, and evaluate declarative Agent intent with the version-matched CLI workflow.

An Agent authoring project is a local source format that compiles into the governed Agent and AgentBlueprint model. The source tree and .checkfu outputs are inspectable authoring material; neither is runtime authority.

The Checkfu CLI has no self-service public installation channel during private alpha. Every command below assumes a Checkfu source checkout or a private artifact supplied through an explicitly authorized alpha arrangement. Read CLI access before continuing. If you do not have CLI access, use the HTTP contract and public schemas instead of inventing an install command.

If the task also includes customer-side Slack, Custom-tool server, or embedded UI code, inspect the bundled integration catalog first:

checkfu add --list

Recipes remain write-nothing integration instructions. This guide owns declarative Agent intent; use Checkfu with your coding agent explains when to install the version-matched authoring skill.

Project tree

checkfu.json
agent/
  agent.json            # optional
  instructions.md
  tools/<tool-name>.json
  skills/<skill-name>.json
scenarios/<scenario-name>.json

agent/instructions.md is the only file under agent/ that is required. checkfu.json already declares the harness, model routing profile, and environment, so a project with nothing but a page of markdown under agent/ compiles: the name comes from the page’s leading # Title, and everything else takes its default. Add agent/agent.json when the agent needs tools, skills, or a policy that page cannot carry.

agent/agent.json follows the canonical Agent manifest, except name is optional. Tool and skill identity comes from the path: omit a redundant name, or make it exactly match <tool-name> / <skill-name>. checkfu.json owns the Blueprint package, and each file under scenarios/ declares an acceptance scenario that travels with it.

Keep credentials out of every file. A Blueprint declares credential requirements; values enter only through the governed write-only operation for the bound resource.

Inspect before editing

Run inspection before changing source, and keep the JSON result for comparison:

checkfu agent info . --json

Inspection reports the source format, normalized Agent and Blueprint identity, release hash, tools, skills, scenarios, diagnostics, required Connections, and compatibility requirements. The compiler defaults blueprint, agent, tool, skill, and scenario authoring capabilities to epoch 1. Declare a different epoch under compatibility in agent/agent.json only when the project genuinely requires it. Never downgrade an epoch merely to make compilation pass.

Compile and inspect the immutable generation

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

Compilation atomically writes an operation-unique generation under the compiled release digest in .checkfu/compile/, then updates .checkfu/current.json. Follow that pointer and inspect the canonical package, diagnostics, inspection, and compatibility documents. Do not assume source was accepted because the command produced some output; compilation fails closed on unsupported capabilities, path/name drift, staging problems, or symlinked artifact roots.

A behavior change becomes effective through the next immutable Agent version and ordinary Session Version pinning. Local source and compiled files never replace that authority.

Plan and run the declared scenarios

checkfu eval .

This validates the declared scenarios and materializes a plan bound to the exact compiled release_hash. Run every planned scenario against the intended Target—for example an authorized local worker or admitted deployment—and read settlement from the Session event log. A failed scenario is a failed evaluation; do not grade from response timing or silently omit a case. Outcomes may supply a platform verdict when a scenario declares one, but the CLI does not create a second grader.

Record exactly one observation per declared scenario. The minimal closed document is:

{
  "kind": "checkfu-agent-eval-observations",
  "version": 1,
  "release_hash": "sha256:<compiled-release-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": "release-worker" },
        "session": "sess_<id>",
        "run": "run_<id>",
        "events": {
          "from_sequence": 1,
          "to_sequence": 12,
          "digest": "sha256:<event-log-digest>"
        }
      }
    }
  ]
}

Then bind the observations to the current plan:

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

The observations input must be a regular UTF-8 JSON file no larger than 1 MiB. Oversized or non-regular input is refused before local evidence is written.

Evaluation writes its own generation and pointer, separate from the compile pointer: follow .checkfu/eval-current.json to the generation holding plan.json and, once observations are bound, evidence.json. That pointer also carries the planned / passed / failed status.

The resulting .checkfu/eval/.../evidence.json is labeled unverified-caller-reported. The CLI validates shape, complete scenario coverage, and release binding, but it does not independently re-read the Target event log or emit promotion-grade ReleaseEvaluation evidence. Treat source_report as a caller assertion.

Agent contract

• Inspect before editing, and compare the compiled generation with your intent.
• Follow path-derived tool and skill names; do not create a second identity in JSON.
• Never weaken compatibility epochs to pass compile.
• A failed or missing scenario is a failed evaluation.
• Never put credentials in source, artifacts, or observations.
• Never run local authoring code in the Checkfu control plane, Runner, or Sandbox.
• Never commit or upload .checkfu artifacts, observations, or evidence without explicit authorization.

For the installed-version repair workflow and complete optional Outcome fields, follow the shipped checkfu-agent-authoring skill. Locate the version-matched copies, and the authoring capability epochs your CLI supports, with:

checkfu agent docs --json

That prints the on-disk paths to the bundled guide and skill rather than fetching anything, so it stays correct offline and cannot drift from the binary you are running. The coding-agent guide covers installing the skill into an agent. This page is the human-readable route into the same stable contract.