agentfootprint

Context engineering, abstracted.

PyTorch's autograd abstracted gradient computation. Express abstracted the HTTP request loop. Prisma abstracted SQL CRUD. Kubernetes abstracted reconciliation. React abstracted the DOM.

Every load-bearing dev tool of the last decade is the same kind of move — abstract one specific kind of bookkeeping that practitioners were doing by hand, so they can spend their attention on intent instead of plumbing.

agentfootprint is that move applied to context engineering — the discipline of deciding what content lands in which slot of an LLM call, when, and why. You describe injections declaratively. The framework evaluates every trigger every iteration, composes the system / messages / tools slots, observes every decision as a typed event, and persists checkpoints you can replay six months later. So you write the intent, not 200 lines of slot-management bookkeeping per agent.

The closest structural parallel is autograd: you describe the graph, the framework traverses it, and because the framework owns the traversal it can record everything that happens for free. Same idea here — you describe Injections, agentfootprint runs the iteration loop, and the typed-event stream + replayable checkpoints are a consequence, not an extra feature.

The abstraction, concretely

Without agentfootprint — context engineering by hand

async function runAgentTurn(userMsg, state) {
  let systemPrompt = baseSystem;
  const messages = [...state.history, { role: 'user', content: userMsg }];
  let activeTools = [...baseTools];

  // 1. Apply always-on steering rules
  for (const rule of steeringRules) systemPrompt += '\n' + rule.text;

  // 2. Evaluate conditional instructions
  for (const inst of instructions) {
    if (inst.activeWhen(state)) systemPrompt += '\n' + inst.prompt;
  }

  // 3. Check on-tool-return triggers
  if (state.lastToolResult?.toolName === 'redact_pii') {
    messages.push({ role: 'system', content: 'Use redacted text only.' });
  }

  // 4. Resolve LLM-activated skills
  for (const id of state.activatedSkills) {
    systemPrompt += '\n' + skills[id].body;
    activeTools.push(...skills[id].tools);
  }

  // 5. Load + format memory for this tenant
  const memEntries = await store.list({ tenant, conversationId });
  messages.unshift({ role: 'system', content: formatMemory(memEntries.slice(-10)) });

  // 6. Call LLM, route tool calls, loop, capture state for resume...
  // 7. Persist new turn back to memory tagged with identity...
  // 8. Wire SSE for streaming, attach observability hooks...

  // No replay. No audit trail. Per agent, hundreds of lines.
  // Every refactor risks a slot-ordering bug nobody catches until prod.
}

With agentfootprint — declarative

const agent = Agent.create({ provider, model: 'claude-sonnet-4-5-20250929' })
  .system('You are a support assistant.')
  .steering(toneRule)            // always-on
  .instruction(urgentRule)       // rule-gated
  .skill(billingSkill)           // LLM-activated
  .memory(conversationMemory)    // cross-run, multi-tenant
  .tool(weather)
  .build();

await agent.run({ message: userInput, identity: { conversationId } });

// Every iteration is a replayable typed event stream — for free.
agent.on('agentfootprint.context.injected', (e) =>
  console.log(`[${e.payload.source}] landed in ${e.payload.slot}`));

Same agent. The hand-rolled version is ~80 lines and growing; the declarative version is ~8 and stable. The framework owns the wiring — which is exactly why it can observe, replay, and audit it for you.

In 30 seconds — runs offline, no API key

npm install agentfootprint footprintjs

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.' }),  // ← deterministic, no API key
  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."

Swap mock(...) for anthropic(...) / openai(...) / bedrock(...) / ollama(...) for production. Nothing else changes.

The mental model — three slots, four triggers, one Injection

Every LLM call has three slots. Every "agent feature" — Skill, Steering doc, Instruction, Fact, Memory replay, RAG chunk — is content flowing into one of them, under one of four triggers. That's the entire abstraction.

                       ┌─────────────────────────────────────┐
                       │                                     │
                       │    Your LLM call has 3 slots:       │
                       │                                     │
                       │    system    messages    tools      │
                       │       ▲          ▲          ▲       │
                       └───────┼──────────┼──────────┼───────┘
                               │          │          │
                               │   one    │   one    │
                               │ Injection│ Injection│
                               │  fires…  │  fires…  │
                               │          │          │
                ┌──────────────┴────┐  ┌──┴───┐  ┌──┴────┐
                │ defineSteering     │  │ ...  │  │ ...   │
                │ defineInstruction  │  │      │  │       │
                │ defineSkill        │  │      │  │       │
                │ defineFact         │  │      │  │       │
                │ defineMemory(read) │  │      │  │       │
                │ defineRAG          │  │      │  │       │
                │   …your next idea  │  │      │  │       │
                └────────────────────┘  └──────┘  └───────┘
                          ▲
                   …under one of:
                  always · rule · on-tool-return · llm-activated

There's no fourth slot. There won't be. Every named pattern in the agent literature — Reflexion, Tree-of-Thoughts, Skills, RAG, Constitutional AI — reduces to which slot + which trigger. You learn one model; the field's growth lands as new factories on the same primitive.

The four triggers — who decides this injection is needed right now?

Why exactly four? Because who decides activation is a closed axis: nobody / the developer / the system / the LLM. Together those four exhaust the meaningful "when does this content matter?" cases. A fifth would require introducing a new agent of decision — and there isn't one. That's why the primitive surface stays this small even as named patterns proliferate above it.

Why this isn't just an ergonomics win — Dynamic ReAct

The React parallel goes one layer deeper than "less code." Because the framework owns the loop, the framework recomposes the prompt + tool list every iteration based on what just happened. That's what we call Dynamic ReAct — and it's the thing other agent frameworks don't do.

LangChain assembles prompts once per turn. LangGraph composes state per node, not per loop iteration. CrewAI's Agent is tool-aware but not iteration-aware. Per-iteration recomposition of all three slots based on the latest tool result + accumulated state is structurally distinct. It's the closest a framework comes to "executive-function-like" behavior — context that adapts to what the agent just observed, not just what it was originally told.

What "every iteration" makes possible

Use cases that emerge once the loop re-evaluates everything:

The framework owns the loop. The framework re-evaluates triggers every iteration. Tool results reshape the next iteration's prompt. That's what makes context engineering compositional instead of static.

The flowchart-pattern substrate (footprintjs) is what makes the observation automatic. Every stage execution is a typed event during one DFS traversal — no instrumentation, no post-processing. Same way React DevTools shows you the component tree because React owns the render path, agentfootprint shows you the slot composition because agentfootprint owns the prompt path.

Side-by-side: classic vs Dynamic ReAct

examples/dynamic-react/ ships two mock-backed scripts solving the same SRE task with the same scripted answers. Per-iteration tool-count progression makes the shape clear:

Classic ReAct                    Dynamic ReAct
───────────────                  ─────────────
iter 1: 12 tools shown           iter 1: 1 tool  (read_skill)
iter 2: 12 tools shown           iter 2: 5 tools (skill activated)
iter 3: 12 tools shown           iter 3: 5 tools
iter 4: 12 tools shown           iter 4: 5 tools
                                 iter 5: 5 tools (final answer)

The two unactivated skills' 8 tools never enter the LLM context. Classic ReAct has no equivalent: every registered tool ships on every call.

Real Anthropic benchmark — 3 models × 2 modes

We ran a real production-shaped agent (10 skills, 18 tools after dedup) against Anthropic with Haiku 4.5, Sonnet 4.5, and Opus 4.5 in both modes. Same prompt, same scenario data, real usage.input_tokens:

Reality check: at Neo's 18-tool / 10-skill scale, Dynamic ReAct's total input-token cost depends on how aggressively the model parallelizes Classic mode. Opus parallelizes best (3 iters, all data tools in one round) so Classic minimizes iterations and wins. Sonnet went serial that turn (5 iters) so Dynamic won. Haiku parallelized well (4 iters) so Classic won.

Classic mode is shape-variable (3–5 iters depending on model mood). Dynamic stays predictable at 5–6 iters across all models.

What Dynamic ReAct WINS even when it loses on raw tokens

1. Constant per-call payload: [2, 2, 6, 6, 6] for Dynamic vs [18, 18, 18] for Classic, regardless of registry size. Scales to 50+ tool catalogs without ballooning per-call cost.
2. Deterministic routing: read_skill forces scope before data tools fire. LLM can't drift to off-topic tools.
3. Auditability: each iteration's tool list is a function of activatedInjectionIds — recorded, replayable, diff-able across runs. Classic mode has no equivalent artifact.
4. Predictable cost: Dynamic varies <5% across model sizes (28K-36K). Classic varies 80%+ run-to-run depending on parallelization.

Where Dynamic ReAct WILL win on cost

The break-even is roughly 30+ tools across 8+ skills. Below that, classic mode often wins on raw tokens. Above it, Dynamic dominates because Classic's tool-description payload grows linearly with the catalog while Dynamic stays flat at active-skill size:

Classic ReAct:   5 iters × 50 tools             = 250 descriptions
Dynamic ReAct:   1 iter  × 1 tool  (read_skill)
               + 4 iters × 5 tools (1 active)   =  21 descriptions
                                                  ────────────
                                                  −92% on tool payload

Plus the second-order win: fewer tools per call → LLM less likely to hallucinate or pick the wrong tool. Narrower context = more in-distribution on the active task. Increasingly load-bearing as catalogs grow.

Run the side-by-side yourself:

TSX_TSCONFIG_PATH=examples/runtime.tsconfig.json npx tsx examples/dynamic-react/01-classic-react.ts
TSX_TSCONFIG_PATH=examples/runtime.tsconfig.json npx tsx examples/dynamic-react/02-dynamic-react.ts

Or for the real-Anthropic version, see scripts/run-comparison.ts in the Neo repo.

What you can build

Three example shapes, all runnable end-to-end with npm run example examples/<file>.ts.

Customer support agent (skills + memory + audit trail)

const agent = Agent.create({ provider, model: 'claude-sonnet-4-5-20250929' })
  .system('You are a friendly support assistant.')
  .skill(billingSkill)        // LLM activates with read_skill('billing')
  .steering(toneGuidelines)   // always-on
  .memory(conversationMemory) // remembers across .run() calls, per-tenant
  .build();

→ examples/context-engineering/06-mixed-flavors.ts

Research pipeline (multi-agent fan-out + merge)

const research = Parallel.create()
  .branch(optimist).branch(skeptic).branch(historian)
  .merge(synthesizer)
  .build();

await research.run({ message: 'Should we adopt microservices?' });

→ examples/patterns/05-tot.ts (Tree-of-Thoughts) · examples/patterns/01-self-consistency.ts

Streaming chat agent (token-by-token to a browser)

agent.on('agentfootprint.stream.token', (e) => res.write(e.payload.content));
agent.on('agentfootprint.stream.tool_start', (e) => res.write(`\n→ ${e.payload.toolName}...\n`));
await agent.run({ message: userInput });

→ docs-site/guides/streaming/

The differentiator: the trace is a cache of the agent's thinking

Other agent frameworks' memory remembers what was said. agentfootprint's defineMemory({ type: CAUSAL }) records the decision evidence — every value the agent's flowchart captured during the run, persisted as a JSON-portable snapshot.

That changes the cost structure of everything that happens after the agent runs. The expensive thinking happened once; the recorded trace makes consuming that thinking cheap, three different ways:

1. Audit / explain — cross-run, six months later, exact past facts

const causal = defineMemory({
  id: 'causal',
  type: MEMORY_TYPES.CAUSAL,
  strategy: { kind: MEMORY_STRATEGIES.TOP_K, topK: 1, threshold: 0.7, embedder },
  store,
  projection: SNAPSHOT_PROJECTIONS.DECISIONS,  // inject "why" only, not "what"
});

// Monday: agent decides loan #42 should be rejected (creditScore=580, threshold=600).
// Friday: user asks "Why was my application rejected?"
// → Causal memory loads the exact decision evidence from Monday.
// → LLM answers from the SOURCE, not reconstruction.

→ examples/memory/06-causal-snapshot.ts — runs end-to-end with mock embedder, ~50 lines.

2. Cheap-model triage — the trace is the reasoning

A trace recorded from your expensive production model (Sonnet-4, GPT-4) is a perfectly good input for a small, fast, cheap model (Haiku, GPT-4o-mini) answering follow-up questions about that run. The expensive model already did the work; the cheap model just reads what's in the trace.

Reading recorded decision evidence is structurally simpler than re-deriving the answer from first principles — so a smaller model is enough. You can compose the routing yourself: when causal memory injected a snapshot on the next turn, send that turn to a cheaper provider.

const heavy = anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
const cheap = anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

// Production turn — heavy model, full reasoning, snapshot persisted.
const productionAgent = Agent.create({ provider: heavy, model: 'claude-sonnet-4-5-20250929' })
  .memory(causal)
  .build();
await productionAgent.run({ message: 'Should we approve loan #42?', identity });

// Follow-up turn — cheaper model reads the snapshot, lower cost per turn.
const followUpAgent = Agent.create({ provider: cheap, model: 'claude-haiku-4-5-20251001' })
  .memory(causal)
  .build();
await followUpAgent.run({ message: 'Why was loan #42 rejected?', identity });

This is memoization for agent reasoning — do the expensive work once, serve many queries from the cached result. Across a production system that handles audit / explain / "why did the agent do X?" traffic, this is real money.

3. Training data — every successful run becomes a labeled trajectory

The same snapshot data shape is the input to SFT / DPO / process-RL training pipelines (causalMemory.exportForTraining({ format: 'sft' | 'dpo' | 'process' }) is on the roadmap — see below). You don't run a separate data-collection phase — your production traffic IS your training set. Every successful customer interaction is a positive trajectory; every escalation or override is a counter-example.

The same JSON shape that powered the audit trail and the cheap-model follow-up is the training payload. One recording, three downstream consumers, no extra instrumentation.

Mocks first, prod second

Generative AI development is expensive when every iteration hits a paid API. agentfootprint is designed so you build the entire app — agent, context engineering, memory, RAG — against in-memory mocks, prove the logic end-to-end with zero API cost, then swap real infrastructure in one boundary at a time.

The flowchart, recorders, narrative, and tests don't change between dev and prod. Ship the patterns first; pay for tokens last.

Pick your starting door

Every code snippet on the docs site is imported from a real, runnable file in examples/ — every example is also an end-to-end test in CI. There is no docs-only code in this repo.

What ships today

• 2 primitives — LLMCall, Agent (the ReAct loop)
• 4 compositions — Sequence, Parallel, Conditional, Loop
• 6 LLM providers — Anthropic · OpenAI · Bedrock · Ollama · Browser-Anthropic · Browser-OpenAI · Mock (with mock({ replies }) for scripted multi-turn)
• One Injection primitive — defineSkill / defineSteering / defineInstruction / defineFact (one engine, four typed factories, all reduce to { trigger, slot })
• One Memory factory — defineMemory({ type, strategy, store }) — 4 types × 7 strategies including Causal
• RAG — defineRAG() + indexDocuments() (sugar over Semantic + TopK)
• MCP — mcpClient({ transport }) for real servers · mockMcpClient({ tools }) for in-memory development
• Memory store adapters — InMemoryStore · RedisStore (subpath agentfootprint/memory-redis) · AgentCoreStore (subpath agentfootprint/memory-agentcore)
• 47 typed observability events across 13 domains — context · stream · agent · cost · skill · permission · eval · memory · …
• Pause / resume — JSON-serializable checkpoints; pause via askHuman / pauseHere, resume hours later on a different server
• Resilience — withRetry, withFallback, resilientProvider
• AI-coding-tool support — bundled instructions for Claude Code · Cursor · Windsurf · Cline · Kiro · Copilot
• Runnable examples organized by DNA layer (core · core-flow · patterns · context-engineering · memory · features) — every example is also an end-to-end CI test

What's next (clearly marked roadmap)

For shipped features per release see CHANGELOG.md. Roadmap items are not claims about the current API — if a feature isn't in npm install agentfootprint today, it's listed here, not in the documentation.

Built on

footprintjs — the flowchart pattern for backend code. The decision-evidence capture, narrative recording, and time-travel checkpointing this library uses are footprintjs primitives. The same way autograd's forward-pass traversal is what makes gradient inspection automatic, footprintjs's flowchart traversal is what makes agentfootprint's typed-event stream and replayable traces automatic. You don't need to learn footprintjs to use agentfootprint — but if you want to build your own primitives at this depth, start there.

License

MIT © Sanjay Krishna Anbalagan