> ## Documentation Index > Fetch the complete documentation index at: https://docs.checkfu.com/llms.txt > Use this file to discover all available pages before exploring further. # Author an Agent project > Inspect, compile, and evaluate local Agent source without turning it into a second runtime or resource writer. An Agent authoring project is a local source frontend for the governed [Agent](/concepts/agents) 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](/getting-started/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](/concepts/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](/getting-started/status) before making availability part of your application's contract. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} checkfu add --list ``` Recipes print instructions and write nothing. This guide covers only the local Agent project. ## Directory layout ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} checkfu.json agent/ manifest.json scenarios/.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: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} cp -R packages/blueprint/templates/tag-assistant ./my-agent cd my-agent ``` Replace `agent/manifest.json` with this complete local-validation example: ```json title="agent/manifest.json" theme={"theme":{"light":"github-light","dark":"github-dark"}} { "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: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```yaml title="support-agent/agent.yaml" theme={"theme":{"light":"github-light","dark":"github-dark"}} 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. ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} checkfu agent plan ./support-agent --agent-id checkfu agent apply ./support-agent --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](/guides/coming-from-claude-managed-agents). The [quickstart](/getting-started/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 --sandbox --model --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](/concepts/agent-blueprints#authoring-authority). ## Plan and evaluate scenarios Materialize the scenario plan bound to the current compiled package: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "kind": "checkfu-agent-eval-observations", "version": 1, "release_hash": "sha256:", "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_", "run": "run_", "events": { "from_sequence": 1, "to_sequence": 12, "digest": "sha256:" } } } ] } ``` 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 ` 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: ```sh theme={"theme":{"light":"github-light","dark":"github-dark"}} checkfu agent docs --json ``` To install a coding agent, continue to [Use Checkfu with your coding agent](/guides/use-checkfu-with-your-coding-agent). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.