agentfootprint

---

The new error class

For decades, software had two kinds of errors — and developers never needed deep domain knowledge to fix either:

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:

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

npm install agentfootprint footprintjs

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({ 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/providers and swap it in — anthropic(...) / openai(...) / bedrock(...) / gemini(...) / ollama(...). Only the import line changes; the agent code stays the same. (Every provider — mock included — lives on the agentfootprint/providers subpath, so the main agentfootprint barrel stays free of optional peer-dep requires.)

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 · OpenAI-compatible endpoints.

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:

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.

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.

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.