Skip to content
AGENTFOOTPRINT

Quick Start

What is an AI agent?

Section titled “What is an AI agent?”

An LLM that can take actions, not just generate text. It calls tools, reads the results, decides what to do next, and loops until done. agentfootprint makes every step of that loop inspectable — what landed in which slot, which tool ran with what args, why a decision branched the way it did.

User question → LLM thinks → calls a tool → reads result → thinks again → responds

Install

Section titled “Install”
Terminal window
npm install agentfootprint

Your first agent

Section titled “Your first agent”
import { Agent, defineTool, mock } from 'agentfootprint';


const weather = defineTool({
  schema: {
    name: 'weather',
    description: 'Get current weather for a city.',
    inputSchema: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
  },
  execute: async (args) => `${(args as { city: string }).city}: 72°F, sunny`,
});


const agent = Agent.create({
  provider: mock({ reply: 'Paris is 72°F and sunny today.' }),
  model: 'mock',
  maxIterations: 5,
})
  .system('You answer weather questions using the `weather` tool.')
  .tool(weather)
  .build();


const result = await agent.run({ message: 'Weather in Paris?' });
console.log(result);
// → "Paris is 72°F and sunny today."

The mock provider returns a scripted reply — perfect for $0 testing. Swap to anthropic / openai / bedrock / ollama for real LLMs; no other code changes.

Add memory in 5 more lines

Section titled “Add memory in 5 more lines”

agentfootprint ships a single defineMemory({ type, strategy, store }) factory. Pick a TYPE (what shape you keep), a STRATEGY (how you fit it in), and a STORE.

import {
  Agent, defineMemory, MEMORY_TYPES, MEMORY_STRATEGIES, InMemoryStore, mock,
} from 'agentfootprint';


const memory = defineMemory({
  id: 'short-term',
  type: MEMORY_TYPES.EPISODIC,
  strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 }, // last 10 turns
  store: new InMemoryStore(),
});


const agent = Agent.create({ provider: mock({ reply: 'Hi Alice!' }), model: 'mock' })
  .memory(memory)
  .build();


// Pass an `identity` so memory accumulates per conversation.
const id = { conversationId: 'alice-session' };
await agent.run({ message: 'My name is Alice', identity: id });
const result = await agent.run({ message: 'What did I just say?', identity: id });
// → memory subflow loaded the prior turn; the agent answered from context

Read memory examples for all 7 strategies (window / budget / summarize / topK / extract / causal / hybrid).

See what happened

Section titled “See what happened”
console.log(agent.getNarrative());
// Human-readable execution trace — every stage, every decision,
// every tool call, every memory injection.

Or attach typed event listeners:

agent.on('agentfootprint.context.injected', (e) => {
  console.log(`[${e.payload.source}] landed in ${e.payload.slot} slot`);
});
agent.on('agentfootprint.stream.tool_start', (e) => {
  console.log(`→ tool ${e.payload.toolName}(${JSON.stringify(e.payload.args)})`);
});

Every event is typed: 47 events across 13 domains (context, agent, stream, tools, skill, permission, eval, cost, memory, …).

Next steps

Section titled “Next steps”