Confused-AI

---

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

1. One agent, one run — start boring
2. Add one capability at a time — a tool, a session store, memory
3. Add runtime surfaces — HTTP serving, scheduling, eval, resilience

Each layer is optional. Most projects only need a subset.

---

Migrate from

From	Guide
LangChain	docs/guide/migration-langchain.md
Vercel AI SDK	docs/guide/migration-vercel.md
CrewAI	docs/guide/migration-crewai.md
LangGraph	docs/guide/migration-langgraph.md
Mastra	docs/guide/migration-mastra.md
Agno	docs/guide/migration-agno.md
All frameworks	docs/guide/comparisons.md
Trust & reliability	docs/guide/trust.md

---

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