AgentProdReady

TypeScript agents you can ship this week — with a clean path to production controls when you need them.

Production-oriented architecture with a young ecosystem.

For TypeScript / Node.js backend developers embedding AI agents into existing applications — without giving up production controls later.

Start here if you are evaluating the project: What is AgentProdReady? — core abstraction, durability, retries/HITL, provider routing, and what “production-oriented” does and does not mean.

---

Core model (30 seconds)

Question	Answer
Abstraction	Agent + Runtime execution — createAgent / invoke / stream + tools. Not a graph DSL (LangGraph-style) as the primary API.
Durable state	Runtime checkpoints + optional fileMemory / postgresMemory, HITL park/resume, stream replay. memory: true stays ephemeral.
Retries / idempotency / HITL	Runtime owns retries; tools declare idempotency (+ ledger for idempotent); approve / reject / resume for required approvals.
Provider routing	Simple helpers pick one model; hosts use Capability Resolution ordered failover (no separate AiRouter).
“Production ready”	Means architecture for production controls, not “large known production fleet.” Young ecosystem — honest about that.

How it fits together

createAgent  →  Runtime (timeout / checkpoint / recover / stream)
                    ↓
               Security (authorize)
                    ↓
        Capability Resolution → AI Provider | Tools | Memory

npm install @agentprodready/agent-framework · ⭐ Star · Contribute

import { createAgent, openai, tool } from "@agentprodready/agent-framework";

const agent = createAgent({
  model: openai("gpt-4o-mini"),
  instructions: "You help with short operational questions.",
  tools: [
    tool({
      name: "lookupStatus",
      description: "Look up a ticket status",
      parameters: {
        type: "object",
        properties: { id: { type: "string" } },
        required: ["id"],
      },
      execute: async ({ id }) => ({ id, status: "open" }),
    }),
  ],
  memory: true,
});

const result = await agent.invoke("Check ticket T-1");
console.log(result.text);
await agent.close();

Also: stream() / stream replay, reference() (zero API key), openaiCompatible() / anthropic() / gemini(), durable memory & HITL, and result.metadata diagnostics.

---

Why AgentProdReady?

• Simple Agent API — createAgent, invoke, stream, close
• Simple Team / Workflow / Orchestrator — createTeam, createWorkflow, createOrchestrator, handoff
• Tools with guardrails — tool() with conservative defaults; durable HITL approve/resume when required
• Streaming — embedded library streams + replay (resumeFrom / replayStream)
• Memory — ephemeral memory: true / inMemory() for the weekend path; fileMemory() / postgresMemory() when you need durability
• OpenAI + OpenAI-compatible + Anthropic + Gemini — first-class helpers; credential isolation for gateways
• Production controls when needed — Runtime, Security, Capability Resolution, recovery — without rewriting your entrance API story

Secondary tagline: Build an agent in minutes. Add production controls when you need them.

Fair comparison: Why AgentProdReady · evaluator FAQ: What is AgentProdReady?.

---

Getting Started

Option A — scaffold (recommended)

npm create agentprodready@latest my-agent
cd my-agent
npm install
npm run dev

Choose Reference (no API key), OpenAI, or OpenAI-compatible.

Option B — one package, zero secrets

npm install @agentprodready/agent-framework

import { createAgent, reference } from "@agentprodready/agent-framework";

const agent = createAgent({
  model: reference(),
  instructions: "You are a helpful assistant.",
});

const result = await agent.invoke("Hello");
console.log(result.text); // Hello
await agent.close();

No API key, database, or Docker. Full walkthrough: Getting Started.

Multi-agent team

import { createAgent, createTeam, reference } from "@agentprodready/agent-framework";

const researcher = createAgent({
  name: "researcher",
  model: reference(),
  instructions: "Research the topic.",
});
const analyst = createAgent({
  name: "analyst",
  model: reference(),
  instructions: "Analyze the research.",
});

const team = createTeam({
  agents: { researcher, analyst },
  strategy: "sequential",
});

const result = await team.run("Research the TypeScript AI agent ecosystem.");
console.log(result.text);

Examples: examples/multi-agent-sequential, multi-agent-parallel, multi-agent-supervisor.

OpenAI

npm install @agentprodready/agent-framework @agentprodready/ai-provider-openai
export OPENAI_API_KEY="..."   # PowerShell: $env:OPENAI_API_KEY="..."

import { createAgent, openai } from "@agentprodready/agent-framework";

const agent = createAgent({
  model: openai("gpt-4o-mini"),
  instructions: "You are a helpful assistant.",
});

The library does not load .env files.

OpenAI-compatible gateway

import { createAgent, openaiCompatible } from "@agentprodready/agent-framework";

const agent = createAgent({
  model: openaiCompatible({
    baseUrl: "https://api.example.com/v1",
    model: "llama-3.1-70b",
  }),
  instructions: "You are a helpful assistant.",
});

Uses OPENAI_COMPATIBLE_API_KEY — never a silent OPENAI_API_KEY fallback. Guide: openai-compatible.md.

Streaming

for await (const event of agent.stream("Hello")) {
  if (event.type === "text") process.stdout.write(event.text);
}

Tools

import { createAgent, reference, tool } from "@agentprodready/agent-framework";

const agent = createAgent({
  model: reference(),
  instructions: "You are helpful.",
  tools: [
    tool({
      name: "getWeather",
      description: "Get weather for a city",
      parameters: {
        type: "object",
        properties: { city: { type: "string" } },
        required: ["city"],
      },
      execute: async ({ city }) => ({ city, forecast: "sunny" }),
    }),
  ],
});

// Deterministic reference demo (OpenAI selects tools from schemas instead):
const result = await agent.invoke('USE_TOOL:getWeather:{"city":"Paris"}');

Defaults: sideEffect: "mutating", idempotency: "non-idempotent", approvalRequirement: "none".
approvalRequirement: "required" pauses for approval — use agent.approve(approvalId) + agent.resume(executionId).
Idempotent tools with a durable ledger are exactly-once-capable; non-idempotent external effects are not exactly-once.

Memory

Ephemeral (default): memory: true ≡ inMemory() — process-local, instance-scoped, cleared on exit.
Durable (v1.6): fileMemory({ directory }) or postgresMemory({ connectionString }) — survives restart.
reference() does not reason over memory in natural language — use openai() for NL recall demos. See Simple Memory · Durable Memory.

---

Examples

Example	Problem it answers
examples/hello-agent	Fastest success — reference() + invoke
examples/backend-agent	Canonical wow — tools + memory + invoke + stream
examples/tools-agent	Focused tool() path
examples/openai-compatible-agent	Gateway / credential isolation
examples/openai-agent	Live OpenAI
examples/anthropic-agent	Live Anthropic (Messages API)
examples/diagnostics-agent	Zero-key result.metadata diagnostics
examples/memory-agent	Honest memory wiring + optional NL recall
examples/streaming-agent	Library stream() only

---

Providers

Helper	Package peer	Secrets
reference()	none	none
openai()	@agentprodready/ai-provider-openai	OPENAI_API_KEY
openaiCompatible()	@agentprodready/ai-provider-openai	OPENAI_COMPATIBLE_API_KEY (or auth: "none")
anthropic()	@agentprodready/ai-provider-anthropic	ANTHROPIC_API_KEY
gemini()	@agentprodready/ai-provider-gemini	GEMINI_API_KEY

Guides: anthropic.md · gemini.md.

---

Production path

When the weekend agent becomes a real backend dependency:

1. Embed recipe — Embed agent deployment (Node service, env, Docker, health, shutdown, your auth)
2. Operator host — Production deployment
3. Graduation — Adopting AgentProdReady
4. Fair positioning — Why AgentProdReady

Simple/embedded mode is not production HTTP authentication. You supply real auth for internet-facing apps.

---

Node.js

Claim	Status
Supported engines	>=22 <25
CI matrix	Node 22 and 24
Node 20	Not claimed

---

Quality & verification

CI runs verification on every push (workflow). Prefer the live workflow over fixed test-count claims.

Gate	Command
Lint + typecheck + unit tests + build	pnpm verify
Versioning integrity	pnpm verify-versioning
Public DX (pack + external install)	pnpm test:public-dx
Scaffold clean install	pnpm test:scaffold-dx
Tools / routing / tenant / streaming	pnpm test:tools · test:routing · test:tenant-isolation · test:streaming

---

Limitations

• Young ecosystem — limited external adoption evidence
• memory: true / inMemory() remain ephemeral by design (use fileMemory / postgresMemory for durability)
• No exactly-once external tool side effects for non-idempotent tools (idempotent + durable ledger is exactly-once-capable)
• No official GHCR image yet
• Embedded Simple mode ≠ hosted multi-tenant platform
• HTTP host SSE reconnect is separate from Simple stream({ resumeFrom }) / replayStream() — see stream replay

Available in v1.6

Capability	Simple API
Durable memory	fileMemory({ directory }), postgresMemory({ connectionString })
HITL wait / resume	approve / reject / resume; AGENT_TOOL_APPROVAL_REQUIRED includes approvalId + executionId
Stream replay	stream(input, { resumeFrom }), replayStream(executionId, afterSequence?)
Idempotent tool ledger	idempotency: "idempotent" + durable ledger — not a claim for non-idempotent external effects
Gemini	gemini(modelId) + @agentprodready/ai-provider-gemini

---

Security

• createAgent simple/embedded mode uses application-local security defaults — not production HTTP auth
• LocalReference host auth is development/reference only
• Report vulnerabilities privately via SECURITY.md

---

Community

Single maintainer today (ameenmari) — no foundation-scale governance claims. Stars, issues, and small PRs are genuinely useful.

Good first contributions (docs / examples / DX — not Runtime/Security redesigns):

• Improve an example README or add a focused recipe under examples/

• Record / polish the demo GIF (docs/community/assets/demo.gif)

• Fix package README clarity (standard)

• Add a getting-started issue reproduction or a test around Simple API DX

• CONTRIBUTING.md · CODE_OF_CONDUCT.md · SUPPORT.md

• ROADMAP.md · CHANGELOG.md · content plan

• Every public npm package ships install + sample code — start with @agentprodready/agent-framework

---

Architecture (after onboarding)

Capability-driven platform with explicit ownership: Runtime owns operational execution, Security owns authorization, Composition owns instantiation, Capability Resolution selects implementations.

Deep docs: Documentation index · Architecture index · Dependency graph · ADRs · Blueprints

Beginners should start with Getting Started — not Blueprints.

---

License

MIT — Copyright (c) 2026 ameenmari