简介

Agentfootprint

<p align="center"> <strong>Your agent gave an answer that <em>looks</em> right — and it's wrong.<br/>The logs can't tell you who influenced it. Agentfootprint can.</strong> </p>

<p align="center"> The explainable AI agent framework for TypeScript: every read, write, decision, and tool call becomes <strong>connected evidence</strong> as your agent runs. When something goes wrong, you don't grep logs — you ask. </p>

<p align="center"> <strong>Build</strong> agents — skills, steering, RAG, memory, control flow — and <strong>debug</strong> them like nothing else.<br/> <em>Why</em> is a query, not a guess. </p>

<p align="center"> <a href="https://footprintjs.github.io/agentThinkingUI/"> <img src="docs/assets/hero-atui.png" alt="An agent run replayed in Story Lens — the LLM 'brain' calls the Flight-search tool, the step inspector shows the tool's raw output and the brain's reasoning about it, and the timeline scrubs every step of the run." width="100%"> </a> </p> <p align="center"> _{A real run, replayed — rendered with <a href="https://github.com/footprintjs/agentThinkingUI"><b>Story Lens</b></a> (<code>npm i agentthinkingui</code>). Every frame is generated from the run's own trace; <a href="https://footprintjs.github.io/agentThinkingUI/">▶ watch it live</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> <img src="https://img.shields.io/badge/coverage-87%25-green.svg" alt="coverage: 87%"> <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>

---

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.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/assets/hero-light.svg"> <img alt="agentfootprint mascot composing context flavors (Skills, Steering, Guardrails, RAG, Tool APIs, Memory) into three structured LLM slots (system, messages, tools) — the central abstraction, visualized." src="docs/assets/hero-light.svg" width="100%"/> </picture> </p> <p align="center"> _{<em>One primitive: <code>Injection = slot × trigger × cache</code>. Because the framework owns this point, every piece of context is <b>born tracked</b> — observability isn't wired up, it's a consequence of the abstraction. <a href="#the-model--what-we-abstract">The full model ↓</a></em>} </p>

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.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/triggers-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/assets/triggers-light.svg"> <img alt="agentfootprint — Every LLM call has 3 fixed slots (system, messages, tools). Every flavor lands in one slot under one of 4 fixed triggers (always · rule · on-tool-return · llm-activated). Sparkle streams flow from each trigger lane down to a specific pill inside its destination slot — same slot can hold pills from different triggers (RAG via rule, Instruction via on-tool-return), and the same flavor (Skill) can land in different slots." src="docs/assets/triggers-light.svg" width="100%"/> </picture> </p>

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.

Why we chose this abstraction

The agent space has many credible primary abstractions:

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:

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.

---

Act — everything your agent does about its own loop, in one block

Tools do the work. Act decides about the work. Watch remembers both — and nothing can act without being watched.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/loop-moments-dark.svg"> <source media="(prefers-color-scheme: light)" srcset="docs/assets/loop-moments-light.svg"> <img alt="One agent turn drawn as a circle. The message enters through the INPUT gate; the loop runs clockwise past the WINDOW gate (what the live context keeps), the context slots and the model call, the BEFORE-TOOL gate (every call, before dispatch), the tool actually running, the AFTER-TOOL gate (every result, before the model reads it) and the end of the iteration; the answer leaves through the OUTPUT gate. Five amber gates are the moments .act() can change; purple watch-dots sit at every moment, including the ones with no gate, because watch attends all of them and cannot be switched off." src="docs/assets/loop-moments-light.svg" width="100%"/> </picture> </p>

const agent = Agent.create({ provider, model })
  .act({
    input:      [scrubSSNs],                            // the message, before the run commits it
    beforeTool: [refundCeiling, fourEyes],              // every call, before it is dispatched
    afterTool:  [stripPII],                             // every result, before the model reads it
    window:     slidingWindow({ keepRecentTurns: 12 }), // what the live window keeps
    output:     [noCodenames],                          // the answer, before the caller gets it
  })
  .build();

Five keys, one per moment, in the order the loop reaches them — so autocomplete on an empty {} teaches the loop. Every rule answers allow(), allow(value, why) or deny(reason) (and ask({ question }) where a person can still change the outcome), and none of them can answer for the tool: the outcome union has no result arm, so what the model finally reads is the real tool's output or a refusal. Every decision files a ledger row stamped with its moment.

It is pure sugar over the five individual doors, pinned byte-equivalent per key — and the bundle's keys are locked against LoopMoment at compile time, so a sixth moment cannot ship without a key for it.

npm run example examples/features/38-act.ts

See The moments of the loop.