agent-framework-js

agent-framework-js

A modular, tree-shakeable JavaScript/TypeScript framework for building and orchestrating AI agents in no-backend deployments — browser, edge runtimes (e.g. Vercel without serverless functions), and Node. It mirrors the in-scope capability set of Microsoft Agent Framework: agents, code tools, MCP, skills, multi-agent workflows, middleware, persistence, and OpenTelemetry observability.

LLM providers are intentionally limited to GitHub Copilot and OpenAI-compatible endpoints (e.g. LM Studio) behind a pluggable abstraction.

Install

npm install agent-framework-js

Optional peer dependencies (installed only if you use the feature):

• @modelcontextprotocol/sdk — MCP integration
• @opentelemetry/api — tracing
• yaml — YAML declarative definitions

Quick start

import { createAgent, createOpenAICompatibleProvider } from "agent-framework-js";

const provider = createOpenAICompatibleProvider({
  baseUrl: "http://localhost:1234/v1", // LM Studio
  getCredential: () => process.env.LMSTUDIO_KEY ?? "",
  capabilities: { model: "local-model", maxInputTokens: 262144, maxOutputTokens: 32000 },
});

const agent = createAgent({ name: "Helper", instructions: "Be concise.", provider });
const res = await agent.run("Say hello.");
console.log(res.status, res.output);

Multiple models (e.g. GitHub Copilot)

A provider can expose several models. Supply models (with an optional defaultModel), then pick one per agent (model) or per request. OpenAI-compatible endpoints are usually single-model, so the capabilities shorthand still works there.

import { createAgent, createCopilotProvider } from "agent-framework-js";

const copilot = createCopilotProvider({
  getCredential: () => myCopilotToken,
  models: [
    { model: "gpt-4o", maxInputTokens: 128000, maxOutputTokens: 16000, supportsVision: true },
    { model: "o3-mini", maxInputTokens: 200000, maxOutputTokens: 100000, supportsReasoning: true },
  ],
  defaultModel: "gpt-4o",
});

// Per agent — capabilities (vision/reasoning/context) follow the chosen model:
const reasoner = createAgent({
  name: "Thinker",
  instructions: "Reason.",
  provider: copilot,
  model: "o3-mini",
});

// Per request:
await copilot.generate({ messages, model: "o3-mini" });

Prefer deep imports for the smallest bundle: agent-framework-js/agents, /providers, /tools, /mcp, /skills, /workflows, /middleware, /persistence, /observability, /declarative.

Features

Area	Entry	Notes
Agents	agents	text + multimodal input, streaming, reasoning field, threads with compaction
Providers	providers	Copilot + OpenAI-compatible; caller-injected credentials; retry/backoff
Tools	tools	local function tools, JSON-Schema validation, namespacing, enable/disable
MCP	mcp	remote (HTTP/SSE) with custom headers everywhere; stdio in Node only
Skills	skills	progressive disclosure; client-side keyword index
Workflows	workflows	sequential / concurrent / handoff / group; HITL; checkpoints
Middleware	middleware	request/response pipeline
Persistence	persistence	in-memory + browser (localStorage/IndexedDB)
Observability	observability	OpenTelemetry spans with secret redaction
Declarative	declarative	YAML or JSON agent definitions

Credential handling

Credentials are always supplied via a callback and are never bundled, persisted, or logged.

• Frontend-only: the end user supplies their own token; it stays client-side.
• Backend: the developer may supply it, or the user sends it per request over SSL/TLS — and the backend must never log or persist it.

Configurable safeguards (defaults & customization)

All safeguards ship with safe defaults and are fully overridable. Set a value to -1 for unlimited where noted.

Knob	Where	Default	Notes
maxIterations	createAgent	10	-1 = unlimited tool-call iterations
toolTimeoutMs	createAgent	none	per-tool-call timeout
compactionThreshold	createAgent	0.9	fraction of maxInputTokens before compaction
compactionModel	createAgent	own provider	override model for summaries
retry.maxRetries	provider	3	transient-error retries (429/5xx/network)
maxRounds	createWorkflow	16	-1 = unlimited; or end via completion signal
failurePolicy	createWorkflow	fail-soft	or fail-fast
maxConcurrency	createWorkflow	4	-1 = unlimited parallel agent/tool calls

Runtime support

Core features use only web-standard APIs and run in browser, edge, and Node. Node-only features (stdio MCP, filesystem storage) are gated by runtime detection and throw a typed RuntimeUnsupportedError when unavailable.

The GitHub Copilot provider cannot be used directly from a browser: api.githubcopilot.com sends no CORS headers, so createCopilotProvider throws RuntimeUnsupportedError when constructed in a browser against the default host. Run it server-side (Node/edge), or route through a lightweight proxy (e.g. a Vite dev-server proxy) and set baseUrl to your proxy. See the agent-usage skill for a proxy example.

Examples

Runnable examples live in examples/ as a single npm workspace (deps are hoisted, so one install covers everything). They consume the published agent-framework-js package and act as a live check of the public API. Each of the three scenarios ships in two flavors:

Scenario	Backend (Fastify, serves rich HTML)	Frontend (React + Vite, no backend)
Single-turn agent + calculator MCP	examples/backend/single-agent-mcp	examples/frontend/single-agent-mcp
Multi-turn orchestrator + 2 subagents	examples/backend/orchestrator-subagents	examples/frontend/orchestrator-subagents
Workflow with live agent-order visuals	examples/backend/workflow-visual	examples/frontend/workflow-visual

The two multi-agent scenarios map to the definitive orchestration recipes documented for AI agents in the agent-usage skill: the orchestrator + subagents example is Recipe A (subagents exposed as tools, dynamic routing) and the workflow example is Recipe B (a fixed Planner → Calculator → Summarizer pipeline).

Every example has a GitHub Copilot ⇄ LM Studio toggle (LM Studio is assumed to be running locally). The differences between the two flavors mirror real deployment constraints:

• Credentials. Backend examples read the Copilot token server-side from examples/.env (COPILOT_TOKEN). Frontend examples cannot ship a secret, so the user pastes their own token into the UI; Copilot is reached through a Vite dev proxy (/copilot) because the browser cannot call api.githubcopilot.com directly (no CORS), which also lifts the framework's browser guard.
• MCP transport. Backend examples support both stdio (spawning bunx @cyanheads/calculator-mcp-server) and http. Frontend examples are http-only — the browser cannot spawn a stdio process — and proxy the hosted calculator MCP server via Vite.

Run an example (installs once at the workspace root):

cd examples
npm install
cp .env.example .env        # backend only: set COPILOT_TOKEN if you use Copilot

# Backends (each serves its UI on http://localhost:3001-3003):
npm run be:single
npm run be:orchestrator
npm run be:workflow

# Frontends (Vite dev server on http://localhost:5101-5103):
npm run fe:single
npm run fe:orchestrator
npm run fe:workflow

The examples are intentionally minimal — they just use the framework — and are excluded from the published package.

Scripts

npm run build      # dual ESM + CJS + .d.ts
npm test           # vitest
npm run lint
npm run typecheck

Agent usage guide

A complete, agent-facing usage guide is bundled as a skill at .github/skills/agent-framework-usage/SKILL.md. Any AI coding agent working in this repository can load that skill to understand how to install, configure, and use the entire public API (providers, agents, tools, MCP, skills, workflows, persistence, observability, declarative agents, safeguards, and the typed error model). It is kept in sync with the implemented surface.

License

MIT