convez.ai
MCP ServerDesenvolvimento WebAvançado
Varun-Patkar

Agent Framework JS

Varun-Patkar/agent-framework-js

Framework de agentes IA modular para apps sem servidor em TypeScript

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework modular e tree-shakeable para construir e orquestrar agentes de IA em aplicações sem backend (browser, edge, Node). Suporta agents, ferramentas de código, MCP, skills, workflows multi-agent, middleware, persistência e observabilidade com OpenTelemetry.

Instalação

$npx convez-ai Varun-Patkar/agent-framework-js

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
—
Issues abertas
3
Contribuidores
1

Casos de uso

  • Construir agentes de IA em aplicações frontend
  • Orquestrar workflows com múltiplos agentes
  • Integrar MCP e skills em ambientes edge/serverless

Veredito

Framework robusto e bem arquitetado para quem precisa de agentes de IA em ambientes sem backend. Suporta OpenAI e GitHub Copilot com abstração plugável, mas exige conhecimento técnico profundo em TypeScript e orquestração de agentes.

README

A tradução para o português deste README ainda está na fila.

agent-framework-js

npm version CI License: MIT Types Node

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

AreaEntryNotes
Agentsagentstext + multimodal input, streaming, reasoning field, threads with compaction
ProvidersprovidersCopilot + OpenAI-compatible; caller-injected credentials; retry/backoff
Toolstoolslocal function tools, JSON-Schema validation, namespacing, enable/disable
MCPmcpremote (HTTP/SSE) with custom headers everywhere; stdio in Node only
Skillsskillsprogressive disclosure; client-side keyword index
Workflowsworkflowssequential / concurrent / handoff / group; HITL; checkpoints
Middlewaremiddlewarerequest/response pipeline
Persistencepersistencein-memory + browser (localStorage/IndexedDB)
ObservabilityobservabilityOpenTelemetry spans with secret redaction
DeclarativedeclarativeYAML 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.

KnobWhereDefaultNotes
maxIterationscreateAgent10-1 = unlimited tool-call iterations
toolTimeoutMscreateAgentnoneper-tool-call timeout
compactionThresholdcreateAgent0.9fraction of maxInputTokens before compaction
compactionModelcreateAgentown provideroverride model for summaries
retry.maxRetriesprovider3transient-error retries (429/5xx/network)
maxRoundscreateWorkflow16-1 = unlimited; or end via completion signal
failurePolicycreateWorkflowfail-softor fail-fast
maxConcurrencycreateWorkflow4-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:

ScenarioBackend (Fastify, serves rich HTML)Frontend (React + Vite, no backend)
Single-turn agent + calculator MCPexamples/backend/single-agent-mcpexamples/frontend/single-agent-mcp
Multi-turn orchestrator + 2 subagentsexamples/backend/orchestrator-subagentsexamples/frontend/orchestrator-subagents
Workflow with live agent-order visualsexamples/backend/workflow-visualexamples/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

Ver o original no GitHub

Bom para

Relacionados