# AgentFootprint

> Build TypeScript agents you can hold to the record: state the rules, trace the run, assess the claims, name the answer’s standing and decide what happens.

- Website: https://agentfootprint.dev/
- Source: https://github.com/footprintjs/agentfootprint
- npm: https://www.npmjs.com/package/agentfootprint
- Creator: Sanjay Krishna Anbalagan (https://github.com/sanjay1909)

## Product and technical views

- Product: https://agentfootprint.dev/?view=product
- Technical: https://agentfootprint.dev/?view=technical

## footprintjs ecosystem

AgentFootprint is one of seven connected open-source projects. Each records or presents causal evidence at a different layer.

- **footprintjs** — Execution provenance for backend systems, with typed reads and writes, decision evidence, backward slicing, and replay. [website](https://footprintjs.github.io/footPrint/) · [source](https://github.com/footprintjs/footPrint) · [npm](https://www.npmjs.com/package/footprintjs)
- **AgentFootprint** — A TypeScript agent framework connecting recorded execution, declared evidence limits and app-configured checks before answer delivery. [website](https://agentfootprint.dev/) · [source](https://github.com/footprintjs/agentfootprint) · [npm](https://www.npmjs.com/package/agentfootprint)
- **HACI Footprint** — A typed capability and action graph that makes applications agent-operable while preserving permissions and human control. [website](https://footprintjs.github.io/hcifootprint/) · [source](https://github.com/footprintjs/hcifootprint) · [npm](https://www.npmjs.com/package/hcifootprint)
- **VizFootprint** — Branchable provenance for human-agent visual analysis, with replay, comparison, mixed-principal causes, and statistical accountability. [website](https://github.com/footprintjs/vizfootprint) · [source](https://github.com/footprintjs/vizfootprint)
- **Explainable UI** — Themeable React components for flowchart traversal, transactional state, time travel, and causal rewind. [website](https://footprintjs.github.io/explainable-ui/) · [source](https://github.com/footprintjs/explainable-ui) · [npm](https://www.npmjs.com/package/footprint-explainable-ui)
- **AgentFootprint Lens** — A React debugger that aligns agent messages, prompts, tools, decisions, causal slices, and cost on one execution cursor. [website](https://github.com/footprintjs/agentfootprint-lens) · [source](https://github.com/footprintjs/agentfootprint-lens) · [npm](https://www.npmjs.com/package/agentfootprint-lens)
- **Thinking UI** — A scrubbable replay of agent reasoning, evidence, tools, and alternatives for non-developer audiences. [website](https://footprintjs.github.io/agentThinkingUI/) · [source](https://github.com/footprintjs/agentThinkingUI) · [npm](https://www.npmjs.com/package/agentthinkingui)

# Docs

- [agentfootprint](/docs): Find the context that made your agent answer wrong.
- Get Started
  - [Quick Start](/docs/getting-started/quick-start): Build your first agent in 5 minutes — and add memory in 5 more.
  - [Why agentfootprint?](/docs/getting-started/why): Agents can fail with correct code because of the context the model saw. agentfootprint records it, so you can trace a wrong answer and hold the next to the record.
  - [Key Concepts](/docs/getting-started/key-concepts): The 5-layer taxonomy. 2 primitives, 4 compositions, N patterns, the Injection cross-cut, infrastructure. Once these are in your head, every agent paper and every framework can be located on the grid.
  - [vs Other Frameworks](/docs/getting-started/vs): How agentfootprint differs from LangChain, LangGraph, CrewAI, Mastra, Pydantic AI and others, read from their docs, with migration notes.
- Build

  - **Primitives**
  - [Agent](/docs/build/agent): Agent = ReAct. The loop primitive that thinks, acts (tool call), observes the result, and repeats until done.
  - [Recipes — an agent setup you can name](/docs/build/recipes): defineAgentRecipe declares an agent's whole setup as one named, versioned AgentRecipe, and .recipe() applies it. Every run then says on its manifest which composition produced the agent that answered.
  - [Conversations](/docs/build/conversations): agent.run() is one turn and starts a new conversation every time. agent.followUp(message) continues this agent's; run({ message, continueFrom }) continues one you are holding. Plus the three things that look like conversation memory and are not.
  - [Dynamic ReAct](/docs/build/dynamic-react): Context that adapts mid-loop. The on-tool-return trigger fires the iteration after a specific tool ran — recency-first injection without hand-rolled state.
  - [Swarm](/docs/build/swarm): A bounded native chart that routes a message to specialists and carries each returned decision inside its invocation.
  - [Patterns](/docs/build/patterns): Reflection, Tree of Thoughts, Self-Consistency, Debate, Map-Reduce and Swarm — each a small factory over the same primitives, so they compose with each other and with your own flows.
  - [LLM routing](/docs/build/llm-router): llmRouter returns a typed routing decision through a native runner. llmSwarm mounts it beside the specialists and keeps each decision in its own invocation.
  - [Workflow](/docs/build/workflow): workflow() chains 1–8 runners where step N's output type must be step N+1's input type. Structured values survive the hand-off, and a chain that does not line up is a compile error.
  - [Graph](/docs/build/graph): graph() runs a fixed DAG of runners. Independent nodes run concurrently, an edge carries the producer's output unchanged, and a broken shape — a cycle, an unknown edge, an un-joined fan-in — is refused at build time.

  - **Context engineering**
  - [Visual context walkthrough](/context-engineering)
  - [Instructions](/docs/build/instructions): Rule-gated context injection. The Instruction primitive activates a prompt when a predicate matches the current iteration's context.
  - [Compaction](/docs/build/compaction): Keep the live context window inside a token budget by folding the oldest turns into a summary — while the commit log keeps every folded turn, byte for byte.
  - [Window strategies](/docs/build/window-strategies): Three ways to keep the live context window inside its budget — summarize, slide, or drop on a token budget — sharing one refusal engine and one ledger, so every strategy records what it removed, by id.
  - [Skills](/docs/build/skills): defineSkill — LLM-activated body + tools. The LLM calls read_skill('billing') to load a body of guidance for the rest of the turn; autoActivate scopes the skill's tools to that window too. The shipped Skills surface today; full conceptual essay in skills-explained.
  - [Skill graph in 5 minutes](/docs/build/skill-graph-quickstart): Three defineSkill calls, one skillGraph({ skills, start }) — routing declared as data, checked at build, and drawn as a picture you can read.
  - [Skill graph architecture](/docs/build/skill-graph-architecture): The three surfaces, the authority rule, and the cursor as a program counter — every claim carrying a status, and one worked refusal taken from a real run.
  - [Skills, explained](/docs/build/skills-explained): Skills are context engineering for instructions — abstracted so you don't do it by hand and get it wrong. A conceptual walk through what they actually are, and why the abstraction exists.
  - [Mounted maps](/docs/build/mounted-maps): An agent can be fed by more than one walkable map. Each map owns its cursor; the mount kernel owns only engagement — whether a map's prompt fragment and tools ride the next call at all.
  - [Tools](/docs/build/tools): defineTool — flat builder for the Tool interface. JSON schema in, async execute out. Drop into agent.tool() or pull a whole MCP server's surface via agent.tools().
  - [Findings reference admission](/docs/build/findings-admission): Refuse citations that the accepted model request did not serve, without using another model.
  - [Artifacts](/docs/build/artifacts): The claim-check store and the data legs — tools check data in and the model routes ~26-char tickets. ctx.artifacts, wants (refs as tool arguments), the present tool, the placement threshold, typed lifecycle events.
  - [Artifact architecture](/docs/build/artifacts-architecture): The five-verb port, the three dispatch legs, and what a ref is allowed to move — every claim carrying a status, three named gaps, and one worked refusal taken from a real run.
  - [Tool providers](/docs/build/tool-providers): staticTools + gatedTools — chainable tool dispatch primitives. Compose permission gating + per-skill tool filtering at the dispatch boundary, not inside each tool's execute.
  - [Tool discovery (async ToolProvider)](/docs/build/tool-discovery): Runtime tool catalogs over hubs, MCP registries, and per-tenant indexes. Async ToolProvider.list(ctx) with TTL caching, AbortSignal propagation, and discovery_started/completed/failed events — no library API additions required.
  - [Connect to an MCP server](/docs/build/mcp-client): mcpClient({ transport }) turns any MCP server's tools into agentfootprint Tool[]. Sign every request with your own fetch, read servers old enough to answer the 2024-10-07 shape, and govern by the server a tool came from.
  - [A client per conversation](/docs/build/mcp-client-pool): mcpClientPool() keeps one MCP client per authenticated conversation for one server — opened once, bounded, never closed while a call is in flight, and ended remotely with the outcome reported.
  - [Serve your tools over MCP](/docs/build/mcp-serve): mcpServe(tools, opts) exposes agentfootprint Tool[] AS an MCP server — stdio or Streamable HTTP. Schemas map 1:1, the served tool is the same object you passed in, so the governance you wrapped around it still runs.
  - [Sequence governance (recipe)](/docs/build/sequence-governance): Build sequence-aware tool governance on the v2.12 PermissionChecker — security (exfil chains), cost (wasteful patterns), correctness (idempotency caps). Same plug point as single-call permission, no new factory.
  - [The moments of the loop](/docs/build/loop-moments): Every place in an agent turn where a rule may speak, what watch reports there, and what act may change. One block — .act({ input, beforeTool, afterTool, window, output }) — with keys locked to the moments at compile time.
  - [Middleware](/docs/build/middleware): A typed chain around every tool dispatch and around the message boundary. Three verbs — allow, deny, ask — and no way to return a result, so the answer the model reads is always the real tool's or a refusal.
  - [Runbook as tool](/docs/build/runbook-as-tool): Turn a written operational procedure into one agent tool whose every answer is evidence — coverage, provenance, rule version, and the recorded walk — instead of a pile of logs.
  - [Runbooks inside a fan-out](/docs/build/runbooks-inside-a-fan-out): Six engine behaviours a decision chart meets the first time it runs one branch per subject. A branch is seeded with only item and index, a decider reports itself path-prefixed by name, and four of the six fail without an error — the run finishes, the rowset looks complete, and the answer is wrong.
  - [Flowchart as tool](/docs/build/flowchart-as-tool): Wrap a footprintjs FlowChart as one Agent tool. Compose existing multi-step procedures (decision evidence, branches, loops, pause/resume) into the LLM's tool surface — no flatten/restructure required.
  - [Output schema](/docs/build/output-schema): Declarative terminal contract for an Agent's final answer. The schema serves three jobs at once — instruct the LLM, parse + validate, type-narrow at the call site.
  - [Strict output (Instructor-style schema retry)](/docs/build/strict-output): Wire outputSchema validation INTO the reliability gate so failed validations re-prompt the model within the current turn — without burning a full ReAct loop iteration. New helpers, ephemeral-message handling, and stuck-loop detection.
  - [Grounding](/docs/build/grounding): Reduce hallucination by giving the LLM the source material — and recording what it produced vs what it was given. The trace IS the grounding evidence.
  - [Names and numbers from evidence](/docs/build/evidence-gate): Every number, identifier and name in the final answer must appear in a tool result the run really read. If one does not, the model typed it rather than read it — a deterministic check, no second model.
  - [Negative claims](/docs/build/negative-claims): Observe prose claims or deliver library-written typed statements, with the search scope and gaps preserved.
  - [Described tool results](/docs/build/semantic-results): describedResult() — a tool returns rows, a series or relationships as typed data, with grain, freshness and coverage traveling with the numbers; a build gate refuses a triage tool that forgets its caveats, by name.
  - [Time](/docs/build/time): One declared clock per run, the person's words read by a strategy you arm, tool periods written exactly or refused with a reason — every step recorded.

  - **Memory**
  - [Memory](/docs/build/memory): One factory, four types, seven strategies. Persistent context across agent runs — observable, swappable, multi-tenant.
  - [Auto memory (Hybrid)](/docs/build/auto-memory): Compose multiple memory layers — recent window + extracted facts + causal snapshots — each as its own .memory() call. Production-grade memory stack in ~30 lines.
  - [Fact extraction (Semantic memory)](/docs/build/fact-extraction): Distill structured facts from raw conversation. Pattern-based (free, regex) or LLM-based (richer). The right shape when you want to remember "what's true about this user" without replaying every word.
  - [Narrative memory (Summarization)](/docs/build/narrative-memory): Compress long conversations into beats. Older turns are LLM-summarized into a shorter narrative; recent turns stay raw. Trades one cheap LLM call per write for token savings on every read.
  - [Semantic retrieval (Top-K)](/docs/build/semantic-retrieval): Cosine-similarity search over embedded entries. Returns the most relevant top-K above a strict threshold — the read-side primitive behind RAG.
  - [Embedders](/docs/build/embedders): openaiEmbedder, bedrockEmbedder, geminiEmbedder, localEmbedder and staticEmbedder — ready-made Embedder implementations. What each one needs, which ones run in a browser, and what they cost.
  - [RAG](/docs/build/rag): defineRAG — sugar over defineMemory(SEMANTIC + TOP_K) with retrieval-friendly defaults. Chunks land in the system-prompt slot when cosine similarity clears the threshold.
  - [Indexing a corpus](/docs/build/indexing): agentfootprint/rag — loaders, splitters and the indexing chart. A folder of documents becomes a searchable index, and the run explains itself.

  - **Providers**
  - [Anthropic](/docs/build/anthropic): anthropic() — Claude provider via @anthropic-ai/sdk. Lazy-loaded peer-dep; install when you use it.
  - [OpenAI](/docs/build/openai): openai() — GPT provider via the openai SDK. Also covers OpenAI-compatible endpoints (Ollama, llama.cpp, vLLM, Together, Groq, LM Studio) via baseURL, the legacyEndpoint dial that declares which dialect such a URL speaks, and azureOpenai() with either an API key or a keyless Entra credential.
  - [AWS Bedrock](/docs/build/aws-bedrock): bedrock() — model-agnostic provider via AWS Bedrock's Converse API. One adapter covers Claude, Llama, Mistral, Titan, Mixtral on Bedrock.
  - [Your gateway (InvokeModel)](/docs/build/invoke-model-gateway): invokeModelGateway() — Anthropic models behind your organisation's gateway that forwards the Bedrock InvokeModel operation over plain HTTPS with an API-key header. Streaming, tool calls, a key per model, typed errors.
  - [Gemini](/docs/build/gemini): gemini() — Google's models through the native @google/genai SDK, on Vertex or the Gemini API. Honest cached- and thinking-token counts, JSON Schema tools with no OpenAPI translation, and a forced single tool that is actually forced.
  - [Ollama](/docs/build/ollama): ollama() — run a real model on your laptop. Free, no API key, no vendor SDK. The middle rung between mock() and a paid API, with the same agent code on all three.
  - [Custom provider](/docs/build/custom-provider): Implement the LLMProvider interface to wrap any LLM API. Two methods (complete, stream) — that's the whole contract.
  - [Prompt caching](/docs/build/caching): Stable context — steering, facts, an active skill — is cached for you on providers that support it, per a policy you can override on each injection. On by default; one flag turns it off.

  - **Run it somewhere**
  - [Infrastructure: ports & adapters](/docs/infrastructure)
  - [Memory stores](/docs/infrastructure/memory-and-stores)
  - [AWS & Bedrock AgentCore](/docs/infrastructure/aws)
  - [Google Cloud & Gemini](/docs/infrastructure/google-cloud)
  - [On-premises](/docs/infrastructure/on-premises)
- Infrastructure
  - [Infrastructure — ports & adapters](/docs/infrastructure): agentfootprint is framework-side. Everything that touches your infrastructure — memory, identity, hosting, tools, telemetry — is a PORT with swappable ADAPTERS. This is the translation boundary, the one decision table, and the honest status of every adapter that ships.

  - **State**
  - [Memory & stores](/docs/infrastructure/memory-and-stores): The MemoryStore port — eleven required members, one optional method, and two declared capability bits. Seven adapters with their supported and missing operations stated honestly, the strategy axes that sit above them, and what each store's search() actually ranks.
  - [Sessions in a file — survive a restart with nothing to install](/docs/infrastructure/sqlite): sqliteSessions({ file }) is the SessionLifecycle port backed by Node's built-in node:sqlite. Conversations and runs paused waiting on a person live in one table, so a restart, a crash or a deploy does not lose them. Zero dependencies, one machine, one file — and a loud refusal instead of a silent fallback.

  - **Identity & governance**
  - [Identity & credentials](/docs/infrastructure/identity-and-credentials): The CredentialProvider port — one method. A tool declares what it needs; the framework resolves it before the tool runs and hands it over as ctx.credential. Machine vs user is decided per REQUEST, consent pauses by default, and a vended token never enters the trace.
  - [Governance & policy](/docs/infrastructure/governance-and-policy): Four places a tool call can be stopped — visibility, the in-process permission gate, the middleware chain, and a gateway upstream where this library has nothing to attach. What enforces what, the exact refusal each one hands the model, and how to replace the removed agentCorePolicy adapter.

  - **Runtime & tools**
  - [Hosting & runtime](/docs/infrastructure/hosting-and-runtime): The ports between an agent and the place it runs — AgentHost, ConversationHost and SessionLifecycle, none of which names a cloud. Plus httpHost/HttpWire for a second HTTP adapter, three reply terminals, three durability modes with stated crash semantics, the human-in-the-loop resume loop, and the three ways to serve many people at once.
  - [AG-UI frontends](/docs/infrastructure/ag-ui): Serve any agentfootprint agent to AG-UI frontends with no glue code — one Fetch-API handler that treats every request as untrusted, keeps the conversation on the server, and streams text, tool calls, steps, sub-agents and interrupts as AG-UI 1.0 events with nothing a redaction policy hides on the wire.
  - [Writing a session store](/docs/infrastructure/session-stores): The ownership rule every SessionLifecycle store must hold, and the shared battery that checks it — runSessionLifecycleConformance, 18 cases, three deliberately distinct non-pass outcomes, and no way to make a case quietly disappear. For anyone implementing the port over Postgres, DynamoDB, SQL Server or anything else.
  - [Tools & gateways](/docs/infrastructure/tools-and-gateways): The McpClient port — four members, three transports. Where a tool comes from is a transport decision (stdio, fixed HTTP headers, per-request vending, or your own signing fetch); what a tool is allowed to do is a governance decision, and they compose without knowing about each other.

  - **Telemetry**
  - [Observability sinks](/docs/infrastructure/observability-sinks): The ObservabilityStrategy port — one required hot-path method that must be sync and must not throw. Compose several sinks into one, choose when delivery happens, and know exactly what a recording keeps and what it summarizes away.

  - **Providers**
  - AWS
    - [AWS & Bedrock AgentCore](/docs/infrastructure/aws): The first worked provider. Every AWS service agentfootprint adapts — Memory, Identity, Runtime hosting, Gateway MCP, Observability, Policy, S3 Vectors, Bedrock models and embedders — with its adapter, its door, its peer dependency, the SDK commands it dispatches, and its honest status.
    - [AgentCore: step by step](/docs/infrastructure/aws/agentcore-setup): A hands-on walkthrough — build the agent mock-first, then swap one adapter at a time (Bedrock, AgentCore Memory, Identity, Gateway, Observability), host the Runtime contract, and deploy. The agent code never changes; only the adapters do.
    - [AgentCore adapters — runtime, sessions, policy, gateway](/docs/infrastructure/aws/agentcore-adapters): agentCoreRuntimeHost, agentCoreSessions and gatewayTransport — the live AgentCore adapter set, how Gateway policy differs, and which parts are really verified or contract-mapped.
    - [AgentCore Memory](/docs/infrastructure/aws/agentcore): AWS Bedrock AgentCore Memory adapter — session/event-based managed memory. Lazy-required @aws-sdk/client-bedrock-agentcore peer-dep.
    - [Bedrock — the LLM provider](/docs/build/aws-bedrock)
  - [Google Cloud & Gemini](/docs/infrastructure/google-cloud): A provider column. What agentfootprint adapts on Google Cloud today — the native Gemini provider, Gemini embeddings, Cloud Storage artifacts, Agent Runtime sessions, Firestore sessions, Memory Bank and ADC-based identity — plus every remaining boundary with the port that fills it and the honest reason it is not an adapter yet.
  - [Microsoft Foundry](/docs/infrastructure/microsoft-foundry): Both directions on one page, plus the whole Microsoft service map. Outbound — foundry() calls a Foundry project over the api-version-free v1 route, and foundryLocal() calls an on-device model with no key at all. Inbound — foundryResponsesHost serves the Foundry Toolkit's hosted-agent contract on the AgentHost port. entraIdentity() vends Azure tokens to tools. And an honest status column — nothing here has been run against live Azure.
  - [On-premises & self-hosted](/docs/infrastructure/on-premises): The provider column for a deployment that owns its own machines. Every service — LLM, stores, embeddings, hosting, code execution, telemetry, credentials, tools — with the adapter that fills it without a cloud account, its door, its dependency and its honest status.
- Debug
  - [How agentfootprint thinks](/docs/debug/manifesto): A manifesto in first person — why agentfootprint exists, what it abstracts, what it refuses to be, and the discipline that comes with adopting it.
  - [Debugging](/docs/debug/debug): How to debug an agentfootprint agent — typed events, narrative entries, time-travel checkpoints, and the agent playground viewer.
  - [Lint your tool catalog](/docs/debug/tool-catalog-lint): Find the tools a model could mix up — and the weak descriptions that make it guess — before a run ever happens. Works on any framework's tool list; a CI gate in five minutes.
  - [Localize a context bug](/docs/debug/localize-context-bug): Git bisect for context — point the debugging harness at a wrong answer and it walks the run back to the input that caused it, then proves it by removing it.
  - [Sharpen a context-bug diagnosis](/docs/debug/sharpen-the-diagnosis): Four tools that sit around localizeContextBug — is the ranking trustworthy, was something dropped, which on-topic source is innocent, and which piece cost loops even when the answer came out right.
  - [Re-run without sources](/docs/debug/rerun-without-sources): One call: take a finished run, ignore some of its context sources, run it again, and see honestly what changed.
  - [Compare two strategies](/docs/debug/compare-strategies): Scorer A versus scorer B, topK versus a re-ranker — the same seeded-rerun discipline as ablation, with the run manifest checking that the arm you declared is the arm that ran.
  - [Variable recall](/docs/debug/variable-recall): Ask about a VARIABLE, not a step — its whole recorded life, in agent vocabulary. And where the dataflow is exact, the backward walk stops guessing.
  - [Recorded chat](/docs/debug/recorded-chat): Record a chat turn-by-turn so any reply can be explained, counterfactually re-run, and forked — without re-writing the glue every chat host gets subtly wrong.
  - [Replay a saved run](/docs/debug/offline-replay): Save a run as three things — snapshot, events, structure — then show it in Why Lens or Flow Lens. Nothing re-runs, no model is called.
  - [Scrub a finished run](/docs/debug/time-travel): Time travel over an agent's commit log — stop on iterations, LLM turns, tool calls and decisions instead of on all forty stages, and read at each stop what the model was actually handed.
  - [File a bug with the run attached](/docs/debug/file-a-bug): A bug report IS the evidence. describeBugReport() measures the run into selectable units so a human can consent; exportBugReport() bundles what they kept as a real zip; githubBugReporter() commits it and files the issue.
  - [Ask your agent "why?"](/docs/debug/self-explain): .selfExplain() lets the agent answer follow-up why-questions about its OWN previous turn from the recorded trace — one builder call, the trace tools gated until asked, evidence bound to the completed run (never the in-flight one), and a cheaper-model delegate mode.
  - [Causal memory deep-dive](/docs/debug/causal-deep-dive): How the trace becomes the agent's working memory — the exact snapshot shape persisted, the four projection rules, and a worked replay end-to-end. The fourth workflow that no other framework has.
  - [Testing](/docs/debug/testing): mock({ replies }) + mockMcpClient + InMemoryStore — script every agent decision deterministically. No API keys, no flake, no hidden $40k OpenAI bill from a runaway test loop.
  - [Error handling](/docs/debug/error-handling): Tool failure recovery, retry/fallback/circuit-breaker decorators, resume-on-error. Build agents that degrade gracefully instead of crashing on the first 429.
- Monitor

  - **Observability**
  - [Observability](/docs/monitor/observability): Typed event streams, recorders, and tier-3 enable.* helpers — observe what the agent did without shaping what it does. Typed events emitted during DFS traversal, no instrumentation.
  - [Context Integrity](/docs/monitor/context-integrity): Typed checks that catch a run contradicting itself — and a ledger that proves the checkers ran.
  - [Arming Context Integrity](/docs/monitor/arming-context-integrity): Each Context Integrity check only runs once the application declares its precondition. This is the smallest declaration that arms each one — and what an unarmed check used to hide.
  - [Empty Lookups](/docs/monitor/empty-lookup): The run produced the identifier and the lookup for it came back empty. An advisory that notices the pair — and never claims to know which kind of empty it found.
  - [Prior-Turn Evidence](/docs/monitor/prior-turn-evidence): The answer is grounded, and nothing this turn fetched grounds it. An advisory that gives grounded values a time axis — and never claims to know whether the reader wanted the older ones.
  - [Column Types](/docs/monitor/column-types): A tool can declare what its rows contain, and the library checks the rows against that declaration at the boundary. It judges type, never meaning — and says so in every finding.
  - [Archive a run](/docs/monitor/recordings): persistRecording wraps a recorded run in a RecordingEnvelope — the versioned contract that says which run it is, how much of it this is, who produced it and under what privacy policy. Every field is derived from the run's own events or stated by the caller, and a fact it cannot honour is refused by name rather than guessed.
  - [Exporters: AgentCore & OTEL](/docs/monitor/exporters): Step-by-step — ship the agent's typed event trace to AWS AgentCore Observability (CloudWatch GenAI) and to OpenTelemetry. Observability is a port; pick an exporter strategy and mount it with agent.enable.observability().
  - [Context engineering recorder](/docs/monitor/context-engineering-recorder): Filter the firehose of context.injected events into engineered (RAG / Skills / Memory / Instructions / Steering / Facts) vs baseline (user / tool-result / assistant). The first-class handle on what your context engineering is actually doing.
  - [The cache meter](/docs/monitor/cache-meter): What prompt caching actually cost and saved on a turn — with "nobody measured" as a first-class answer, so an unmeasured turn can never render as a zero one.
  - [Streaming](/docs/monitor/streaming): Token-by-token output via provider.stream(). The same response is delivered as a stream for UI feedback AND as the authoritative LLMResponse for the ReAct loop — single round-trip, no double call.
  - [Locales (Message Catalog Pattern)](/docs/monitor/locales): Ship the agent's voice as a locale pack. defaultCommentaryMessages + defaultThinkingMessages + composeMessages + validateMessages — the i18n surface for agentfootprint observability prose.

  - **Production**
  - [Deployment](/docs/monitor/deployment): Multi-tenant identity at every store call, peer-dep declarations, mocks-first dev → real-infra prod swap. The patterns that take an agentfootprint app from laptop to production.
  - [Pause / Resume](/docs/monitor/pausable): Human-in-the-loop with JSON-checkpointed state. Pause hours mid-run via askHuman or pauseHere; resume on a different process, day, or server.
  - [Check in with the receipts](/docs/monitor/checkin): Evidence-carrying human consent for consequential tool actions. A tool declares checkIn; the ask rides an evidence pack (willDo / read / drivers / trail); the decision lands as a typed record.
  - [Resilience](/docs/monitor/resilience): withRetry + withFallback + fallbackProvider + withCircuitBreaker — composable decorators that wrap any LLMProvider with retry-on-transient, cross-provider failover, and fail-fast breaking. Compose freely.
  - [Reliability](/docs/monitor/reliability): Three primitives for production agents — circuit breaker for vendor outages, output-fallback for malformed LLM JSON, resume-on-error for mid-run failure recovery.
  - [Reliability gate](/docs/monitor/reliability-gate): Rules-based retry / fallback / fail-fast around every LLM call inside an Agent's ReAct loop. v2.11.5 — slot×trigger×cache, but for failure semantics.
  - [Security](/docs/monitor/security): Permission gating for tool calls, multi-tenant identity isolation, and an honest prompt-injection posture — what the library contains, what it does not detect, and where your own guard plugs in.
- Reference

  - **Architecture**
  - [Dependency graph (8-layer DAG)](/docs/reference/dependency-graph): How the library is structured. Each layer depends only on the ones above it; consumers can reach any layer directly without going through the others. The architecture diagram + the principles behind it.

  - **Design lineage**
  - [Inspiration — the academic shoulders we stand on](/docs/reference/inspiration): The two pillars under agentfootprint's design — Palantir-style connected data (the user-visible win) and Liskov-style modular boundaries (the engineering discipline that makes connection tractable).
  - [Connected Data — the Palantir lineage](/docs/reference/connected-data-palantir): THE WHY behind agentfootprint's design. Palantir's 2003 thesis (connect data, not analysts) returns at agent runtime — disconnected state burns iterations and tokens. agentfootprint connects four classes of agent data so the next token compounds the connection instead of paying for it again.
  - [Modularity — the Liskov lineage](/docs/reference/modularity-liskov): THE HOW behind agentfootprint's design. Liskov's ADT (1974) and LSP (1987) work, applied to flowcharts. Subflows are CLU clusters. CacheStrategy / LLMProvider / ToolProvider are LSP-substitutable. Locality of reasoning is enforced as a runtime invariant.
  - [Strategy Pattern Everywhere — port / adapter for vendor integrations](/docs/reference/strategy-everywhere): v2.6 cache layer's strategy-registry pattern, generalized to every observability / cost / status / lens vendor integration in v2.8+. AWS-first adapter priority — Bedrock AgentCore Observability → CloudWatch → X-Ray — with non-AWS (OTel, Datadog, Pino) following.

  - **Papers**
  - [Citations & papers](/docs/reference/citations): The research foundation of agentfootprint — every named pattern shipped as a recipe is grounded in a paper. References + how the recipe in examples/patterns/ relates to the original work.

  - **Full API**
  - [API Reference](/docs/api)