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.
footprintjs · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add footprintjs/agentfootprint --skill agentfootprintAbout this skill
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)
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 — 13 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).
Core Concepts
LLMCall — a single LLM call, no tools
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
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
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:
const graph = skillGraph()
.entry(triage, { when: (c) => /order/.test(c.userMessage) }) // where the turn STARTS
.route(triage, re
Read the complete source ↗