A TypeScript agent framework for connecting answers to recorded evidence, making uncertainty explicit,
and checking outputs before delivery. Configure what an answer must support and when to withhold it.
Built on FootprintJS execution provenance:
context, tool calls, results and decisions become connected records as the agent runs.
Build with tools, skills, memory, RAG and orchestration; use that record for answer checks, debugging and review.
---
## What can this answer support?
A tool returned no rows. Before an agent says **"there are no incidents"**, the app
needs to know which account was searched, what period the read covered, whether it
finished, and what it could not reach. A successful empty query and a failed query
support different answers.
For example, the bounded claim is: **"The search returned no matching incidents
for this account and time window. Email reports were not checked."** That is an
illustration of scope-aware wording, not a claim that no incident exists anywhere.
When the evidence cannot support the requested conclusion, the app should make
that uncertainty explicit or withhold the answer.
Agentfootprint supplies the execution record and configurable checks for that
decision. Your app defines the comparisons and delivery policy. Tool declarations
must describe the query truthfully: recording a source's assertion does not prove
the source is correct.
## How evidence reaches the answer
1. **Record what ran.** FootprintJS connects execution steps and data dependencies;
Agentfootprint records the context supplied, tools called and results returned.
2. **Preserve the limits.** Tools declare absence, coverage and time boundaries.
Configure those limits to travel with the answer instead of relying on the model
to repeat them.
3. **Check before delivery.** Opt-in answer validation compares the candidate with
evidence under app-authored rules. Enforce mode withholds failed or unverified
candidates; the host decides how to explain the refusal to the user.
4. **Inspect the same run.** Review recorded inputs, results, decisions and checks,
or replay the execution to investigate a failure.
Execution provenance describes what ran and what was supplied. It does not expose
the model's internal reasoning or independently establish that an external fact
is true. Withholding an answer does not undo tool actions already performed.
## Checks you can enable
Installing the framework does not make every answer verified. These mechanisms
have different jobs and must be configured for the claims your app needs to check.
| Mechanism | What it provides | Boundary of the guarantee |
|---|---|---|
| [`absent()`, `coverage()` and `.limitsTravelWithTheAnswer()`](#what-a-tool-returns--three-helpers-one-rule) | Explicit absence and declared limits, carried into prose or returned beside typed output. | Preserves declarations; does not prove that the tool described its coverage correctly. |
| [`.answerValidation()`](docs-next/content/docs/build/output-schema.mdx#check-the-answer-against-evidence) | App-authored checks on a typed final answer. Enforce mode buffers drafts and withholds failed or unverified answers; observe mode records the report and permits delivery. | Only the configured checks are judged. The app owns their correctness and the trustworthiness of its evidence. |
| [`.namesAndNumbersFromEvidence()`](docs-next/content/docs/build/evidence-gate.mdx) | A deterministic detector for unsupported values, with configurable extraction limits and delivery postures. | Default `assist` flags; `rails` refuses. A false sentence assembled from real values can pass. This is not general factual verification. |
| [`Tool.search` and typed `.negativeClaims()`](docs-next/content/docs/build/negative-claims.mdx) | Composed search scope and library-written statements for cited structured negative claims, retaining gaps and withholding or reporting unsupported claims according to policy. | **Opt-in, available but not recommended pending benchmark gates.** Accuracy and usefulness remain unmeasured. Depends on truthful app-owned search declarations; other answer fields remain unchecked model text. |
| [`.negativeClaims({ prose: true })`](docs-next/content/docs/build/negative-claims.mdx) | Bounded heuristic warnings on the model's own negative sentences. | Never verifies, blocks or rewrites an answer. The previous detector failed its benchmark; the revised path is unmeasured. No warning does not mean verified. |
The links above describe this branch. Features marked **unreleased** in the
[capability index](CAPABILITIES.md) are not yet available in the published package;
check its availability column and the [release notes](CHANGELOG.md) for your
installed version. The basic quick start below does not enable these checks.
## How this compares with LangChain and Mastra
These frameworks all support agent building and runtime controls. The useful
distinction is what each emphasizes, rather than whether it has guardrails.
| Framework | Emphasis and existing runtime controls |
|---|---|
| **LangChain / LangGraph** | Model and tool integrations, agent loops and stateful orchestration with persistence and human oversight. [LangGraph](https://docs.langchain.com/oss/javascript/langgraph/overview) covers execution; [LangChain guardrails](https://docs.langchain.com/oss/javascript/langchain/guardrails) can check inputs, outputs and tool calls during a run. |
| **Mastra** | A TypeScript framework for agent applications, with workflows, memory, development tools, tracing and evaluations. Its [input/output processors](https://mastra.ai/docs/agents/processors) can validate or transform messages during execution. [Overview](https://mastra.ai/docs). |
| **Agentfootprint** | Agent building organized around FootprintJS execution provenance: connected execution records, declared evidence limits, and [configured checks](#checks-you-can-enable) that can govern answer delivery. |
Choose Agentfootprint when a central requirement is to connect an answer to what
the agent actually read, the limits of that evidence, and the checks applied before
delivery. Skills, tools and orchestration build the agent; the execution record
also supports its answer policy. This comparison describes design emphasis, not
exclusive capabilities or measured superiority in answer accuracy.
## Quick start — runs offline, no API key
```bash
npm install agentfootprint footprintjs
```
```typescript
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({
replies: [
{ toolCalls: [{ id: 'weather-1', name: 'weather', args: { city: 'Paris' } }] },
{ content: 'The demo weather tool returned 72°F and sunny for Paris.' },
],
}),
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); // → "The demo weather tool returned 72°F and sunny for Paris."
```
The tool runs locally and the mock scripts its call and reply. The temperature is
fixture data, not a live weather reading; this example demonstrates wiring, not
answer validation. For a configured delivery check, run the [mock answer-validation
example](examples/features/99-guard-presented-code.ts).
To use a real model, replace the scripted mock with a provider from
`agentfootprint/providers` — `anthropic(...)` / `openai(...)` / `bedrock(...)` /
`gemini(...)` / `ollama(...)` — and configure its model and any required credentials.
The agent and tool wiring stays the same. Every provider, including `mock`, lives
on that subpath so the main barrel stays free of optional provider SDK imports.
**No cloud account?** `ollama('llama3.2')` from `agentfootprint/providers` runs the same agent against a local model for $0 — the free rung between the mock and the bill. Full recipes: [Ollama](https://agentfootprint.dev/docs/build/ollama/) · [OpenAI-compatible endpoints](https://agentfootprint.dev/docs/build/openai/#openai-compatible-endpoints-ollama-llamacpp-vllm-together-groq-lm-studio).
## What a tool returns — three helpers, one rule
Whatever a tool returns is what the model reads next. When that value has limits the model must not lose, return it through one of three helpers — each is the tool's response; nothing is added to the system prompt or the tool's schema:
| helper | use it when | the model reads | the record keeps |
|---|---|---|---|
| `describedResult({ … })` | rows, a series or relationships from a system of record | the data, with `grain`, `provenance` and one `not_covered` line per gap | the whole envelope (`tools.semantics_declared`) |
| `coverage(value, { … })` | any other value that has limits | your value, with what was and was not checked | `tools.coverage_declared` |
| `absent({ … })` | nothing matched | what was looked for, where, and that a retry returns the same | `tools.absent` |
Never wrap one in another. Add `.limitsTravelWithTheAnswer()` and the declared coverage is appended to the final answer — or, for a typed `.outputSchema()` answer, returned beside it as data by `agent.answerCoverage()`. Provenance and grain never are.
```typescript
import { absent, coverage, describedResult } from 'agentfootprint';
execute: ({ vm, summary }) => {
const { exportedAt, source, runs: all } = backupExport; // your system of record
const runs = all.filter((r) => r.vm === vm);
const ground = { checked: [`every backup job in the export of ${exportedAt}`] };
if (runs.length === 0) return absent({ what: `backup runs for ${vm}`, ...ground }); // nothing matched
if (summary) return coverage(`${vm}: ${runs.length} backup runs`, ground); // a verdict with limits
return describedResult({ // rows from the record
facts: runs.map((r) => ({ entity: vm, day: r.day, ok: r.ok === 1 })),
provenance: { measuredAt: exportedAt, source }, // the time comes from the data
coverage: ground,
});
},
```
What the model reads from each, exactly: [Tools → what `execute` returns](https://agentfootprint.dev/docs/build/tools/#what-execute-returns--three-helpers-one-rule).
## Building agents — context, tools and orchestration
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 4 triggers ↓
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, activeWhen: s => s.lastToolResult?.toolName === 'search', prompt: 'Cite source IDs.' }))` | `system` |
| `llm-activated` | runtime — agent-driven | LLM calls `read_skill('id')` | `.skill(defineSkill({ id: 'refund-policy', description, body }))` | `system` (body) + `tools` |
**3 slots × 4 triggers × N flavors = the entire context-engineering surface.**
## Inspect and replay the evidence
The recorded run also supports debugging. These examples illustrate different
kinds of evidence; a similarity score or recorded dependency alone is not proof
of why a model chose an answer.
A run replayed with Story Lens (npm i agentthinkingui). Frames are generated from the run's trace; ▶ watch it live.
