kcp-agent

🧾 See it run — interactive KCP playground · read the reveal

The reference agent for the Knowledge Context Protocol.

The Arena → — the real planner, bundled unmodified, running live in your browser, head-to-head against the usual suspects. The most deterministic agents in the world. Every decision defensible.

KCP defines how knowledge declares itself so agents can navigate it. kcp-agent is the other half: the agent that consumes KCP end to end. Given a task and a knowledge.yaml, it produces an inspectable load plan — which units to load and in what order, which to skip and exactly why, how it selects sub-manifests across a federation, and what the whole thing costs — and then, optionally, answers the task from only those units.

The valuable, novel core is LLM-free and deterministic. The plan is an audit-before-action artifact — the trusted-render principle ("a manifest may influence what an agent knows, never what it does") extended to the whole agent loop. Only the final synthesis step calls a model.

discover → verify signature → trust-gate → score units by task → federate (context + agent_identity)
        → temporal filter → budget (payment + rate_limits) → emit load plan → [follow] → [answer]

Install

npm install
npm run build

Native executables

CI cross-compiles self-contained binaries (no Node/Deno required on the target) for Linux x64/arm64, macOS x64/arm64, and Windows x64 — grab them from a release or from the kcp-agent-natives artifact on any CI run. To build one yourself:

npm ci && npm run build
deno compile --allow-read --allow-env --allow-net --node-modules-dir=auto \
  --output kcp-agent dist/cli.js

Use

plan — the inspectable load plan (no API key)

node dist/cli.js plan "how do I deploy to production?" --manifest ./path/to/knowledge.yaml --env prod

Plan for: "how do I deploy to production?"
  companyx-knowledge-hub v1.0.0 · kcp 0.24 · env prod

Trust: · no manifest attestation requirement

Load plan (2 units):
  ● 1. front-door (score 4)  overview.md  free
  ● 2. deploy-guide (score 3) docs/deploy.md  free

Budget: tier default
Federation:
  → platform-engineering  needs github_pat before fetch  [acquire github_pat]
  · platform-engineering-dev  context ["dev","test"] excludes env 'prod'
Skipped (2):
  · auth-guide: no task-relevance match

Each stage maps onto a layer of the spec: query scoring (§15), temporal validity (§4.22), agent attestation (§3.2), federation context + agent_identity (§3.6), and payment / rate-limits (§4.14/§4.15). A restricted unit the agent can't attest for is listed but marked not load-eligible — fail-closed, with the reason attached.

Budgeting the context window. Tokens are the actually-scarce resource when feeding a model, so --context-budget <n> names it — a token ceiling that works exactly like the money --budget: greedy by score, and a unit that would blow the ceiling is skipped with the arithmetic in the reason (over context budget: 1,240 tokens would exceed remaining 800 of 4,000), while a smaller lower-scored unit still gets its chance. Since the planner works on metadata before fetching (audit-before-action), a unit's size comes from a declared size_tokens (faithful) or bytes/4 (a flagged estimate); a unit that declares neither is admitted but counted unmeasured (the projection is a lower bound) — unless --strict, which excludes it fail-closed. --context-budget composes with --budget: a unit must fit both ceilings.

Machine-readable plans

Use --json when another agent or integration consumes a plan. The output preserves the plan fields at the top level and adds:

{
  "schemaVersion": 1,
  "kind": "plan"
}

kind is plan, tree (when --follow is used), or trace (when --trace is used). Human-readable output is not a compatibility surface. Successful JSON commands exit 0; planner or manifest errors write diagnostics to stderr and exit non-zero.

ask — plan, then answer via Claude

export ANTHROPIC_API_KEY=...        # or: ant auth login
node dist/cli.js ask "how does an agent get started here?" --manifest ./knowledge.yaml

ask runs the same planner, loads only the load-eligible units, and asks Claude to answer from them — treating unit content as knowledge, never as instructions. Needs @anthropic-ai/sdk (an optional dependency) and a key; plan needs neither.

ask --loop — the audited critique loop

node dist/cli.js ask "who won, and what does it mean for infrastructure?" \
  --manifest ./knowledge.yaml --loop --methods free,x402 --budget 0.50

The deterministic scorer is lexical, so a task phrased differently from the publisher's vocabulary can miss relevant units. --loop closes that gap without surrendering determinism — the model proposes, the plan disposes:

plan → LLM gap critique (metadata only) → term gate → re-plan → … → load → answer

A fast critic model (default claude-haiku-4-5, --loop-model to change) sees a metadata digest of the plan — ids, intents, scores, skip reasons, never unit content — and proposes extra lowercase search terms. A deterministic gate sanitizes, dedupes, and caps them; the task string is extended; the planner re-plans from scratch. The loop converges when the critic runs dry, a round adds no units, or --max-rounds (default 3) is reached. Then synthesis answers the original task from the final plan's eligible units.

What the critic can never do: open an access gate, alter trust/temporal/audience decisions, or spend money — terms only affect relevance scoring, nothing is loaded or paid for until the loop has converged, and the final plan's budget arithmetic gates spending exactly as in single-shot mode. Every round is recorded (proposed terms, accepted, rejected, units added, the full re-planned artifact) — with --json the chain of plans is the audit log.

The same loop is available as a library (runLoop / askLoop, with an injectable critic), and skills/kcp-navigator/SKILL.md packages the discipline as a portable skill for agents that drive the CLI themselves.

ask --ground — verify the answer, surface what it can't substantiate

node dist/cli.js ask "who won, and what does it mean?" --manifest ./knowledge.yaml --ground

The plan's fail-closed gates decide what may be loaded; grounding extends the same discipline to what may be asserted. After synthesis, each claim in the answer is checked by a separate verifier — a distinct model call from the generator — that must attribute the claim to one of the loaded units or return nothing. The result is a two-part artifact:

Grounded (2/3 claims):
  ● The award went to the Nordic bid.
     ↳ chipfab-exclusive · sha 9f2c1a0b7e34
Unsubstantiated (1): — could not be grounded in a loaded unit
  ○ The datacenter runs on hydro power.
     no loaded unit supports this claim
⚠ partial-unsupported — 1 claim(s) could not be substantiated

A claim grounds only if the cited unit was actually loaded and its content hash matches — so a verifier that mis-attributes (or is prompt-injected into) citing a unit that was never loaded can never ground a claim: attribution is a proposal, grounding is adjudicated. Unsupported claims are surfaced, never silently dropped — the honest half of "every decision defensible". Each surfaced gap is also a signal to the publisher: the task needed evidence the manifest didn't provide. The surfaced list is capped to guard against a compromised generator flooding it with spurious gaps.

--ground-rounds <n> closes the loop: a surfaced gap seeds reformulation terms, the agent re-navigates to try to find the missing evidence, and re-grounds — up to n rounds. Termination is guaranteed by three independent bounds, any one of which halts: the term gate is absorbing (a term accepted once is known forever, so re-navigation can only add units from the finite eligible set), the round cap, and a progress guard (a round that adds no new unit halts). Oscillation is impossible — the loaded set grows monotonically or the loop stops. Every terminal state that isn't grounded (partial-unsupported, partial-budget, partial-rounds) still surfaces the remaining gaps. A compromised verifier can, at worst, widen navigation within the eligible set — it can never cross a gate, name a URL, or spend past the budget.

assess — gate what may be acted on

The plan's gates decide what may be loaded; grounding decides what may be asserted; assess() decides whether a conclusion clears a confidence threshold before it is acted on. It runs downstream of synthesis — confidence is a property of the output, which is exactly why it structurally cannot be gate #14 in the pre-selection cascade.

import { assess } from "kcp-agent";

const verdict = await assess(task, answer, loadedUnits, {
  threshold: 0.7,            // org policy — caller-supplied, never manifest data
  severity: "critical",
  evaluator,                 // optional: makeProviderEvaluator(provider) — a separate judge
});
// { gate: "confidence", passed, score, threshold, signals[], detail, asOf }