agentfootprint: Explainable AI Agent Flowcharts

Where this fits

You're building an AI agent that must call an LLM, run a tool, and conditionally branch based on the response. Debugging why the agent took a certain path usually means adding print statements or logging calls after the fact. agentfootprint solves this by modeling the agent as a flowchart at build time—every injection, read, write, decision, and tool call becomes connected evidence as the run happens. You can trace exactly what happened, swap providers without code changes, and test with deterministic mocks.

Why agents benefit

• Adapter-swap testing: Use mock({...}) for $0 deterministic runs, then switch to ollama for free local tests, then to anthropic or openai—all without changing logic.
• Declarative context: Declare facts, steering, and skills; the framework decides when they fire and which slot they land in, reducing boilerplate.
• Evidence collected during traversal: Inherited from footprintjs, data is captured as the run happens—no post-processing or fragile replay.
• Resilience built in: Retries, timeouts, and streaming are first-class concepts, so agents handle real-world flakiness gracefully.
• Composable flowcharts: Combine LLMCall, Agent, RAG, memory, control flow, and Swarm patterns as reusable blocks, making complex agents maintainable.

Practical scenarios

Testing agent logic with $0 mock runs

Before investing in paid API calls, run your full agent with mock({...}) to assert deterministic outputs. Catch logic errors, branch missteps, or tool call order issues early—no cost, no flakiness.

Swapping from local ollama to anthropic for production

Develop locally with ollama for fast iteration, then flip a single provider line to anthropic for production. The same agent code works unchanged, which means you can test with a real model locally and scale to a paid provider only when needed.

Debugging RAG flows with traceable evidence

When a retriever returns irrelevant chunks, agentfootprint's runtime evidence shows exactly which context was injected into the prompt and how the agent used it. You see the decision path and the data that drove it, making root-cause analysis quick.

Add it to your agent workflow

Install the skill with:

npx skills add footprintjs/agentfootprint --skill agentfootprint

Then use it in your agent:

import { Agent, mock } from 'agentfootprint';

const agent = new Agent({
  provider: mock({ responses: ['hello'] }),
  skills: ['greeting'],
});
const result = await agent.run('hi');
console.log(result.evidence); // trace of every step

For more patterns and community discussions, see the agentfootprint skill page.

Compare before adopting

Evaluate agentfootprint against alternatives like LangGraph or custom state machines. Look at:

• Quality signals: Does it have tests, examples, and clear docs? (Check the repo's README and recent commits.)
• Maintenance freshness: Is it actively maintained? Star count and commit activity are good proxies.
• Alternatives: Compare provider-swap ease, evidence collection, and Swarm support.
• Workflow fit: Does the flowchart model match how you think about agents? Try a small pilot before committing.

Why it is worth tracking

agentfootprint is young (20 stars) but its design—composable flowcharts with runtime evidence and provider-agnostic swaps—addresses a real pain point in agent debugging. The project's connection to footprintjs (established in observability) gives it a solid engineering pedigree. Track it if you value testability and transparency in agent development. It's worth a spike when you're planning a multi-step agent that needs deterministic testing and clear audit trails.