What makes personaforge different
Every agent framework can spin up an agent. personaforge is the only TypeScript framework that ships durability, multi-agent orchestration, guardrails, eval, and a control-plane dashboard in a single npm install.
| Against | personaforge wins on |
|---|
| LangChain | Single package (not 200+). Built-in checkpoint/replay. MCP + A2A protocols. SSRF-protected tools. τ-bench cross-framework benchmarks. |
| Vercel AI SDK | Full agent runtime (not just streaming primitives). Sessions, memory, knowledge, teams, durability, guardrails, eval, control plane. |
| CrewAI | TypeScript-native. 6 team modes vs 2. Event-sourced durability. Built-in eval. 120+ tools. Graph DAG engine. |
| LangGraph | Same graph semantics in TypeScript — plus budget enforcement, guardrails, OTLP tracing, eval, and control plane in one install. |
| Mastra | Durable DAG engine, circuit breakers, USD budget caps, multi-tenancy, 100+ tools, and enterprise audit logging. |
| AutoGen / Agno | TypeScript-native. Durable interrupts + resume. Built-in guardrails + budget enforcement. OTLP tracing. Control plane dashboard. |
One quick example
import { agent } from 'personaforge/lite';
import { tool } from 'personaforge/tool';
import { z } from 'zod';
const getQuote = tool({
name: 'get_quote',
description: 'Return a stock quote for a ticker symbol.',
parameters: z.object({ symbol: z.string() }),
execute: async ({ symbol }) => ({ symbol, price: 927.5, changePct: 1.4 }),
});
const financeAgent = agent({
name: 'finance-agent',
model: 'gpt-4o-mini',
instructions: 'Use the tool to answer market questions in one concise sentence.',
tools: [getQuote],
});
const result = await financeAgent.run("What's NVDA trading at today?");
console.log(result.text); // "NVDA is trading at $927.50, up 1.4% today."
Installation
npm install personaforge
# or
bun add personaforge
Zero-config. Treeshakeable. No peer dependencies required for basic use.
Feature Overview
🤖 Agents & Tools
- ReAct agent runtime — think-act-observe loop with configurable max steps, timeout, retry, and tool error handling
- 30+ LLM providers (native) + 300+ via AI SDK adapter — OpenAI, Anthropic, Google Gemini, AWS Bedrock, Ollama, OpenRouter, plus any
@ai-sdk/provider model and more
- 120+ built-in tools — search (Tavily, Exa, Brave, Serper, Arxiv, PubMed, Perplexity, Reddit, YouTube), web scraping (FireCrawl, Newspaper), HTTP client with SSRF protection, filesystem, shell, browser, finance (Stripe, Yahoo), CRM, media, productivity
- Custom tools — define with Zod schemas, auto-JSON-schema conversion
- Tool composition —
compose, pipe, parallel, fallback, retry, timeout, map, filter
- Durable run store — every agent execution persisted with cost, status, tenant, error. InMemory, SQLite, or Postgres.
- Cost tracking — auto-estimated USD cost per LLM call in every
AgentRunResult. Zero instrumentation.
- Concurrency limits — bounded parallel execution with backpressure. Wire via gateway
maxConcurrency.
- Structured error taxonomy — 14 error classes with stable codes, HTTP mapping, and JSON serialization.
- Guardrail integration — tool calls and LLM output validated in the core runner. Block policy violations.
- Tenant-scoped knowledge — per-tenant document isolation in RAG queries.
🧠 Memory & Knowledge
- 4-layer memory architecture — short-term context, long-term vector, episodic workflow history, semantic graph memory
- Vector stores — in-memory, SQLite, Chroma, Pinecone, Redis, with OpenAI / custom embeddings
- RAG engine —
createKnowledgeBase with text splitters, BM25 indexing, hybrid RRF fusion, rerankers (Cohere, Jina, LLM), multi-query, contextual compression, parent-document, self-query, time-weighted retrievers
- Session stores — in-memory, SQLite (zero-server), Redis, fallback chain, PostgreSQL
👥 Multi-Agent Orchestration
| Mode | What it does |
|---|
| Supervisor | Manager delegates to specialists, reviews output |
| Swarm | Dynamic sub-agent scaling (up to 100 agents) |
| Consensus | Majority-vote, unanimous, or weighted voting across agents |
| Handoff | Agent-to-agent transfer with context |
| Router | Instruction/tool-based agent routing |
| Pipeline | Sequential agent composition |
| GSD | Goal-Strategy-Decomposition pattern |
| Team | Role-based team creation with permission isolation |
🔗 DAG Graph Engine
- Directed Acyclic Graph execution with sequential, parallel, branching, and joining topologies
- Conditional edges — output-driven routing (LangGraph parity):
addConditionalEdges('classify', { map: { positive: 'handle', negative: 'escalate' }, default: 'review' })
- State machine channels — typed state schemas with reducers, producers, consumers
- Event sourcing — every run recorded to append-only log (SQLite, Redis, in-memory)
- Deterministic replay — re-run from log with zero LLM calls for time-travel debugging, audit, simulation
- Tamper-evident audit — hash-chained event log with
verifyChain()
- Scheduler — cron, interval, event-driven, and delay-based execution
- Pluggable middleware — telemetry, logging, audit, custom plugins
interrupt() / resume() / fork() — durable checkpoints with DurableExecutor
🛡️ Production Safety
| Capability | What it does |
|---|
| Guardrails | PII detection/redaction, prompt injection detection (pattern + heuristic + LLM), content moderation (OpenAI Moderation API), allowlists for tools/hosts/output |
| HITL | Human-in-the-loop approval hooks with interrupt() / resume() |
| Budget enforcement | Per-user, per-session, and global token/cost caps |
| Rate limiting | Sliding-window (in-memory + Redis) |
| Circuit breaker | Provider failure detection and recovery |
| Idempotency | Deduplication of tool calls and agent runs |
| Graceful shutdown | Drain active executions before shutdown |
| Health checks | Readiness, liveness, and dependency probes |
| Secret management | Pluggable backends with live secret watching |
📊 Observability & Eval
- OTLP-native tracing — OpenTelemetry spans with gen-ai semantic conventions
- Prometheus metrics — request counts, latency, token usage, error rates
- LLM-as-judge — single-criterion and multi-criteria evaluation
- Benchmark runner — τ-bench harness with retail/data/coding domains (13 tasks)
- Cross-framework comparison — scores personaforge vs LangGraph, Agno, CrewAI, Mastra on identical tasks via
benchmarks/tau-bench/PROTOCOL.md
- Regression detection —
replayDataset, diffResults for eval regression
- Trace ↔ Dataset —
spanToSample converts production traces to eval datasets
🚀 Serving & Runtime
- HTTP server —
createHttpService with OpenAPI generation, admin API, WebSocket transport
- Framework adapters — Express router, Fastify plugin, Hono route (all lazy-loaded)
- SSE streaming —
text/event-stream for real-time agent responses
- A2A protocol — Agent-to-Agent communication server
- Background queues — InMemory, BullMQ, Kafka, RabbitMQ, SQS, Redis PubSub
- Scheduled agents — cron and interval-based execution
- CLI —
npx personaforge for quick agent runs
🛂 Enterprise Gateway
One declarative config turns on authentication, multi-tenant isolation, RBAC,
budget enforcement, rate limiting, and durable audit — plus a board-ready
compliance dashboard (SOC 2, HIPAA, GDPR, ISO 27001).
import { createAgent } from 'personaforge';
import { createEnterpriseGateway } from 'personaforge/gateway';
import { apiKeyAuth } from 'personaforge/runtime';
import { createSqliteAuditStore, createSqliteRunStore } from 'personaforge/production';
const support = createAgent({ name: 'support', instructions: 'You are a support agent.' });
const billing = createAgent({ name: 'billing', instructions: 'You handle billing questions.' });
const gateway = createEnterpriseGateway({
agents: { support, billing },
auth: apiKeyAuth([process.env.GATEWAY_API_KEY!]),
runStore: createSqliteRunStore('./runs.db'), // ← every run persisted (cost, status, tenant)
maxConcurrency: 25, // ← at most 25 concurrent agent executions
tenants: [
{
id: 'acme',
monthlyBudgetUsd: 500,
maxRpm: 60,
allowedAgents: ['support', 'billing'],
},
],
policy: { monthlyBudgetUsd: 5000, requestTimeoutMs: 60_000 },
auditStore: createSqliteAuditStore('./audit.db'),
});
await gateway.start(8787);
// → http://localhost:8787/compliance (compliance dashboard)
| Capability | What it does |
|---|
| Multi-tenant | Per-tenant budgets, rate limits, agent allowlists, RBAC |
| Policy engine | Global + per-tenant USD caps, RPM limits, timeouts |
| Audit trail | Hashed prompts, IPs, costs, tools called — SOC 2 ready |
| Compliance dashboard | /compliance — live SOC 2 / HIPAA / GDPR / ISO 27001 controls |
🎛️ Control Plane Dashboard
Built-in AgentOS dashboard served by createControlPlane():
| Tab | What it shows |
|---|
| Overview | Session count, eval runs, traces, pending approvals |
| Sessions | Browse with search, view full conversation history |
| Memory | Inspect vector and graph memory stores |
| Evals | Pass/fail rates, score distribution, run history |
| Traces | Waterfall timeline visualization |
| Approvals | HITL queue with approve/reject buttons |
| Knowledge | Document browser with search |
| Chat | Interactive playground with agent selector |
| Graph | DAG workflow visualizer with SVG rendering |
📦 Structured & Composable
- Structured output — unified JSON-schema generation across OpenAI, Anthropic, Gemini
- Output parsers — JSON (Zod-aware), CSV, Regex, output-fixing, retry-with-error
- Runnable / LCEL —
pipe(), batch(), stream(), withRetry(), withFallbacks(), assign()
- Event streaming — LangGraph-style
values | updates | messages | debug | custom modes
- Reasoning tools — Agno-style
think / analyze scratchpad tools
- Native reasoning streaming —
onReasoning, result.reasoning, reasoning-delta stream events for Anthropic, Bedrock, Gemini, Ollama, and OpenAI-compatible thinking models
- Deep research agent —
createDeepAgent plan-research-synthesize recipe
Three Primitives
| Primitive | When to use |
|---|
| Agent | One model-backed worker can handle the task |
| Team | Specialists should coordinate, delegate, or vote |
| Workflow | Execution path should be staged, deterministic, or branching |
How to adopt
- One agent, one run — start boring
- Add one capability at a time — a tool, a session store, memory
- Add runtime surfaces — HTTP serving, scheduling, eval, resilience
Each layer is optional. Most projects only need a subset.
Migrate from
Repository stats
| Metric | Count |
|---|
| Source files | 570+ |
| Lines of TypeScript | 112,000+ |
| Test files | 92 |
| Lines of test code | 15,800+ |
| Built-in tools | 120+ (across 20 categories) |
| LLM provider integrations | 30+ native + 300+ via AI SDK adapter |
| Production primitives | 20+ (run store, error taxonomy, concurrency, circuit breaker, rate limiter, ...) |
| Graph DAG engine | 5,200+ lines |
| Entry points (treeshakeable) | 75+ |
Adopters
Using personaforge in production? Add yourself to ADOPTERS.md.
License
MIT
