# agentfootprint

Adopt this skill: https://proskills.md/skills/other/footprintjs-agentfootprint-ai-instructions-claude-code

Page: https://proskills.md/skills/other/footprintjs-agentfootprint-ai-instructions-claude-code
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: ai-instructions/claude-code/SKILL.md
size: 8076
upstream: https://github.com/footprintjs/agentfootprint/blob/main/ai-instructions/claude-code/SKILL.md

````text
---
name: agentfootprint
description: Use when building AI agents with agentfootprint — LLMCall, Agent, skills, RAG, memory, control flow, Swarm concepts, mock/anthropic/openai/ollama providers, tools, recorders, resilience, and streaming. Also use when someone asks how agentfootprint works or wants to understand the framework.
---

# agentfootprint — The Explainable Agent Framework

agentfootprint structures AI agents as composable flowcharts, so every injection, read, write, decision and tool call becomes connected evidence as the run happens. Every concept takes an `LLMProvider` — swap `mock({...})` for `anthropic({...})` with zero code changes.

**Core principles:**
- Adapter-swap testing ($0 test runs, deterministic assertions)
- The ladder: `mock` → `ollama` (free, local, real model) → a paid provider
- Declare context (facts, steering, skills); the framework decides WHEN it fires and WHICH slot it lands in
- Collect during traversal, never post-process (inherited from footprintjs)

```bash
npm install agentfootprint footprintjs
```

## Read this first — what does NOT exist

These are not hypothetical. A capable author, working from a correct mental model of
this library, invented all four in one document. Treat them as the things you are
most likely to get wrong here.

| You will reach for | The reality |
|---|---|
| `startRun(...)` | **No such function.** The door is `agent.run(input, options?)`, where `AgentInput = { message: string; identity?; continueFrom? }` and `AgentOutput = string`. `run()` returns `AgentOutput \| RunnerPauseOutcome` — a run paused for a human returns a checkpoint; discriminate with `isPaused(result)`. |
| `RunStep` as skill/route history | **`RunStep` is real and it is something else** — the footprintjs flowchart TOPOLOGY slider, exported from `agentfootprint/observe`. Its `kind` is `'sequential' \| 'fork' \| 'merge' \| 'decide' \| 'iteration' \| 'iteration-exit' \| 'react'`. Nothing in it concerns skills. Importing it succeeds, which is exactly why it is dangerous. For route history use `routeRecorder()` from the same door. |
| the LLM classifier as routing "tier 3" | **It is a tier-2 strategy.** Tier 1 = declared start rules. Tier 2 = the configured scorer — `llmClassifier(provider)` OR `keywordScorer()` OR `embeddingScorer(e)` OR the entry scorer; near-ties fall through rather than argmax. Tier 3 = a menu the model resolves in-band through `read_skill`'s own description, reached only when tier 2 was NOT decisive. |
| a skill's tools being gated to that skill automatically | **They are not, by default.** `defineSkill({ tools })` puts them in the agent's static tool list at build time — visible from iteration 1 whether the skill ever activates or not. Ask for the gate: `.toolsFromActiveSkill()` (agent-wide), `skillGraph({ scopeTools: true })` (graph-wide), or `autoActivate: 'currentSkill'` (per skill). `.tree()` leaves are the one shape scoped by default. |

Two more absences: there is **no runtime force-stop governor** (`routeRecorder().getTrips()`
only *labels* a spinning run; `maxIterations` is the hard stop), and there is **no
automatic re-delivery of an ageing skill body** (`refreshPolicy` is stored and never
read on any version — use `surfaceMode: 'both'`).

## Subpath map — 18 doors

`agentfootprint` (main barrel: `Agent`, `LLMCall`, `defineTool`, control flow, patterns, `defineRAG`, pause/resume) · `/providers` (`mock`, `anthropic`, `openai`, `bedrock`, `ollama`, `mcpClient`, embedders — every provider, so bundlers never walk the vendor SDKs from the main barrel) · `/context` (`defineSkill`, `defineFact`, `defineSteering`, `defineInstruction`, `skillGraph`, `skillsFromDir`, the scorers) · `/memory` (`defineMemory`, `InMemoryStore`, `mockEmbedder`, the stores) · `/rag` (stores + loaders; `defineRAG` itself is on the main barrel) · `/observe` (recorders, tracing, `RunStep`) · `/resilience` (provider decorators) · `/reliability` (the rules-based fail-fast gate) · `/cache` (prefix-cache strategies; importing it registers them) · `/security` · `/hosting` · `/events` · `/skill-graph` (the routing layer with no framework attached, for a host that is not this agent) · `/recipes` (`defineAgentRecipe` — one named, versioned agent setup, applied with `.recipe()`) · `/maps` (`Claim<T>` and the map-engagement vocabulary behind `.maps()`) · `/classify` (the calibrated-classifier port: `Classifier`, `mockClassifier`) · `/ontology` (`defineOntology` — a declared map of the domain, mounted with `.ontology()`) · `/time` (`convertForTool` + `sugarForms` + `granularityMsOf` — the time layer's own answer to whether and how a tool reads a window, for an app outside a run; the steps `convertExact`, `convertWidened`, `periodFactProblem` too). `package.json` `exports` is the complete list; a path not on it does not resolve.

## Core Concepts

### LLMCall — a single LLM call, no tools

```typescript
import { LLMCall } from 'agentfootprint';
import { mock } from 'agentfootprint/providers';

const caller = LLMCall.create({ provider: mock({ reply: 'Hello!' }), model: 'mock' }).system('You are helpful.').build();
const result = await caller.run({ message: 'Hi' });
```

### Agent — a ReAct agent with tools

```typescript
import { Agent, defineTool } from 'agentfootprint';
import { mock } from 'agentfootprint/providers';

const weather = defineTool({
  name: 'weather',
  description: 'Get current weather for a city.',
  inputSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
  execute: async ({ city }: { city: string }) => `${city}: 72°F, sunny`,
});

const agent = Agent.create({ provider: mock({ reply: 'It is 72°F.' }), model: 'mock' })
  .system('You answer weather questions using the weather tool.')
  .tool(weather)
  .maxIterations(5)
  .build();

const result = await agent.run({ message: 'Weather in Paris?' });
```

### Context — facts, steering, skills, and declared routing

```typescript
import { defineFact, defineSteering, defineSkill, skillGraph } from 'agentfootprint/context';

Agent.create({ provider, model })
  .fact(defineFact({ id: 'user-profile', data: 'Plan: Pro · Customer since 2022' }))
  .steering(defineSteering({ id: 'policy', prompt: 'Never promise a refund before checking.' }))
  .skill(defineSkill({ id: 'refunds', description: 'Refund procedure.', body: '…', tools: [issueRefund] }))
  .build();
```

`defineSkill` bodies load on demand — the model opens one with `read_skill`, or a `skillGraph()` routes to it:

```typescript
const graph = skillGraph()
  .entry(triage, { when: (c) => /order/.test(c.userMessage) })   // where the turn STARTS
  .route(triage, refunds, { onToolReturn: 'lookup_order' })      // a declared handoff
  .build();

Agent.create({ provider, model }).skillGraph(graph).build();
graph.toMermaid();   // declared === drawn
```

`.entry()` and `.route()` take the skill OBJECTS, not their ids. The object form is
the other door — `skillGraph({ skills, start, steps })` returns a finished graph with
nothing to chain.

A skill is active exactly while the cursor is on it — one skill's turn at a time. An `.entry(x)` with **no** `when` is the persistent base (`always`), on beside whatever the cursor is on.

**The cursor is a program counter, not a per-turn classifier.** Nine causes move it (or
decline to), reported as `cursorMove.by` on `agentfootprint.context.evaluated` and as
`outcome` on `routeRecorder().getHops()`:

`'entry'` (cold start) · `'route'` (a declared `from`-gated edge fired) · `'tool-proposal'`
(a TOOL RESULT proposed a transition and the graph accepted it) · `'model-pick'` (a
gate-accepted `read_skill`) · `'intent'` (the tier-2 scorer was decisive) · `'continuity'`
(the cursor inherited from the previous turn held) · `'decider'` (an out-of-band menu
resolver) · `'stay'` (nothing fired — sticky, and a recorded decision, not an absence) ·
`'none'` (no cursor at all: nothing to enter, or a `tree()`, which has no cursor).
`routeRecorder`'s `RouteOutcome` is t
````

## File: README.md
upstream: https://github.com/footprintjs/agentfootprint/blob/main/README.md

```text
<h1 align="center">Agentfootprint</h1>

<p align="center">
  <strong>Build agents you can hold to the record.</strong>
</p>

<p align="center">
  An agent framework that compares the model's claims with what actually ran, during the run.
  You choose the checks and what happens next. It holds claims to the record, not to the world.
</p>

<p align="center">
  Built on <a href="https://github.com/footprintjs/footPrint">FootprintJS execution provenance</a>:
  context, tool calls, results and decisions become connected records as the agent runs.<br/>
  Build with tools, skills, memory, RAG and orchestration; use that record for answer checks, debugging and review.
</p>

<p align="center">
  <a href="#what-can-this-answer-support">Evidence and limits</a> ·
  <a href="#checks-you-can-enable">Checks and guarantees</a> ·
  <a href="#how-this-compares-with-langchain-and-mastra">Framework comparison</a> ·
  <a href="#quick-start--runs-offline-no-api-key">Quick start</a>
</p>

<p align="center">
  <a href="https://github.com/footprintjs/agentfootprint/actions"><img src="https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <!-- coverage-badge --><img src="https://img.shields.io/badge/coverage-87%25-green.svg" alt="coverage: 87%"><!-- /coverage-badge -->
  <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/v/agentfootprint.svg?style=flat" alt="npm version"></a>
  <a href="https://bundlephobia.com/package/agentfootprint"><img src="https://img.shields.io/bundlephobia/minzip/agentfootprint?label=minzipped" alt="minzipped size"></a>
  <a href="#tree-shakeable--esm-first"><img src="https://img.shields.io/badge/tree--shakeable-%E2%9C%93-success?style=flat" alt="tree-shakeable"></a>
  <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/dm/agentfootprint.svg" alt="Downloads"></a>
  <a href="https://github.com/footprintjs/agentfootprint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
</p>

---

## What can this answer support?

A tool returned no rows. Before an agent says **"there are no incidents"**, the app
needs to know which account was searched, what period the read covered, whether it
finished, and what it could not reach. A successful empty query and a failed query
support different answers.

For example, the bounded claim is: **"The search returned no matching incidents
for this account and time window. Email reports were not checked."** That is an
illustration of scope-aware wording, not a claim that no incident exists anywhere.
When the evidence cannot support the requested conclusion, the app should make
that uncertainty explicit or withhold the answer.

Agentfootprint supplies the execution record and configurable checks for that
decision. Your app defines the comparisons and delivery policy. Tool declarations
must describe the query truthfully: recording a source's assertion does not prove
the source is correct.

## How evidence reaches the answer

1. **Record what ran.** FootprintJS connects execution steps and data dependencies;
   Agentfootprint records the context supplied, tools called and results returned.
2. **Preserve the limits.** Tools declare absence, coverage and time boundaries.
   Configure those limits to travel with the answer instead of relying on the model
   to repeat them.
3. **Check before delivery.** Opt-in answer validation compares the candidate with
   evidence under app-authored rules. Enforce mode withholds failed or unverified
   candidates; the host decides how to explain the refusal to the user.
4. **Inspect the same run.** Review recorded inputs, results, decisions and checks,
   or replay the execution to investigate a failure.

Execution provenance describes what ran and what was supplied. It does not expose
the model's internal reasoning or independently establish that an external fact
is true. Withholding an answer does not undo tool actions already performed.

## Checks you can enable

Installing the framework does not make every answer verified. These mechanisms
have different jobs and must be configured for the claims your app needs to check.

| Mechanism | What it provides | Boundary of the guarantee |
|---|---|---|
| [`absent()`, `coverage()` and `.limitsTravelWithTheAnswer()`](#what-a-tool-returns--three-helpers-one-rule) | Explicit absence and declared limits, carried into prose or returned beside typed output. | Preserves declarations; does not prove that the tool described its coverage correctly. |
| [`.answerValidation()`](docs-next/content/docs/build/output-schema.mdx#check-the-answer-against-evidence) | App-authored checks on a typed final answer. Enforce mode buffers drafts and withholds failed or unverified answers; observe mode records the report and permits delivery. | Only the configured checks are judged. The app owns their correctness and the trustworthiness of its evidence. |
| [`.namesAndNumbersFromEvidence()`](docs-next/content/docs/build/evidence-gate.mdx) | A deterministic detector for unsupported values, with configurable extraction limits and delivery postures. | Default `assist` flags; `rails` refuses. A false sentence assembled from real values can pass. This is not general factual verification. |
| [`Tool.search` and typed `.negativeClaims()`](docs-next/content/docs/build/negative-claims.mdx) | Composed search scope and library-written statements for cited structured negative claims, retaining gaps and withholding or reporting unsupported claims according to policy. | **Opt-in, available but not recommended pending benchmark gates.** Accuracy and usefulness remain unmeasured. Depends on truthful app-owned search declarations; other answer fields remain unchecked model text. |
| [`.negativeClaims({ prose: true })`](docs-next/content/docs/build/negative-claims.mdx) | Bounded heuristic warnings on the model's own negative sentences. | Never verifies, blocks or rewrites an answer. The previous detector failed its benchmark; the revised path is unmeasured. No warning does not mean verified. |

The links above describe this branch. Features marked **unreleased** in the
[capability index](CAPABILITIES.md) are not yet available in the published package;
check its availability column and the [release notes](CHANGELOG.md) for your
installed version. The basic quick start below does not enable these checks.

## How this compares with LangChain and Mastra

These frameworks all support agent building and runtime controls. The useful
distinction is what each emphasizes, rather than whether it has guardrails.

| Framework | Emphasis and existing runtime controls |
|---|---|
| **LangChain / LangGraph** | Model and tool integrations, agent loops and stateful orchestration with persistence and human oversight. [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview) covers execution; [LangChain guardrails](https://docs.langchain.com/oss/javascript/langchain/guardrails) can check inputs, outputs and tool calls during a run. |
| **Mastra** | A TypeScript framework for agent applications, with workflows, memory, development tools, tracing and evaluations. Its [input/output processors](https://mastra.ai/docs/agents/processors) can validate or transform messages during execution. [Overview](https://mastra.ai/docs). |
| **Agentfootprint** | Agent building organized around FootprintJS execution provenance: connected execution records, declared evidence limits, and [configured checks](#checks-you-can-enable) that can govern answer delivery. |

Choose Agentfootprint when a central requirement is to connect an answer to what
the agent actually read, the limits of that evidence, and the checks applied before
delivery. Skills, tools and orchestration build the agent; the execution record
also supports its answer policy. This comparison describes design emphasis, not
exclusive capabilities or measured superiority in answer accuracy.

## 
```
