Your agent gave an answer that looks right — and it's wrong. The logs can't tell you who influenced it. Agentfootprint can.
The explainable AI agent framework for TypeScript: every read, write, decision, and tool call becomes
connected evidence as your agent runs. When something goes wrong, you don't grep logs — you ask.
Build agents — skills, steering, RAG, memory, control flow — and debug them like nothing else. Why is a query, not a guess.
A real run, replayed — rendered with AgentThinkingUI (npm i agentthinkingui). Every frame is generated from the run's own trace; ▶ watch it live.
---
## The new error class
For decades, software had two kinds of errors — and developers never needed deep
domain knowledge to fix either:
| Error class | Where the bug lives | How you find it |
|---|---|---|
| **Infrastructure** — crash, timeout, 500 | the system | infra logs, monitoring |
| **Business logic** — wrong branch, wrong math | the code | stack trace, debugger, `console.log` |
| **Contextual** — wrong tool chosen, wrong fact believed, stale memory trusted | **what the model was given** | **nothing. Until now.** |
Agents introduced the third class. The code is correct, the infra is healthy, the
answer even reads well — and the run is still wrong, because something influenced
the model:
| The model… | because… |
|---|---|
| picked the wrong tool | two descriptions read nearly alike — it chose between twins |
| believed a wrong "fact" | a tool returned it, or an injected fact planted it |
| followed the wrong instruction | the wrong skill / steering fired — or fired one iteration too early |
| answered from the past | a previous turn or stale memory bled into this one |
Classical logs can't explain any of it: **they record what the code did, never
what the context did.** The debugging question changed — no longer *"what did my
code do?"* but **"who influenced the model?"**
## The idea
If contextual errors live in what the model was given, then the run itself must be
structured so context is **evidence** — every injection, read, write, decision, and
tool call recorded *connected*, the moment it happens. Not logs you grep. Evidence
you ask.
## Quick start — runs offline, no API key
```bash
npm install agentfootprint footprintjs
```
```typescript
import { Agent, defineTool, mock } from 'agentfootprint';
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: 'I checked: it is 72°F and sunny.' }),
model: 'mock',
})
.system('You answer weather questions using the weather tool.')
.tool(weather)
.build();
const result = await agent.run({ message: 'Weather in Paris?' });
console.log(result); // → "I checked: it is 72°F and sunny."
```
For production, import a real provider from `agentfootprint/llm-providers` and swap it in — `anthropic(...)` / `openai(...)` / `bedrock(...)` / `ollama(...)`. Only the import line changes; the agent code stays the same. (The vendor-SDK providers live on the `agentfootprint/llm-providers` subpath so the main `agentfootprint` barrel stays free of optional peer-dep requires; `mock`, `browserAnthropic`, and `browserOpenai` are on the main barrel.)
### Run against a local model (Ollama, llama.cpp, vLLM — any OpenAI-compatible endpoint)
No cloud account, no API key, $0 per token. `openai({ baseURL })` targets any server that speaks the OpenAI Chat Completions API — Ollama has its own one-line shortcut:
```typescript
import { Agent } from 'agentfootprint';
import { ollama } from 'agentfootprint/llm-providers';
const agent = Agent.create({ provider: ollama({ defaultModel: 'llama3.1' }), model: 'llama3.1' }).build();
// → talks to http://localhost:11434/v1 (run `ollama pull llama3.1` first)
```
For llama.cpp's `llama-server` or vLLM, swap in `openai({ baseURL: 'http://localhost:8080/v1', apiKey: 'not-needed', defaultModel: '…' })` — same `Agent` code either way. Local servers usually ignore `apiKey`, and most only accept the older `max_tokens` field; both are handled automatically whenever `baseURL` is set. Full recipes: [OpenAI-compatible endpoints](https://footprintjs.github.io/agentfootprint/docs/build/openai/#openai-compatible-endpoints-ollama-llamacpp-vllm-together-groq-lm-studio) · [Ollama guide](https://footprintjs.github.io/agentfootprint/docs/build/ollama/).
### Then add context
A real agent carries more than one prompt and one tool: facts about the user, always-on rules, skills that unlock on demand. Declare each piece — the framework decides **when** it fires and **which slot** it lands in, and every piece is born tracked:
```typescript
import { defineFact, defineSteering, defineSkill } from 'agentfootprint';
const agent = Agent.create({ provider, model })
.system('You are a support agent.')
.fact(defineFact({ // data the model should know — always on
id: 'user-profile',
data: 'Name: Maya · Plan: Pro · Customer since 2022',
}))
.steering(defineSteering({ // rules the model must follow — always on
id: 'refund-policy',
prompt: 'Never promise a refund before checking the policy tool.',
}))
.skill(defineSkill({ // guidance + tools — unlocks when the LLM asks
id: 'billing',
description: 'Use for refunds, charges, billing questions.',
body: 'When handling billing: confirm identity first, then…',
tools: [refundTool],
}))
.build();
```
Same shape for `.instruction()` / `.memory()` / `.rag()` / raw `.injection()` — they're all the one primitive, `Injection = slot × trigger × cache`. [The full model ↓](#the-model--what-we-abstract)
### Then compose control flow
One agent is a `Runner`. So is every composition of agents — four control-flow primitives, and anything that runs composes into anything else:
```typescript
import { Sequence, Parallel, Conditional } from 'agentfootprint';
const pipeline = Sequence.create()
.step('classify', classifyAgent) // sequence: step → step
.step('review',
Parallel.create() // parallel: fan out, then merge
.branch('legal', legalAgent)
.branch('ethics', ethicsAgent)
.mergeWithLLM({ provider, model, prompt: 'Synthesize:' })
.build())
.step('respond',
Conditional.create() // conditional: one branch runs
.when('urgent', (i) => i.message.startsWith('URGENT'), urgentAgent)
.otherwise('normal', normalAgent)
.build())
.build();
await pipeline.run({ message: 'URGENT: refund dispute on order #4411' });
```
The fourth primitive is `Loop` — `Loop.repeat(agent).until(guard).times(5)`, with a mandatory budget guard. And the named patterns from the research literature ship pre-composed from the same four: `selfConsistency` · `reflection` · `debate` · `mapReduce` · `tot` · `swarm`. Because every composition is a flowchart, the structure you wrote is the structure you see in the UI — and the trace spans the whole pipeline, not one agent at a time. [Designing systems of agents ↓](#-build--design-your-agent-or-system-of-agents)
---
## How — we abstract context engineering
Skills, steering, RAG, facts, memory, guardrails — every name for context does one thing: it injects into one of three LLM slots. So we abstracted the injection itself.
One primitive: Injection = slot × trigger × cache. Because the framework owns this point, every piece of context is born tracked — observability isn't wired up, it's a consequence of the abstraction. The full model ↓
## What tracking buys you
**See it in 30 seconds** — four questions logs can't answer, each answered by code in this repo from a real run:
```text
Q: Why did the model pick refund_full instead of refund_partial?
A: margin 0.02 — ⚠ NARROW: the two tool descriptions read nearly identical
(toolChoiceRecorder — and the catalog lint flags the pair before you ever run)
Q: Why was this loan declined?
A: decision ← [control: "DTI above the 0.43 affordability ceiling"] ← dti 0.52 ← monthlyDebt / income
(decide() evidence + the causal slice — every hop is a real recorded edge)
Q: Which piece of context made the answer wrong?
A: CAUSAL: ablating fact 'vip-override' flipped the outcome in 3/3 seeded reruns
(localizeContextBug — ranked proxies, counterfactual proof)
Q: Prove nobody edited this run's record.
A: verifyAuditBundle → valid: false, brokenAt: #16 — the tampered record, named
(hash-chained audit export, offline verification)
```
And you don't have to read the trace yourself — the trace toolpack lets a debugger model do it: in one run it found a planted bug while reading **9.5% of the trace** ([guide](docs/guides/trace-debugging.md)).
And the watching costs the run nothing:
Your agent is the event loop: each stage feeds its trace events into a queue on the call stack; the dispatcher delivers them to your listeners in the idle beat — one beat behind, never on the hot path.
## One contextual error, walked end to end
The third question above, in full — every value below is the captured output of
[`examples/observability/05-context-bisect.ts`](examples/observability/05-context-bisect.ts)
and [`06-backtrack-trace.ts`](examples/observability/06-backtrack-trace.ts), runnable offline.
**The bug.** A refunds agent carries a poisoned customer-profile fact. It answers:
> *"Refund APPROVED: Dana Reyes holds VIP tier override status, so the 47-day-old
> order qualifies for a refund beyond the 30-day window."*
The policy says 30 days. The logs look fine — the model was *given* bad context,
and classical logging has no row for that.
**The walk.** Because context here is state, the decision backtracks like a
variable: who read it, who wrote it, who let it in, where it was born —
```text
ANSWER "Refund APPROVED…" ← the bug
READ call-llm#40 assembled the system prompt ← exactly what the model saw
LANDED context#6 wrote systemPromptInjections ← who mutated state
ALLOWED trigger { kind: 'always' } — active every iteration ← why it was let in
BORN defineFact('vip-override-fact') ← who wrote it
```
That chain is the **provable candidate set** — everything that demonstrably reached
the call, nothing else. Influence scoring then *ranks* inside it, and counterfactual
**ablation proves**: removing `vip-override-fact` flips APPROVED → DECLINED in
**3/3 seeded reruns** (the benign fact and the lookup tool: 0/3). Scores are proxies;
only ablation makes the causal claim.
**Three interfaces, one per shape of bug** — ship-a-default, bring-your-own:
| interface | finds the culprit when it is… | confirm by |
|---|---|---|
| **influence ranking** (`scoreInfluence` + `rankingConfidence`) | **present** — orders suspects, says when it can't rank | — |
| **ablation** (`localizeContextBug`) | **present** — *remove* it, see the outcome flip | removal |
| **missing-context finder** (`findDroppedContext`) | **absent** — available but never reached the model (`available − sent`) | restoration |
The third closes a gap the first two are blind to: a key instruction truncated out of
the window has nothing to ablate, so you confirm by *restoration*. And when scoring is
too flat to trust, `rankingConfidence` returns a shortlist to confirm rather than a
confident, wrong #1. Guides: [ranking-confidence](docs/guides/ranking-confidence.md) ·
[missing-context](docs/guides/missing-context.md).
**The same walk, visual.** `toBacktrackTrace()` serializes the report into
[AgentThinkingUI](https://github.com/footprintjs/agentThinkingUI)'s ``
— the "why?" board, triggerable from any decision point (final answer, a mid-loop tool
choice, a deterministic `decide()` rule):
The wrong answer, suspects with influence meters, the CAUSAL 3/3 ablation stamp on the planted fact, and the rewind showing the exact system prompt the model saw with the culprit highlighted — recorded state, not a reconstruction. Every id is a runtimeStageId a debugger LLM can drill via the trace toolpack. ▶ Try it live · run 06-backtrack-trace.ts offline.
### Pick how influence is scored — then re-run without the noisy source
Influence ranking is a pluggable strategy. Two ship out of the box:
`semantic-alignment` (embeddings, the default) and `lexical-overlap` (plain word
overlap — free and deterministic). `listInfluenceStrategies()` gives a UI everything
it needs to offer a picker, and to grey out what it can't run.
Found the source you suspect? `rerunWithoutSources` runs the same scenario again without
it. It reports what changed — the answer, how often it flipped across seeded re-runs, and
(with `checkBaseline`) a causal verdict. Scores suggest; re-runs convict.
```ts
const again = await rerunWithoutSources({ report, ignore: ['social-sentiment'], runner, originalAnswer, embedder });
again.answer; // 'HOLD …'
again.whatChanged.summary; // 'Removing sources [social-sentiment] changed the answer in 3/3 seeded re-runs …'
```
### Chat sessions that can explain themselves
`recordedChat` wraps your agent factory into a recorded conversation. Every `send()`
freezes that turn's evidence. `reason(k)` shows what influenced reply K. `rerunTurn(k,
{ ignore })` re-runs that exact turn — same recorded history, byte for byte — without a
source, and returns the same honest result `rerunWithoutSources` gives you. `fork(k,
{ fromRerun })` continues the conversation from the what-if as a new recorded session.
Branch, never rewrite.
```ts
import { recordedChat } from 'agentfootprint/debug';
const chat = recordedChat({ makeAgent }); // your factory, specs applied at construction
await chat.send('Should we BUY or HOLD?'); // recorded turn (frozen evidence)
const rerun = await chat.rerunTurn(1, { // that turn, minus one source
ignore: ['social-sentiment'], embedder, checkBaseline: true,
});
const fork = chat.fork(1, { fromRerun: rerun }); // continue from the what-if
```
---
## Pick your door
| 🔧 Building an agent? | 🐛 Agent misbehaving? | 🏛️ Need audit / compliance? |
|---|---|---|
| Typed agents with skills, steering, RAG, memory, guardrails — and the trace for free. | Lint your tool catalog in 5 minutes — works on **any** framework's tool list (plain JSON / MCP / OpenAI / Anthropic shapes). Then causal slices, context bisection, and the debugger-LLM toolpack. | Hash-chained, tamper-evident run records with an offline verifier — record-keeping in the EU-AI-Act shape. |
| [→ Quick start](#quick-start--runs-offline-no-api-key) · [→ Build ↓](#-build--design-your-agent-or-system-of-agents) | [→ Debug ↓](#-debug--see-what-your-agent-did) · [→ Tool-catalog lint](docs/guides/tool-catalog-lint.md) · [→ Trace debugging](docs/guides/trace-debugging.md) | [→ Audit ↓](#-audit--prove-what-happened) · [→ Security guide](docs/guides/security.md) |
---
## The model — what we abstract
You collect domain-specific data and instructions — **Skills · Steering · Guardrails · RAG · Tool APIs · Memory**, with more on the way. They all do one thing: **inject into one of three slots** (`system`, `messages`, `tools`). So we abstracted the injection itself.
The abstraction is three rules:
1. **Three slots are fixed.** `system`, `messages`, `tools` — the LLM API surface.
2. **N flavors are open.** You declare what you have. Tomorrow's flavor (few-shot, reflection, persona, A2A handoff…) plugs in the same way.
3. **Rules decide *where* and *when*.** You provide the rules. We collect your data, fire the right one, land it in the right slot at the right iteration.
That's the whole model: `Injection = slot × trigger × cache`.
- **Slot** — which of the 3 LLM API regions the content lands in (`system` / `messages` / `tools`).
- **Trigger** — when the content fires (see below).
- **Cache** — how stable the content is across iterations. The framework places provider cache markers for you — stable content gets 80–90% cheaper prefixes.
### The 4 triggers
| Trigger | Flavor | Fires when | Illustration | Default slot |
|---|---|---|---|---|
| `always` | static | Every iteration | `.steering(defineSteering({ id, prompt: 'You are a triage agent…' }))` | `system` |
| `rule` | runtime — predicate | Your rule returns true | `.instruction(defineInstruction({ id, activeWhen: s => /price\|refund/.test(s.userQuery), prompt }))` | `system` |
| `on-tool-return` | runtime — lifecycle | After a specific tool returns | `.instruction(defineInstruction({ id, slot: 'messages', activeWhen, prompt: 'Cite source IDs.' }))` | `messages` |
| `llm-activated` | runtime — agent-driven | LLM calls `read_skill('id')` | `.skill(defineSkill({ id: 'refund-policy', description, body, viaToolName: 'read_skill' }))` | `messages` (body) |
> [!NOTE]
> The "Illustration" column shows the shape of each flavor — the typed builder methods (`.steering` / `.instruction` / `.skill` / `.fact` / `.rag`) take an `Injection` (or `MemoryDefinition` for `.rag`) produced by the matching `defineSteering` / `defineInstruction` / `defineSkill` / `defineFact` / `defineRAG` factory. Slot is a default, not a coupling — the same `Skill` can live in `tools` (schema only, discovered via `read_skill`), `messages` (body injected on activation), or `system` (baked into the prompt as steering).
**3 slots × 4 triggers × N flavors = the entire context-engineering surface.**
---
## Why we chose this abstraction
The agent space has many credible primary abstractions:
| Framework | What it abstracts |
|---|---|
| **LangChain** | Pipelines of composable components |
| **LangGraph** | State machines of nodes and edges |
| **CrewAI · AutoGen** | Crews of role-playing agents |
| **Mastra · Genkit · Pydantic AI** | Typed full-stack bundles |
| **DSPy** | Compiled prompts |
| **Inngest AgentKit** | Durable workflows |
We didn't have to choose between them.
agentfootprint is built on **footprintjs** — the flowchart pattern for backend code. footprintjs gives us every one of those abstractions out of the box:
| Capability | What footprintjs hands us |
|---|---|
| Composition | `Sequence` · `Parallel` · `Conditional` · `Loop` |
| State machines | The ReAct loop *is* a flowchart |
| Multi-agent crews | Compose Agents through control flow — no special class needed |
| Durable workflows | `pauseHere()` plus JSON-portable `resume()` |
| Typed observation | 60+ events for free, because the framework owns the loop |
So we used the budget those abstractions would have cost us to invest deeply in something they all leave to the developer: **the injection loop.**
> [!IMPORTANT]
> **We abstract context engineering — and hand back the trace.**
> Live to develop · offline to monitor · detailed to improve.
---
## 🔧 Build — design your agent or system of agents
Two scales — same alphabet. Four control flows are the entire vocabulary.
Same five stages; only the loop edge differs. Classic returns to CallLLM with slots frozen; Dynamic (agentfootprint) returns to SystemPrompt, so injections recompose the next prompt — also the prerequisite for per-iteration caching.
Pick the flows that match your problem. Chain them. **That's your Agentic Application.**
```typescript
const research = Loop.create()
.repeat(Sequence.create().step('plan', plan).step('search', searchAll).build())
.until(({ iteration, latestOutput }) => iteration >= 3 || latestOutput.includes('DONE'))
.build();
```
### Named patterns — also compositions of the same 4
The patterns the field knows reduce to the same alphabet:
| Pattern | Composition |
|---|---|
| **Swarm** | `Loop( Parallel( Agent×N ) → merge )` |
| **Tree-of-Thoughts** | `Loop( Parallel( Agent×N ) → Conditional(score) )` |
| **Reflexion** | `Loop( Agent → Conditional(critique) → Agent )` |
| **Debate** | `Parallel( Agent_pro, Agent_con ) → Agent_judge` |
| **Router** | `Conditional → Agent_A \| Agent_B \| Agent_C` |
| **Hierarchical** | `Agent_planner → Sequence( Agent_worker×N ) → synth` |
Same trick as the injection model: instead of N libraries for N patterns, we found the M building blocks all N patterns are made of.
> 📖 Compare: [hand-rolled vs declarative](https://footprintjs.github.io/agentfootprint/docs/getting-started/why/) · [migration from LangChain / CrewAI / LangGraph](https://footprintjs.github.io/agentfootprint/docs/getting-started/vs/)
### Check in with the receipts — human consent for consequential actions
OpenWorker-class agents check in; agentfootprint checks in **with the receipts.** A tool declares `checkIn: 'always'` (or a `(args) => boolean` predicate). When it trips, the run pauses **before** the tool executes and hands back an evidence pack: `willDo` (plain-words claim), `read` (context the run consumed), `drivers` (which context drove the choice, ranked, zero LLM calls), and a compact `trail`. A human answers `checkInApproved({ by })` / `checkInDeclined({ by, note })`; on approve the tool runs, on decline the model sees the note and adapts.
```ts
const refund = defineTool({
name: 'issue_refund', description: 'Issue a refund',
inputSchema: { type: 'object', properties: { amount: { type: 'number' } } },
checkIn: (args) => args.amount > 1000, // ask a human only for big refunds
execute: ({ amount }) => `refunded ${amount}`,
});
const out = await agent.run({ message: 'refund 5000' });
if (isCheckInPause(out)) { // distinct from a plain askHuman pause
showToHuman(out.checkIn.evidence); // the receipts
await agent.resume(out.checkpoint, checkInApproved({ by: 'alice@ops' }));
}
```
It rides the same JSON checkpoint as pause/resume — the ask and the decision can be servers and days apart — and lands `checkin.request` / `checkin.decision` as typed events (`CheckInRecorder` captures the audit trail). A tool without `checkIn` is byte-identical. Permission (policy) still runs first — check-in is **consent**, not policy.
Run the flagship demo — an AI coworker that drafts a weekly status doc and checks in before posting it (deterministic $0 mock, watch it adapt on decline):
```bash
npm run example examples/features/34-checkin-coworker.ts -- --decline
```
See the [Check-in guide](https://footprintjs.github.io/agentfootprint/docs/monitor/checkin/).
---
## 🐛 Debug — see what your agent did
One real run, fully explained — the Lens (npm i agentfootprint-lens): conversation · executed path · per-step timeline · stats, every pixel from the trace.
