⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
agentfootprint
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.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
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
- Record what ran. FootprintJS connects execution steps and data dependencies; Agentfootprint records the context supplied, tools called and results returned.
- 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.
- 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.
- 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() | 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() | 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() | 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() | 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 }) | 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 are not yet available in the published package; check its availability column and the release notes 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 covers execution; 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 can validate or transform messages during execution. Overview. |
| Agentfootprint | Agent building organized around FootprintJS execution provenance: connected execution records, declared evidence limits, and configured checks 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.
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
ai-instructions/claude-code/SKILL.md7.9 KBupstream ↗
--- 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 tREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/footprintjs-agentfootprint-ai-instructions-claude-code.md