The same agent, from your laptop to production.

import { Agent, defineTool } from 'agentfootprint';import { mock } from 'agentfootprint/providers'; const getRefund = defineTool<{ orderId: string }, unknown>({  name: 'get_refund',  description: 'Look up a refund by order id.',  inputSchema: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'] },  execute: ({ orderId }) => ({ orderId, status: 'pending' }),}); // A scripted model: free, offline, and the same every time.const provider = mock({  replies: [    { toolCalls: [{ id: 'c1', name: 'get_refund', args: { orderId: 'A-1042' } }] },    { content: 'Your refund for A-1042 is still pending.' },  ],}); const agent = Agent.create({ provider, model: 'mock' })  .system('You answer refund questions.')  .tool(getRefund)  .build(); const answer = await agent.run({ message: 'Where is my refund for A-1042?' });

const agent = Agent.create({  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),  model: 'claude-sonnet-5-5',})  .system('You answer refund questions.')  .tool(getRefund)  .build();

import { Agent } from 'agentfootprint';import { defineOntology } from 'agentfootprint/ontology'; const map = defineOntology({  id: 'fleet',  version: '1',  sources: {    inventory: { meaning: 'the switch inventory export', configured: true },  },  nodes: {    port: {      meaning: 'a physical switch port',      sources: [{ source: 'inventory', via: ['lookup_port'], coverage: 'every port on every switch' }],    },    port_error_rate: { meaning: 'CRC errors per minute on a port', unit: 'errors/min' },  },  edges: [{ from: 'port_error_rate', to: 'port', relation: 'measured-on' }],}); const agent = Agent.create({ provider, model: 'mock' }).tool(lookupPort).ontology(map).build();

import { Agent, defineTool, inMemoryArtifacts } from 'agentfootprint'; // 48,000 rows. Past the threshold, the store keeps them and the model gets a short ticket.const getSales = defineTool({  name: 'get_sales',  description: 'Fetch the Q3 sales rows (large).',  inputSchema: { type: 'object', properties: {} },  execute: () => Array.from({ length: 48_000 }, (_, i) => ({ order: i, amount: (i % 97) + 1 })),}); // This argument is a ticket. The tool receives the data behind it.const summarize = defineTool<{ sales: string }, string>({  name: 'summarize',  description: 'Summarize sales rows.',  inputSchema: { type: 'object', properties: { sales: { type: 'string' } }, required: ['sales'] },  wants: { sales: 'tool-result/get_sales' },  execute: ({ sales }) => {    received.push((JSON.parse(sales) as unknown[]).length);    return 'summary';  },}); const agent = Agent.create({  provider,  model: 'mock',  artifacts: { store: inMemoryArtifacts(), placement: { maxInlineChars: 2_000 } },})  .tool(getSales)  .tool(summarize)  .build();

import { Agent } from 'agentfootprint'; const agent = Agent.create({ provider, model: 'mock' })  .time({ zone: 'America/Los_Angeles' }) // the fallback, and each run's own zone wins  .build(); await agent.run({  message: 'Any errors since 8?',  time: { now: '2026-11-05T17:30:00Z', zone: 'America/New_York' },}); const clock = agent.findings()?.find((row) => row.kind === 'clock');// { kind: 'clock', now: '2026-11-05T17:30:00Z', nowSource: 'app', zone: 'America/New_York', zoneSource: 'run' }

const agent = Agent.create({ provider, model: 'mock' })  .system('You are a refunds assistant.')  .tool(getRefund)  .selfExplain() // one line, and the trace tools stay hidden until someone asks  .build(); await agent.run({ message: 'Should order A-1042 be refunded?' }); // The next turn asks about the last one. It answers from its own record.const why = await agent.run({ message: 'Why did you approve it?' });

import { openRecording, recordRun, traceDebugAgent } from 'agentfootprint/observe'; const recorder = recordRun(agent);await agent.run({ message: 'Where is my refund for A-1042?' });const artifacts = openRecording(recorder.toRecording()); // A second agent, whose only tools read that saved run.const debuggerAgent = traceDebugAgent({ artifacts, provider, model: 'mock' });const report = await debuggerAgent.run({ message: 'Why did it say pending?' });

import { useMemo } from 'react';import { Agent } from 'agentfootprint';import { mock } from 'agentfootprint/providers';import { Lens, lensRecorder } from 'agentfootprint-lens'; export function App() {  const { agent, recorder } = useMemo(() => {    const agent = Agent.create({ provider: mock({ reply: 'Hi!' }), model: 'mock' }).build();    const recorder = lensRecorder();    recorder.observe(agent);    return { agent, recorder };  }, []);   return (    <>      <button onClick={() => agent.run({ message: 'Hello!' })}>Run</button>      <Lens recorder={recorder} runner={agent} />    </>  );}

agent.on('agentfootprint.eval.score', (event) => {  scores.push(event.payload.value);}); const answer = await agent.run({ message: 'Where is my refund for A-1042?' }); // Your grader decides the score. The library only carries it.agent.emit('agentfootprint.eval.score', {  metricId: 'refund-accuracy',  value: myGrader(answer),  target: 'run',  targetRef: 'this-run',  evaluator: 'heuristic',});

const myModel = {  name: 'my-model',  complete: () => callMyModel(), // reach your model however you like}; const agent = Agent.create({ provider: myModel, model: 'any' }).build();

/** * WHO is calling — proven, never read off a header. A real app passes its IdP: * `jwksIdentity({ jwksUrl, issuer, audience })` from `agentfootprint/security`. * This demo verifier knows one token. */const verify = async (token: string) => {  if (token !== DEMO_TOKEN) throw new Error('unknown token');  return { userId: 'ada' };}; /** The whole server side: one handler, mounted at any route of any framework. */function serve(provider: LLMProvider) {  return streamHandler({    agent: ({ tools }) => buildAgent(provider, tools), // fresh per request    adapter: agUi(),    // No valid token → 401. The thread is keyed by the VERIFIED caller, so the    // same thread id from someone else is someone else's conversation.    threads: verifiedThreads({ verify }),    sessions: memorySessions(), // sqliteSessions({ file }) to survive a restart  });  // Next.js:  export const POST = serve(provider);  // Hono:     app.post('/agent', (c) => handler(c.req.raw));  // Bun/Deno: Bun.serve({ fetch: handler }) · Deno.serve(handler)}

import { otelObservability, xrayObservability } from 'agentfootprint/observe';import { setImmediateDriver } from 'footprintjs/detach'; // Native: typed events, as the agent runs.agent.on('agentfootprint.stream.tool_end', (event) => console.log(event.payload)); // Any OTLP backend, through your own OpenTelemetry tracer.agent.enable.observability({  strategy: otelObservability({ serviceName: 'refunds', tracer }),  detach: { driver: setImmediateDriver, mode: 'forget' }, // off the agent's call path}); // Or straight to AWS X-Ray.agent.enable.observability({ strategy: xrayObservability({ region: 'us-west-2', serviceName: 'refunds' }) });

// A recorder of your own sees every state write as the run happens.const refundWatch: CombinedRecorder = {  id: 'refund-watch',  onWrite: (event) => written.push(event.key),}; const agent = Agent.create({ provider, model: 'mock' }).watch(refundWatch).build(); // Your own events travel the same stream as the library's.agent.on('*', (event) => {  const { type, payload } = event as { type: string; payload: unknown };  if (type === 'myapp.refund.flagged') alertTeam(payload);});agent.emit('myapp.refund.flagged', { order: 'A-1042' });