Teams building agents in TypeScript now have four widely used open-source options, and their documentation uses different words for the same ideas, which makes a like-for-like comparison slow. This page sets the AI SDK from Vercel, LangGraph.js from LangChain, Mastra and the OpenAI Agents SDK for JavaScript side by side, using identical fields drawn only from each project's official repository and documentation. It covers licence, runtime requirements, the agent and workflow model, tool approval, MCP support, state and memory, and tracing. It is written for engineers choosing a stack, architects reviewing what is already in use and security teams who need to know where data and credentials flow. Frameworks are listed alphabetically throughout, and order is never a ranking. Last checked: 2026-11-15.
This is an independent reference page from NHI Mgmt Group based on public provider documentation; it is not sponsored or endorsed by any provider.
Key takeaways
- All four are open source, with two licence families. The AI SDK and Mastra core are Apache 2.0 (Mastra keeps code in
ee/directories under a separate enterprise licence), while LangGraph.js and the OpenAI Agents SDK for JavaScript are MIT. - Each one targets a different level of abstraction. The AI SDK centres on model calls and a tool loop, LangGraph.js on a low-level stateful graph, Mastra on agents plus a workflow engine, and the OpenAI Agents SDK on agents, handoffs and guardrails.
- All four document MCP client support. Each project names its own MCP classes or functions and transports, and Mastra also documents an MCP server class for exposing agents and tools.
- Human approval works differently in each. The approval flow ranges from per-call status values to graph interrupts, workflow suspension and serialisable run state, so approval design has to follow the framework.
- Tracing defaults differ and matter for data handling. Check where each framework sends traces by default before production, especially where prompts or tool arguments contain personal data or secrets.
What is a TypeScript agent framework?
A TypeScript agent framework is a library that runs the loop in which a language model chooses tools, the code executes them and the results go back to the model until a stopping condition is met. Beyond that loop, frameworks add some mix of multi-step workflows, state persistence, human approval, model provider abstraction, MCP connectivity and tracing. The four projects on this page all run on Node.js and publish their packages on npm. For the wider landscape, including Python frameworks and managed platforms, see the AI Agent Frameworks and Platforms Hub (2026), and for the distinction between frameworks and hosted services see Agent Frameworks vs Managed Agent Platforms.
The four frameworks at a glance
As of 15 November 2026, from each project's repository LICENSE file, package.json and README on the main branch.
| Field | AI SDK (Vercel) | LangGraph.js (LangChain) | Mastra | OpenAI Agents SDK for JavaScript |
|---|---|---|---|---|
| Repository | vercel/ai | langchain-ai/langgraphjs | mastra-ai/mastra | openai/openai-agents-js |
| Main npm package | ai | @langchain/langgraph | @mastra/core | @openai/agents |
| Licence | Apache 2.0 | MIT | Apache 2.0, except ee/ directories under the Mastra Enterprise License | MIT |
| Node.js engine in package.json or README | Node.js 22 or later | Node.js 18 or later | Node.js 22.13.0 or later | Node.js 22 or later; Deno and Bun; Cloudflare Workers with nodejs_compat marked experimental |
| Self-description | Provider-agnostic TypeScript toolkit for AI applications and agents | Low-level orchestration framework for building stateful agents | Framework for AI applications and agents with a TypeScript stack | Lightweight framework for multi-agent workflows, provider-agnostic |
| Core agent primitive | ToolLoopAgent (plus HarnessAgent for preconfigured harnesses) | State graph with nodes and edges; Deep Agents as a higher-level package | Agent class plus a graph-based workflow engine | Agent, SandboxAgent and RealtimeAgent |
| Model access | Unified provider API; model strings route through Vercel AI Gateway by default, or provider packages such as @ai-sdk/openai | Through LangChain model integrations in @langchain/core | Model router with 40+ providers through one interface | OpenAI APIs by default; described as supporting other providers |
| Product guide | None on nhimg.org | LangChain and LangGraph | What Is Mastra? TypeScript Agent Framework Explained | OpenAI Agents SDK and AgentKit |
Note on versions: package version numbers change weekly and the main branch often carries pre-release tags, so this page does not quote them. Pin the version you test in your lockfile and record it in your inventory.
How does each framework model an agent?
AI SDK: the ToolLoopAgent class runs the model and tools in a loop. The loop control documentation states that it stops after 20 steps by default, equivalent to isStepCount(20), described as a safety measure against runaway loops. Other stop helpers are hasToolCall(...) and isLoopFinished(), and prepareStep adjusts settings between steps. A shared runtimeContext carries state between steps. The AI SDK UI module adds hooks for Next.js, React, Svelte and Vue, and createAgentUIStreamResponse streams an agent to a route handler.
LangGraph.js: you define a graph of nodes that read and write shared state, compile it and invoke it. The README lists durable execution, human-in-the-loop, short-term and long-term memory, and LangSmith debugging as its main features, and states that LangGraph is inspired by Pregel and Apache Beam and can be used without LangChain. Deep Agents is a higher-level package built on LangGraph for agents that plan, use subagents and work with file systems.
Mastra: agents reason over goals, choose tools and iterate until the model returns a final answer or an optional stopping condition is met. When explicit control is needed, Mastra workflows use a graph-based engine with .then(), .branch() and .parallel() control flow. Mastra Studio, served locally on port 4111 in the default project, is a UI for building and testing agents, workflows and tools.
OpenAI Agents SDK for JavaScript: agents are models configured with instructions, tools, guardrails and handoffs. Other agents can be used as tools or receive a handoff. SandboxAgent pairs an agent with a filesystem workspace through sandbox clients (local Unix, Docker or hosted), and RealtimeAgent with RealtimeSession supports low-latency voice in the browser. Sessions manage conversation history across runs.
Which features does each framework document?
As of 15 November 2026, from official documentation pages listed under Standards and references.
| Capability | AI SDK (Vercel) | LangGraph.js (LangChain) | Mastra | OpenAI Agents SDK for JavaScript |
|---|---|---|---|---|
| Loop or run control | stopWhen, prepareStep; default 20 steps | Graph edges and conditional routing | Stopping condition on agents; workflow control flow | Runner with run configuration; handoffs between agents |
| Human approval | toolApproval on generateText, streamText or ToolLoopAgent | interrupt() inside a node, resumed with new Command({ resume }) | Suspend and resume for agents and workflows; requireToolApproval on MCP servers | needsApproval on tools; pending calls in result.interruptions |
| State persistence | Application stores messages, for example in the onEnd callback | Checkpointers: MemorySaver, PostgresSaver, SqliteSaver, keyed by thread_id | Memory from @mastra/memory on a storage provider such as LibSQLStore, keyed by thread and resource | Sessions; RunState serialised with toString() and restored with RunState.fromString() |
| MCP client | createMCPClient from @ai-sdk/mcp | MCPAdapter from @langchain/mcp-adapters (2.0 or later) | MCPClient from @mastra/mcp | MCPServerStdio, MCPServerStreamableHttp, MCPServerSSE, grouped by MCPServers |
| MCP transports documented | HTTP (recommended for production), SSE, stdio (local servers only), custom MCPTransport | stdio, Streamable HTTP (default for URLs), SSE for legacy servers | stdio and Streamable HTTP, on MCP revision 2026-07-28 | stdio, Streamable HTTP, SSE |
| Tracing and telemetry | OpenTelemetry integration from @ai-sdk/otel, active once registered with registerTelemetry | LangSmith for tracing and evaluation | OpenTelemetry-compatible spans; exporters include MastraStorageExporter, MastraPlatformExporter, ArizeExporter, LangfuseExporter | Built-in tracing exported through OpenAITracingExporter; custom processors with addTraceProcessor() |
| Evaluation | Not stated by Vercel on the pages checked | LangSmith evaluations | Built-in evals | Not stated by OpenAI on the pages checked |
How does human approval work in each framework?
Approval is where the frameworks differ most, and it is the control that most often stands between an agent and an irreversible action. For the design patterns themselves, see the Human-in-the-Loop for AI Agents Guide.
- AI SDK: set
toolApprovalwith a status per tool ('not-applicable'by default,'approved','denied'or'user-approval') or a single function. The call does not pause: it returnstool-approval-requestparts, your code collects the decision, appends atool-approval-responseand calls again. The olderneedsApprovalproperty ontool()is documented as deprecated but still working, and provider-executed tools ignoretoolApproval. - LangGraph.js: call
interrupt()inside a node to pause, read the payload under__interrupt__, then resume withnew Command({ resume: value }). A checkpointer is a stated prerequisite, and you resume with the samethread_id, so approval state lives wherever the checkpointer stores it. - Mastra: agents and workflows can suspend and await input or approval, using storage to remember execution state so they can resume later. For MCP tools,
requireToolApproval: truegates every tool on a server, or a function can decide per call from tool name, arguments or annotations. The docs advise treating annotations from servers you do not control as untrusted hints. - OpenAI Agents SDK for JavaScript: set
needsApprovalon a tool totrueor an async function. Pending calls appear inresult.interruptionsand are resolved withresult.state.approve()orresult.state.reject(), optionally sticky for the run. The docs state thatRunState.fromString()does not authenticate the snapshot, so deserialise only from trusted storage and keep approval state on the server for browser or mobile clients.
Where does data go by default?
As of 15 November 2026.
| Data path | AI SDK (Vercel) | LangGraph.js (LangChain) | Mastra | OpenAI Agents SDK for JavaScript |
|---|---|---|---|---|
| Model calls | Model strings use Vercel AI Gateway by default; provider packages call providers directly | The configured LangChain model integration | The configured provider through the model router | OpenAI APIs by default, or the configured provider |
| Traces | Sent wherever the registered telemetry integration exports; nothing until one is registered | To LangSmith when you configure it | To the configured exporters | On by default in Node.js, Deno and Bun, exported to the OpenAI Traces dashboard; off in browsers and when NODE_ENV=test |
| How to switch off or redirect | Per call with telemetry: { isEnabled: false } | Do not configure LangSmith, or point it at your own deployment | Choose exporters in configuration | OPENAI_AGENTS_DISABLE_TRACING=1 globally, tracingDisabled per runner; the docs state tracing is unavailable under an OpenAI Zero Data Retention policy |
| Conversation state | Your own store | The checkpointer you choose | The storage provider you choose | Sessions and serialised run state you store |
For each framework, the credential that reaches the model provider, the tracing backend and any MCP server is a non-human identity in its own right. Record it, scope it and rotate it. See Agent Observability vs Audit Logging for why traces alone are not an audit trail.
How to choose: factual criteria
These criteria are questions to answer for your own system, not a ranking. The right answer for a small team shipping a chat feature differs from that for a platform team running long-lived workflows.
| If your requirement is... | Check in each framework |
|---|---|
| Streaming agent output into a React, Next.js, Svelte or Vue front end | Whether UI hooks or integrations are documented (AI SDK UI hooks; Mastra documents integration with AI SDK UI and CopilotKit; LangGraph.js publishes a streaming cookbook; the OpenAI SDK documents realtime browser sessions) |
| Long-running work that survives restarts | Which durable store backs pause and resume: checkpointers, Mastra storage, serialised RunState or your own message store |
| Explicit, auditable control flow | Graph definitions in LangGraph.js, Mastra workflows, handoff rules in the OpenAI SDK, step controls in the AI SDK |
| Strict licence policy | MIT or Apache 2.0 terms, and for Mastra whether any ee/ code is in your dependency tree |
| Runtime outside Node.js | Stated support for Deno, Bun, edge or browser runtimes and the Node.js minimum in each package |
| Data residency or no third-party telemetry | Default model routing and tracing destinations in the table above |
| Many existing MCP servers | Supported transports, approval hooks for MCP tools and the MCP revision each client implements |
Small organisations: fewer moving parts usually matters more than graph expressiveness, so weigh how much state infrastructure each option requires. Large organisations: weigh how approval state, traces and credentials fit existing logging, secrets and change control, and require a pinned, reviewed version per service.
Where identity and security fit
Every framework here executes tool calls with whatever credentials your code hands it, so the security work is mostly yours. Keep API keys for model providers, gateways, tracing backends and MCP servers in a secrets manager rather than .env files in repositories, give each agent its own scoped credential, and log tool calls with the identity that made them. Framework packages are also part of your software supply chain: pin versions, review install scripts and prefer packages published with provenance. For the controls in depth see the Securing Agent Frameworks Guide, and the framework-specific pages: LangChain and LangGraph Security Guide, Mastra Agent Framework Security Guide, Securing OpenAI Agents SDK and Responses API Guide and, for the platform behind AI Gateway, the Vercel Security Guide. For package hygiene, see the npm Install-Time Security Guide.
Common failure patterns
- Assuming approval pauses execution: in the AI SDK manual flow the call returns approval request parts rather than blocking, so code that ignores them never asks a human. Test that a denied call reaches the model as denied.
- In-memory state in production:
MemorySaverandInMemorySaverlose checkpoints on restart, which silently drops pending approvals. Use a durable checkpointer or store for anything a human will resume later. - Trusting client-held run state: a serialised run or approval snapshot returned from a browser can be edited. Keep it server-side, as the OpenAI SDK documentation advises.
- Unplanned trace export: tracing that is on by default, or an exporter added during development, can send prompts and tool arguments to a third-party backend. Review exporter configuration in every environment.
- Legacy MCP transports by habit: SSE remains available in several clients for older servers. Prefer Streamable HTTP for remote servers; see MCP SSE to Streamable HTTP Migration.
Practitioner checklist
- Record framework, package name, pinned version, licence and Node.js minimum for every agent service in your inventory.
- For Mastra deployments, confirm whether any
ee/features are in use and whether the enterprise licence terms apply in production. - Decide the tracing destination before the first production run, and for the OpenAI Agents SDK set
OPENAI_AGENTS_DISABLE_TRACING=1or a custom processor if traces must not leave your environment. - Gate every destructive or external-facing tool with the framework's approval mechanism and test both the approve and deny paths.
- Store approval and run state server-side in a durable, access-controlled store; never accept serialised run state from a client.
- Set explicit loop limits rather than relying on defaults, and alert when runs hit them.
- List every MCP server each agent connects to, its transport and its credential, and restrict stdio servers to local, trusted binaries.
- Give each agent its own scoped model and tool credentials, held in a secrets manager and rotated on a schedule.
Standards and references
- Vercel: AI SDK repository, LICENSE and README (accessed 2026-11-15)
- Vercel: AI SDK Agents overview and loop control (accessed 2026-11-15)
- Vercel: AI SDK tools, tool approval, MCP tools and telemetry documentation (accessed 2026-11-15)
- LangChain: LangGraph.js repository, LICENSE and README (accessed 2026-11-15)
- LangChain: LangGraph.js persistence, interrupts and MCP adapter documentation (accessed 2026-11-15)
- Mastra: repository, LICENSE.md and README (accessed 2026-11-15)
- Mastra: MCP, memory and observability documentation (accessed 2026-11-15)
- OpenAI: Agents SDK for JavaScript repository, LICENSE and README (accessed 2026-11-15)
- OpenAI: Agents SDK for JavaScript tracing, human-in-the-loop and MCP guides (accessed 2026-11-15)
Related NHI Mgmt Group resources: AI Agent Frameworks and Platforms Hub (2026), AI Agent Platforms Compared, Securing Agent Frameworks Guide, MCP Security Guide, Agent Identity and Access Guide.