agentfootprint

Open-source TypeScript agent framework

agentfootprint: Your agent decides what a person used to. Only one of them leaves a reason.

  • 21,800+npm installs a month
  • MITopen source, no seat fees
  • No telemetryit never phones home
  • 9,800+tests on every release
  • Begin at the current step. The graph defines the instructions and working context available there.
  • Act, then observe. Models and tools return evidence to the run.
  • Advance through the graph. The next transition can be linear, rule-based, or model-selected.
  • Keep the path as it runs. Context → decision → action → outcome stay connected.
Build your agent with a skill graph Inspect a recorded run
Six inspectable facets of an agent run: evidence, decision, reason, coverage, refusal and replay.Evidencewhat was availableDecisionwhat it choseReasonits declared basisCoveragewhat was missingRefusalwhere it stoppedReplaytest dependence
Six facets of an inspectable agent run.
The handoff

An agent inherits the context a person used to carry.

Then the runbook has to become executable.

The progressionWhat changes
  1. Humancarries context between systems
  2. Agentinherits the same responsibility
  3. Whole runbookloads every instruction at once
  4. Current stepreveals what is needed now
  5. Traversaladvances and records together

The path is already a footprint as it runs.

A developer’s operating model

Four stages. The API you need at each one.

01 · Build

Turn the runbook into a path the agent can walk.

Scope

One state. One reachable skill.

Only its procedure, tools, and model enter the step.

Build the graph →
A refund request selects billing.refund from several candidate skills. Only that skill's procedure, three tools, and model enter the working set.

Route

Keep the payload out of the prompt.

For stored results, the model gets a ticket. Your product redeems the real data.

Follow the two lanes →
In this configured artifact path, a large tool result splits into two parts. The payload is stored outside model context. A small artifact ticket enters the conversation, where the model can route it to the present tool. The product interface redeems the ticket and loads the payload from the artifact store.
The model routes the ticket.The UI redeems the payload.

02 · Debug

Open the run before you change the agent.

View · five lenses

One recorded run. Five ways to inspect it.

One run · backup_protection_triage
  1. Read the estate
  2. Assess each cluster
  3. Assess each subject
  4. Posture
  5. Collect
  1. FlowWhat did it actually run?Every stage, in the order it took them — the chart the run really walked, not a diagram of the chart you wrote.
  2. WhyWhy did it decide that?The decision and the evidence beneath it, quoted from the run, with time travel to any moment.
  3. StoryCan someone else follow it?The same run as prose, for the people who will never open a graph and still have to sign off.
  4. Skill graphWhat could it even reach?Which procedure was live at each step, and the tools that step exposed — instead of a flat surface of everything.
  5. Data graphWhere did the numbers come from?How rows were shaped, tool by tool, into the ones the answer rests on. Running in an application today, landing in the lens next.

Test

Remove one source. Rerun the case.

If the output changes under the same baseline, you have evidence of dependence in this case—not hidden reasoning.

Test a source →
One recorded runOne controlled change
original · 8f2recorded
  1. intentsupport.refund
  2. skillbilling.refund
  3. contextpolicy/refunds-v1suspect
decisionAPPROVEwrong output
rerunpolicy/refunds-v1
rerun · 8f2-r1same case
contextpolicy/refunds-v1removed
decisionDENYchanged result

Dependence confirmed

Counterfactual replay tests the recorded run. It does not expose private model reasoning.

03 · Run in production

Serve on your stack. Keep the graph.

Bind

One graph. Your stack.

Every backend is a typed port; every vendor is an adapter behind it. Pick the ground and the adapters resolve — the agent you wrote does not move.

Wire your first port →
The same agent runs on AWS, Google Cloud, Microsoft Foundry or your own hardware. Choosing AWS binds the model port to Bedrock, memory to S3 and PostgreSQL, the runtime to AgentCore, and observability to CloudWatch and X-Ray. The agent itself is unchanged.

Infrastructure detail

ModelsMemoryAFruntimeStorageTelemetry
Keep the graph. Swap the edges.

One customer implementation

~40 toolsfocused surface

Better evaluated responses with a lower-cost model.

Field result, not a benchmark. Reproduce it on your workload.See the comparison method →
Bring your infrastructure — AWS, Google Cloud, Microsoft Foundry, or your own hardwareThe runtime is the whole ecosystem: models, memory, tools, identity, sessions and telemetry. Provision with your CDK or SDK and connect through typed ports — detach telemetry when export must not gate the run. Nothing about the agent you wrote changes when the cloud does.
  • ModelsOpenAI · Anthropic · Bedrock · Gemini · Azure OpenAI · Foundry · Ollama
  • Memory + dataRedis · PostgreSQL · SQLite · S3 · Cloud Storage
  • Toolsyour functions · MCP servers, local or remote
  • Identity + secretsJWKS · Vault · Entra ID · declare-and-push credentials
  • Runtime + sessionsAgentCore · Vertex sessions · your own process
  • ObserveOpenTelemetry · CloudWatch · X-Ray · audit bundles
The same agent, on four groundsagentfootprint provisions nothing and wants none of your credentials — it connects to what you already run. Changing ground changes which adapters you construct at the edge, which is the only place a vendor name should appear in your codebase.
  • AWSBedrock models · AgentCore runtime · S3 · CloudWatch · X-Ray
  • Google CloudGemini and Vertex models · Vertex sessions · Cloud Storage
  • Microsoft FoundryFoundry hosting and models · Azure OpenAI · Entra ID
  • Your own hardwareOllama · PostgreSQL · SQLite · your process · OpenTelemetry

04 · Monitor

Watch, export, archive, and learn from the same event stream.

The monitoring foundation ships todaySubscribe to typed events while the agent runs, send them to your existing backend, or persist the complete recording. The joins are written during traversal, so each downstream tool starts from the same connected run.
  • Watch and exportUse .on() for typed decisions, tools, cost, errors, and coverage; mount .enable.observability() to send the same stream to OTel, CloudWatch, NDJSON, or an audit bundle.
  • Archive the joined runrecordRun() captures state, events, and structure together; persistRecording() writes the versioned envelope to your sink.
  • Learn across runscontextLedger() already aggregates which skills, tools, and injections earned their context. Dedicated cross-session coverage-gap queries are in progress; today, aggregate the typed absence and coverage events in your sink.

Try agentfootprint

A front-end developer would never debug blind — they open DevTools. Your agents deserve the same.

npm i agentfootprintBuild your first agent Star on GitHub