{"id":48515300,"url":"https://github.com/footprintjs/agentfootprint","last_synced_at":"2026-06-06T08:03:04.292Z","repository":{"id":344916790,"uuid":"1183666171","full_name":"footprintjs/agentfootprint","owner":"footprintjs","description":"Context engineering, abstracted. Build AI agents whose every LLM call traces back to what was injected, who triggered it, when, and how it cached. Built on footprintjs","archived":false,"fork":false,"pushed_at":"2026-05-25T19:39:04.000Z","size":5497,"stargazers_count":9,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-25T21:27:29.794Z","etag":null,"topics":["agent-framework","agentic-ai","ai-agents","ai-safety","explainability","human-in-the-loop","llm","observability","rag","tool-use"],"latest_commit_sha":null,"homepage":"https://footprintjs.github.io/agentfootprint/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/footprintjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-16T20:49:43.000Z","updated_at":"2026-05-25T19:39:06.000Z","dependencies_parsed_at":"2026-04-22T07:01:58.246Z","dependency_job_id":null,"html_url":"https://github.com/footprintjs/agentfootprint","commit_stats":null,"previous_names":["footprintjs/agentfootprint"],"tags_count":84,"template":false,"template_full_name":null,"purl":"pkg:github/footprintjs/agentfootprint","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/footprintjs%2Fagentfootprint","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/footprintjs%2Fagentfootprint/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/footprintjs%2Fagentfootprint/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/footprintjs%2Fagentfootprint/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/footprintjs","download_url":"https://codeload.github.com/footprintjs/agentfootprint/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/footprintjs%2Fagentfootprint/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33973868,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","agentic-ai","ai-agents","ai-safety","explainability","human-in-the-loop","llm","observability","rag","tool-use"],"created_at":"2026-04-07T19:00:38.567Z","updated_at":"2026-06-06T08:03:04.264Z","avatar_url":"https://github.com/footprintjs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"220\" alt=\"agentfootprint logo\" src=\"https://github.com/user-attachments/assets/a47840f4-cc8b-4bea-b88d-d9753f59616b\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eagentfootprint\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eContext engineering, abstracted.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/footprintjs/agentfootprint/actions\"\u003e\u003cimg src=\"https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/footprintjs/agentfootprint\"\u003e\u003cimg src=\"https://codecov.io/gh/footprintjs/agentfootprint/branch/main/graph/badge.svg\" alt=\"Coverage\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/agentfootprint\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/agentfootprint.svg?style=flat\" alt=\"npm version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/agentfootprint\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/agentfootprint.svg\" alt=\"Downloads\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/footprintjs/agentfootprint/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"MIT\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## What is agentfootprint?\n\n**A framework for building AI agents by treating context as a first-class runtime system.**\n\nMost agent code becomes context plumbing: which instructions go in `system`, which messages get added after a tool returns, which tools should be exposed right now, which memory to load for this tenant, which parts of the prompt are stable enough to cache.\n\nWithout a framework, every agent hand-rolls this logic. Over time it becomes a fragile mix of prompt concatenation, tool routing, memory loading, cache markers, observability hooks, and retry logic.\n\n**agentfootprint abstracts that bookkeeping.** You declare what context to inject, where it lands, and when it activates. The framework owns the agent loop, recomposes the LLM call every iteration, records typed events, applies caching, and persists replayable checkpoints.\n\n\u003e You write the intent. agentfootprint owns the context loop.\n\n---\n\n## The lineage\n\nEvery load-bearing dev tool of the last decade made the same move:\n\n| Framework | You write | The framework abstracts |\n|---|---|---|\n| **PyTorch (autograd)** | Forward graph | Gradient computation, backward pass |\n| **Express / Fastify** | Routes + handlers | HTTP loop, middleware chain |\n| **Prisma** | Schema + query intent | SQL generation, migrations |\n| **React** | Components + state | DOM diffing, render path |\n| **agentfootprint** | Injections (slot × trigger × cache) | Slot composition, iteration loop, caching, observation, replay |\n\nThe closest structural parallel is **autograd**: you describe the graph, the framework traverses it, and *because the framework owns the traversal it can record everything for free*. Same idea here — typed events, replayable checkpoints, and provider-agnostic prompt caching are consequences of owning the loop, not extra features.\n\n---\n\n## The core idea\n\nEvery LLM call has three slots:\n\n```text\nsystem     messages     tools\n```\n\nEvery agent feature — steering, instructions, skills, facts, memory, RAG, tool schemas — is content flowing into one of those slots. agentfootprint models all of them as one primitive:\n\n```text\nInjection = slot × trigger × cache\n```\n\nAn Injection answers three questions:\n\n1. **Where does this content land?** `system`, `messages`, or `tools`\n2. **When does it activate?** `always` · `rule` · `on-tool-return` · `llm-activated`\n3. **How is it cached?** `always` · `never` · `while-active` · predicate\n\nThat is the whole abstraction. Every named pattern in the agent literature — Reflexion, Tree-of-Thoughts, Skills, RAG, Constitutional AI — reduces to *which slot* + *which trigger*. You learn one model; the field's growth lands as new factories on the same primitive.\n\n```text\n                         LLM call\n        ┌────────────────────────────────────┐\n        │   system      messages      tools  │\n        │      ▲            ▲            ▲   │\n        └──────┼────────────┼────────────┼───┘\n               │            │            │\n          Injection     Injection     Injection\n               ▲\n               │\n      always · rule · on-tool-return · llm-activated\n```\n\n---\n\n## Why this isn't just an ergonomics win — Dynamic ReAct\n\nBecause the framework owns the loop, **all three slots recompose every iteration based on what just happened.**\n\n- **LangChain** assembles prompts once per turn.\n- **LangGraph** composes state per node, not per loop iteration.\n- **agentfootprint** recomposes per iteration.\n\nPer-iteration recomposition is what makes context engineering compositional instead of static. It's also the structural prerequisite for the cache layer — cache markers can't track active injections in lockstep without it.\n\n```text\nClassic ReAct                    Dynamic ReAct\n───────────────                  ─────────────\niter 1: 12 tools shown           iter 1: 1 tool  (read_skill)\niter 2: 12 tools shown           iter 2: 5 tools (skill activated)\niter 3: 12 tools shown           iter 3: 5 tools\n```\n\nUse Dynamic ReAct when your tools have dependencies (one tool's output implies which tool to call next). Use Classic ReAct when all tools are independent and ordering doesn't matter.\n\n\u003e 📖 Deep dive: [Dynamic ReAct guide](https://footprintjs.github.io/agentfootprint/guides/dynamic-react/) · [Cache layer](https://footprintjs.github.io/agentfootprint/guides/caching/)\n\n---\n\n## Quick start — runs offline, no API key\n\n```bash\nnpm install agentfootprint footprintjs\n```\n\n```typescript\nimport { Agent, defineTool, mock } from 'agentfootprint';\n\nconst weather = defineTool({\n  name: 'weather',\n  description: 'Get current weather for a city.',\n  inputSchema: {\n    type: 'object',\n    properties: { city: { type: 'string' } },\n    required: ['city'],\n  },\n  execute: async ({ city }: { city: string }) =\u003e `${city}: 72°F, sunny`,\n});\n\nconst agent = Agent.create({\n  provider: mock({ reply: 'I checked: it is 72°F and sunny.' }),\n  model: 'mock',\n})\n  .system('You answer weather questions using the weather tool.')\n  .tool(weather)\n  .build();\n\nconst result = await agent.run({ message: 'Weather in Paris?' });\nconsole.log(result);  // → \"I checked: it is 72°F and sunny.\"\n```\n\nSwap `mock(...)` for `anthropic(...)` / `openai(...)` / `bedrock(...)` / `ollama(...)` for production. Nothing else changes.\n\n---\n\n## A real agent in 8 lines\n\n```typescript\nconst agent = Agent.create({ provider, model: 'claude-sonnet-4-5-20250929' })\n  .system('You are a support assistant.')\n  .steering(toneRule)            // always-on\n  .instruction(urgentRule)       // rule-gated\n  .skill(billingSkill)           // LLM-activated\n  .memory(conversationMemory)    // cross-run, multi-tenant\n  .tool(weather)\n  .build();\n\nawait agent.run({ message: userInput, identity: { conversationId } });\n```\n\nThe hand-rolled equivalent is ~80 lines of slot management, trigger evaluation, memory loading, and cache marker placement — and growing with every feature. The declarative version stays at 8.\n\n\u003e 📖 Compare: [hand-rolled vs declarative](https://footprintjs.github.io/agentfootprint/getting-started/why/) · [migration from LangChain / CrewAI / LangGraph](https://footprintjs.github.io/agentfootprint/getting-started/vs/)\n\n---\n\n## The differentiator: the trace is a cache of the agent's thinking\n\nOther agent frameworks remember *what was said*. agentfootprint's causal memory records the **decision evidence** — every value the flowchart captured during the run, persisted as a JSON-portable snapshot.\n\nThat changes the cost structure of everything that happens after the agent runs:\n\n1. **Audit / explain** — six months later, \"why was loan #42 rejected?\" answers from the original evidence (creditScore=580, threshold=600), not reconstruction.\n2. **Cheap-model triage** — a trace from Sonnet is good *input* for Haiku to answer follow-up questions about that run. Memoization for agent reasoning.\n3. **Training data** — every successful production run is a labeled trajectory for SFT/DPO/process-RL, no separate data-collection phase.\n\nOne recording, three downstream consumers, no extra instrumentation.\n\n\u003e 📖 Deep dive: [Causal memory guide](https://footprintjs.github.io/agentfootprint/guides/causal-memory/)\n\n---\n\n## What you can build\n\n```typescript\n// Customer support — skills + memory + audit + cache\nconst agent = Agent.create({ provider, model })\n  .system('You are a friendly support assistant.')\n  .skill(billingSkill)\n  .steering(toneGuidelines)\n  .memory(conversationMemory)\n  .build();\n\n// Research pipeline — multi-agent fan-out + merge\nconst research = Parallel.create()\n  .branch(optimist).branch(skeptic).branch(historian)\n  .merge(synthesizer)\n  .build();\n\n// Streaming chat — token-by-token to a browser via SSE\nagent.on('agentfootprint.stream.token', (e) =\u003e res.write(toSSE(e)));\nawait agent.run({ message: req.query.message });\n```\n\n\u003e 📖 Full examples: [examples gallery](https://github.com/footprintjs/agentfootprint/tree/main/examples) · every example is also a CI test.\n\n---\n\n## Mocks first, production second\n\nBuild the entire app against in-memory mocks with **zero API cost**, then swap real infrastructure one boundary at a time.\n\n| Boundary | Dev | Prod |\n|---|---|---|\n| LLM provider | `mock(...)` | `anthropic()` · `openai()` · `bedrock()` · `ollama()` |\n| Memory store | `InMemoryStore` | `RedisStore` · `AgentCoreStore` · DynamoDB / Postgres / Pinecone |\n| MCP | `mockMcpClient(...)` | `mcpClient({ transport })` |\n| Cache strategy | `NoOpCacheStrategy` | auto-selected per provider |\n\nThe flowchart, recorders, and tests don't change between dev and prod.\n\n---\n\n## What ships today\n\n- **2 primitives** — `LLMCall`, `Agent` (the ReAct loop)\n- **4 compositions** — `Sequence`, `Parallel`, `Conditional`, `Loop`\n- **7 LLM providers** — Anthropic · OpenAI · Bedrock · Ollama · Browser-Anthropic · Browser-OpenAI · Mock\n- **One Injection primitive** — `defineSkill` / `defineSteering` / `defineInstruction` / `defineFact`\n- **One Memory factory** — 4 types × 7 strategies including **Causal**\n- **Provider-agnostic prompt caching** — declarative per-injection, per-iteration marker recomputation\n- **RAG · MCP · Memory store adapters** — InMemory · Redis · AgentCore\n- **48+ typed observability events** across context · stream · agent · cost · skill · permission · eval · memory · cache · embedding · error\n- **Pause / resume** — JSON-serializable checkpoints; resume hours later on a different server\n- **Resilience** — `withRetry`, `withFallback`, `resilientProvider`\n- **AI-coding-tool support** — Claude Code · Cursor · Windsurf · Cline · Kiro · Copilot\n\n\u003e 📖 [Full feature list \u0026 API reference](https://footprintjs.github.io/agentfootprint/reference/) · [CHANGELOG](./CHANGELOG.md)\n\n---\n\n## Roadmap\n\n| Theme | Focus |\n|---|---|\n| Reliability | Circuit breaker, output fallback, auto-resume-on-error |\n| Causal exports | `causalMemory.exportForTraining({ format: 'sft' \\| 'dpo' \\| 'process' })` |\n| Governance | Policies, budget tracking, production memory adapters |\n| Cache v2 | Gemini handle-based caching, cost attribution |\n| Deep agents | Planning-before-execution, A2A protocol, Lens UI |\n\nRoadmap items are *not* current API claims. If a feature isn't in `npm install agentfootprint` today, it's listed here, not in the docs.\n\n---\n\n## Design philosophy\n\nTwo principles shape the runtime:\n\n**Connected data (Palantir, 2003).** Enterprise insight is bottlenecked by data fragmentation, not analyst skill. Agents face the same problem at runtime — disconnected tool state, lost decision evidence, scattered execution context. agentfootprint connects state, decisions, execution, and memory into one runtime footprint so the next iteration compounds the connection instead of paying for it again.\n\n**Modular boundaries (Liskov, 1974).** Every framework boundary — `LLMProvider`, `ToolProvider`, `CacheStrategy`, `Recorder`, `MemoryStore` — is an LSP-substitutable interface. Swap implementations without changing agent code.\n\nConnected data alone is fast but unmaintainable. Modular boundaries alone are clean but dumb. Together: a runtime that's both fast and reasonable.\n\n\u003e 📖 Long-form: [the Palantir lineage](https://footprintjs.github.io/agentfootprint/inspiration/connected-data/) · [the Liskov lineage](https://footprintjs.github.io/agentfootprint/inspiration/modularity/)\n\n---\n\n## Where to next\n\n| If you are... | Go here |\n|---|---|\n| New to agents | [5-minute quick start](https://footprintjs.github.io/agentfootprint/getting-started/quick-start/) |\n| Coming from LangChain / CrewAI / LangGraph | [Migration guide](https://footprintjs.github.io/agentfootprint/getting-started/vs/) |\n| Architecting an enterprise rollout | [Production guide](https://footprintjs.github.io/agentfootprint/guides/deployment/) |\n| Doing due diligence | [Architecture overview](https://footprintjs.github.io/agentfootprint/architecture/) |\n| Researcher / extending | [Extension guide](https://footprintjs.github.io/agentfootprint/contributing/extension-guide/) |\n| Curious about design | [Inspiration docs](https://footprintjs.github.io/agentfootprint/inspiration/) |\n\nOr jump into the [examples gallery](https://github.com/footprintjs/agentfootprint/tree/main/examples) — every example is also an end-to-end CI test.\n\n---\n\n## Built on\n\n[footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. The decision-evidence capture, narrative recording, and time-travel checkpointing this library uses are footprintjs primitives. The same way autograd's forward-pass traversal is what makes gradient inspection automatic, footprintjs's flowchart traversal is what makes agentfootprint's typed-event stream and replayable traces automatic.\n\nYou don't need to learn footprintjs to use agentfootprint — but if you want to build your own primitives at this depth, [start there](https://footprintjs.github.io/footPrint/).\n\n---\n\n## License\n\n[MIT](./LICENSE) © [Sanjay Krishna Anbalagan](https://github.com/sanjay1909)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffootprintjs%2Fagentfootprint","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffootprintjs%2Fagentfootprint","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffootprintjs%2Fagentfootprint/lists"}