Streaming chat inside a React or Next.js product points to the Vercel AI SDK. Stateful agent workflows with tracing point to LangGraph.js or Mastra. A vendor you will never change points to its own SDK. One small backend API across OpenAI, Claude, Gemini and local models, with a Python twin, is where IntelliNode fits. Below are the numbers, the code, and where each option falls short.

What a Node.js LLM library should do for you​

Every option can send a prompt and return text. The differences show up in the second month, when you add tools, need JSON you can store, or hit a 429 at peak traffic. A useful library gives you:

• One interface across models, so switching vendor means changing a provider name and a key, not call sites.
• Tool calling with a bounded loop: the model asks for a function, your code runs it, and a step limit stops runaway loops.
• Structured output that follows a JSON Schema, using each provider's native mode.
• Streaming for chat interfaces, with cancellation.
• Errors you can branch on: timeouts, retries with backoff, and the HTTP status on the error, so a 429 can fall back to another model while a 401 fails loudly.

Then the business questions: how much code is tied to one vendor's format, whether a workload can move to a cheaper model without a sprint of refactoring, how long until the first feature ships, and who maintains it when its champion changes teams. With Python services too, ask whether prompts and tool schemas can be shared or will live twice.

The options at a glance​

The download figures come from the npm registry API for the week of 2026-09-22 to 2026-09-28 (api.npmjs.org/downloads/point/last-week/<package>), pulled on 2026-09-30. They include CI installs and transitive dependencies, so read them as ecosystem size, not quality.

Provider SDKs: the baseline​

The official SDKs are typed, maintained by the vendor, and get new features first. If you use one model family and will not change, they are the right call.

The cost shows up later. Each vendor has its own message format, tool schema and streaming events, so a tool loop written against openai has to be rewritten to run on Claude, tests included. Teams usually find this out the week procurement asks for a price comparison.

Vercel AI SDK​

The AI SDK is a TypeScript toolkit for AI apps and agents. AI SDK Core gives one API for text, structured objects, tool calls and agents. AI SDK UI adds useChat, useCompletion and useObject hooks for React, Svelte, Vue.js and Angular. Providers ship as packages such as @ai-sdk/openai, and Ollama is covered by a community provider.

It is the strongest choice when your product streams chat into a web UI. Check two things: a backend-only service uses just the Core half, and a Python team next to you will need a different library. Teams looking for a Vercel AI SDK alternative are usually in one of those two spots.

LangChain.js and LangGraph.js​

LangChain.js has a very large integration catalog: model providers, tools, vector stores and retrievers. LangGraph.js adds agents and controllable workflows built as graphs, and LangSmith covers testing and monitoring. It runs in Node.js, browsers, Deno, Bun and Cloudflare Workers.

Pick it for many integrations, stateful multi-step agents, or a tracing product your ops team already uses. The price is abstraction: for one prompt and two tools, there are several layers between your code and the HTTP request, and that is where debugging time goes.

Mastra and the OpenAI Agents SDK​

Mastra is a TypeScript framework with agents, a graph-based workflow engine (.then(), .branch(), .parallel()), memory, human-in-the-loop suspend and resume, MCP, evals, observability and routing to 40+ providers. The OpenAI Agents SDK centers on agents, handoffs, guardrails, sessions and tracing, plus realtime voice agents. It calls itself provider agnostic and reaches other models through an AI SDK integration.

A TypeScript AI agent framework earns its structure when you have several agents, approval steps, and evals that gate a release. For a summarize endpoint, it is more framework than the job needs.

Where IntelliNode fits​

IntelliNode (intellinode on npm) sits at the light end: a unified LLM SDK, not a framework. One Chatbot class covers OpenAI, Anthropic, Gemini, Mistral, Cohere, NVIDIA and vLLM, plus presets for OpenAI-compatible services (OpenRouter, Groq, DeepSeek, xAI, Together, Ollama, LM Studio). It adds a tool loop, schema-based JSON, streaming, MCP and TypeScript types.

One call shape for OpenAI, Claude and a local model​

const { Chatbot, ChatGPTInput, AnthropicInput, OpenAICompatibleInput } = require('intellinode');

const system = 'You are a billing support assistant. Answer in two sentences.';
const question = 'A customer was charged twice this month. What should we check first?';

async function ask(bot, input) {
  input.addUserMessage(question);
  const [answer] = await bot.chat(input);   // chat() resolves to an array of replies
  return answer;
}

async function main() {
  const openai = new Chatbot(process.env.OPENAI_API_KEY, 'openai');            // gpt-5.5, Responses API
  const claude = new Chatbot(process.env.ANTHROPIC_API_KEY, 'anthropic');      // claude-sonnet-5
  const local = new Chatbot(null, 'ollama', null, { model: 'qwen2.5:0.5b' });  // no key, runs on your machine

  console.log(await ask(openai, new ChatGPTInput(system, { effort: 'low' })));
  console.log(await ask(claude, new AnthropicInput(system, { maxTokens: 4096 })));   // Claude 5 thinking counts toward maxTokens
  console.log(await ask(local, new OpenAICompatibleInput(system)));
}
main();

Only the key, the provider name and the input class change. Claude 5 counts thinking toward maxTokens, so the 2048 default is raised. The local line needs no key, which makes it a free way to test the plumbing in CI. Chatbot.createInput(bot.provider, system) can pick the input class for you, as the seam example below shows.

A tool calling agent in about 20 lines​

const { Chatbot, AnthropicInput } = require('intellinode');

const tools = [{
  name: 'get_invoice',
  description: 'Look up an invoice by id and return its amount and payment status',
  parameters: {
    type: 'object',
    properties: { invoiceId: { type: 'string' } },
    required: ['invoiceId'],
  },
  handler: async ({ invoiceId }) => ({ invoiceId, amount: 129, currency: 'USD', status: 'charged twice' }),
}];

async function main() {
  const bot = new Chatbot(process.env.ANTHROPIC_API_KEY, 'anthropic');
  const input = new AnthropicInput('You are a billing assistant. Always call get_invoice before answering.', { maxTokens: 4096 });
  input.addUserMessage('What is the status of invoice INV-2041?');

  const { text, steps } = await bot.runTools(input, tools, { maxSteps: 3 });
  console.log(steps.map((step) => step.name));   // [ 'get_invoice' ]
  console.log(text);
}
main();

runTools calls the model, runs every tool it asks for, sends the results back, and repeats until the model answers in text. maxSteps caps the tool rounds and the call throws after that, so a confused model cannot loop forever. The same call works with ChatGPTInput, GeminiInput and OpenAICompatibleInput. It appends tool turns to the input, so build a fresh input per request.

On local models: with qwen2.5:0.5b on Ollama, this agent called the tool in 3 of 6 runs and answered without it in the others. Use a capable model for agents. The tool calling docs cover handler errors and handling tool calls yourself, and Build AI Agents in Node.js With Tools and MCP goes further.

JSON that matches a schema​

const { Chatbot, ChatGPTInput } = require('intellinode');

const ticketSchema = {
  type: 'object',
  properties: {
    category: { type: 'string', enum: ['billing', 'bug', 'account', 'other'] },
    urgent: { type: 'boolean' },
    summary: { type: 'string' },
  },
  required: ['category', 'urgent', 'summary'],
};

async function main() {
  const bot = new Chatbot(process.env.OPENAI_API_KEY, 'openai');
  const input = new ChatGPTInput('Classify the support ticket.', { responseSchema: ticketSchema, strictSchema: true });
  input.addUserMessage('I was charged twice for my March invoice and need a refund today.');

  const ticket = await bot.chatJson(input);   // a parsed object, not a string
  console.log(ticket.category, ticket.urgent, ticket.summary);
}
main();

With responseSchema set, chatJson uses each provider's native structured output (OpenAI, Anthropic, Gemini, and response_format on compatible providers) and returns a parsed object. strictSchema: true turns on OpenAI strict mode.

chatJson itself only confirms the reply is an object, or an array if the schema says so. Required fields and types come from the provider's structured output mode, so validate business data with a validator such as ajv before it reaches your database. A schema also guarantees shape, not truth: on the local 0.5B model, the double-charge ticket sometimes came back as account instead of billing. More in the structured output guide.

Streaming, MCP and the browser​

• Streaming: for await (const chunk of bot.stream(input)) works for OpenAI, Anthropic, Mistral, Cohere, NVIDIA, vLLM and every OpenAI-compatible provider, local Ollama included. Gemini, Replicate and SageMaker need chat(), and tool calls are not surfaced through stream().
• MCP: pass an MCPClient straight into runTools and the model uses that server's tools. MCPServer exposes your own functions over stdio or Streamable HTTP, and npx -y intellinode mcp gives Claude Code, Cursor or VS Code 15 cross-provider tools. See MCP in Node.js.
• Browser: a script-tag bundle exposes a global IntelliNode, fine for local models and demos but not for paid keys.

What IntelliNode does not do​

• No UI hooks. For useChat-style state in React, the AI SDK is the better fit.
• No graph workflow engine, memory store or tracing UI. Orchestration is plain JavaScript: fine for three steps, tedious for thirty.
• No tool calls on Cohere. runTools there returns the model's text with zero steps and no error.
• Node-only pieces. CodingAgent and MCPServer are not in the browser bundle.
• A much smaller community. 405 downloads that week against millions for the leaders means fewer forum answers and more reading of the source.

How to choose a Node.js LLM library: a decision checklist​

Go through these in order. The first yes usually decides it.

1. Do you stream chat into a React, Next.js, Vue, Svelte or Angular UI? Start with the Vercel AI SDK.
2. Is one vendor fixed for the next year by contract, committed spend or a compliance review? Use its SDK and keep the calls behind one module.
3. Do you need stateful multi-step workflows, approval pauses and tracing? LangGraph.js or Mastra, or the OpenAI Agents SDK for several cooperating agents on OpenAI models.
4. Must some data stay on your own hardware? Pick a library where local models share the cloud code path, like IntelliNode's ollama and lmstudio presets.
5. Is there a Python side? Look for a Python counterpart with the same concepts, so prompts and tool schemas carry over. IntelliNode's is Intelli, with the same Chatbot idea and JSON Schema tool calling, though there you run the tool loop yourself.
6. Who maintains it? Two backend engineers do better with fewer abstractions. A platform team serving ten product teams can justify a framework.

A scenario most SaaS teams will recognize​

A 40-person B2B SaaS company runs a Node.js API and a two-person Python data team. Support wants AI ticket triage: classify, pull the invoice, draft a reply. Then two constraints land: an enterprise contract says ticket text may not go to an outside model provider, and finance wants cost per ticket tracked before the feature reaches every tenant.

A provider SDK ships the first version fastest, but the enterprise tenant then needs a second code path. LangGraph.js or Mastra would work, though a three-step flow is small for a graph. The AI SDK fits if the agent assist panel lives in their Next.js dashboard. With IntelliNode the team keeps one createBot() function: Claude for most tenants, Ollama for the enterprise one, the same chatJson schema for both, and prompts the data team can reuse in Python with Intelli. Several options would work. What decided it was the on-premises tenant and the size of the team.

Switching later without a rewrite​

Whatever you pick, keep one file that knows the vendor. The rest of the codebase calls answer() and never imports a provider package.

// llm.js: the only file that knows which vendor serves a request
const { Chatbot } = require('intellinode');

const KEYS = { openai: 'OPENAI_API_KEY', anthropic: 'ANTHROPIC_API_KEY', gemini: 'GEMINI_API_KEY' };
const REQUEST = { timeout: 30000, retries: 2 };

function createBot(provider = process.env.LLM_PROVIDER || 'openai') {
  if (provider === 'ollama') {
    return new Chatbot(null, 'ollama', null, { ...REQUEST, model: process.env.OLLAMA_MODEL || 'qwen2.5:0.5b' });
  }
  return new Chatbot(process.env[KEYS[provider]], provider, null, REQUEST);
}

async function answer(system, question) {
  const bot = createBot();
  const input = Chatbot.createInput(bot.provider, system, { maxTokens: 4096 });
  input.addUserMessage(question);
  const [reply] = await bot.chat(input);
  return reply;
}

module.exports = { createBot, answer };

Moving the app to Gemini, or one tenant to a local model, is now an environment variable. timeout applies per attempt, retries back off on 429, most 5xx responses and network errors, and the thrown error carries status (or code on a timeout), so fallback logic can tell a rate limit from a bad key.

OpenAI-compatible endpoints widen the choice without new code. new Chatbot(process.env.OPENROUTER_API_KEY, 'openrouter') reaches the models OpenRouter hosts, and the groq, deepseek, xai, together, ollama and lmstudio presets work the same way (all except deepseek need a model in the options). Details in OpenAI-compatible providers.

Before you move traffic to a cheaper model, measure it on your own prompts:

const { LLMEvaluation } = require('intellinode');

async function main() {
  // the embedding provider that scores the answers: openai, cohere, gemini, replicate or openrouter
  const evaluation = new LLMEvaluation(process.env.OPENAI_API_KEY, 'openai');

  const results = await evaluation.compareModels(
    'A customer was charged twice. What should support do first?',
    ['Confirm the duplicate charge with the payment provider, refund it, and tell the customer when the money will arrive.'],
    [
      { apiKey: process.env.ANTHROPIC_API_KEY, provider: 'anthropic', type: 'chat', model: 'claude-sonnet-5', maxTokens: 2048 },
      { apiKey: process.env.OPENAI_API_KEY, provider: 'openai', type: 'chat', model: 'gpt-5.5' },
      { apiKey: null, provider: 'ollama', type: 'chat', model: 'qwen2.5:0.5b', maxTokens: 300 },
    ],
  );

  for (const [lane, runs] of Object.entries(results)) {
    if (lane !== 'lookup') console.log(lane, runs[0].stop_reason, runs[0].score_cosine_similarity);
  }
}
main();

compareModels sends the same prompt to each lane, embeds every answer, and scores it against your reference answers (cosine similarity, Euclidean and Manhattan distance). A failing lane is recorded with stop_reason: 'error' instead of stopping the run. Treat the score as a measure of semantic closeness rather than correctness, and run it over 50 real tickets before you trust it. See LLM evaluation.

FAQ​

What is the best Node.js LLM library in 2026?​

There is no single winner. The Vercel AI SDK leads for web apps with streaming UI, LangGraph.js and Mastra for stateful agent workflows, provider SDKs for single-vendor apps, and IntelliNode for a small multi-provider backend with local models. The checklist above usually settles it.

Is IntelliNode a LangChain.js alternative?​

For many backend features, yes: chat across providers, a tool loop, schema-based JSON, streaming and MCP, with fewer layers. It does not replace LangChain's integration catalog, LangGraph's stateful graphs or LangSmith tracing, so teams that depend on those should stay.

Does IntelliNode support TypeScript?​

Yes. The package ships index.d.ts covering Chatbot, every input class, runTools, chatJson and the MCP classes, so no @types package is needed. The build is CommonJS and ESM named imports work too. It is not TypeScript-first the way Mastra is.

Can a JavaScript LLM library run in the browser?​

Several can. LangChain.js lists browsers among its environments, and IntelliNode ships a script tag bundle with Chatbot, runTools, chatJson, stream and MCPClient over HTTP. The hard part is the key: anything in the page is public, so paid keys belong on a server.

Does IntelliNode work with OpenRouter, Groq and Ollama?​

Yes. They are built-in presets of the OpenAI-compatible provider. openrouter defaults to openai/gpt-5.5, while groq and ollama need a model name. Local presets need no key, and listModels() returns the models the server offers.

Try it on your own prompts​

Start with the local model, since it needs no key and no budget approval:

npm i intellinode
ollama pull qwen2.5:0.5b

Run the local line from the first example, then point createBot() at your hosted provider and try a real prompt from your backlog. The installation guide covers Node.js versions, TypeScript imports and the browser bundle.

This guide builds one support agent end to end with the intellinode npm package. It answers order questions with a plain JavaScript tool, gets the same tool from an MCP server, waits for a person before it issues a refund, and falls back to another provider when one is down. You develop on a local Ollama model with no API key, then move to OpenAI, Claude or Gemini by changing one line.

Every snippet was run on Node.js 20 against Ollama with qwen2.5:0.5b. Where the tiny model got things wrong, we say so: those failures are worth seeing before you ship.

What you need to build AI agents in Node.js​

Picture an online store with a small support team. Much of the inbox is some version of "where is my order", and every answer means opening the order system and copying a status into a reply. That is a good first agent: the data lives in your system, the question is narrow, and a wrong answer is easy to catch. Refunds are different. They move money, so a person approves them.

You will build it in small files: tools, a loop, a provider switch, an MCP server and client, a refund approval step and a production wrapper. This follows Anthropic's advice in Building effective agents: start with direct LLM calls and add layers only when the simple version falls short.

Install IntelliNode and pick a model​

You need Node.js 18 or newer. The package has three runtime dependencies and its own TypeScript types (see the installation page).

npm i intellinode

# local models for development, no key needed
ollama pull qwen2.5:0.5b   # about 400 MB, fine for wiring things up
ollama pull qwen3:8b       # 5.2 GB, a better fit for real tool use

The 0.5B model runs on any laptop, which is why we tested with it. It is also poor at deciding when to call a tool, so you meet the failure modes early. For anything a customer reads, use a larger local model such as qwen3, which Ollama lists with tool support, or a cloud model.

Cloud keys go in environment variables on your server: OPENAI_API_KEY, ANTHROPIC_API_KEY and GEMINI_API_KEY. Never put them in a browser bundle, where anyone can read them.

Define the tools the model can call​

A tool is a name, a description, a JSON Schema for its arguments and a handler. The model never sees the handler. The name, description and schema alone decide whether it calls the tool and with what arguments.

// order-tools.js: plain functions the agent can call
const ORDERS = {
  'A-1001': { status: 'shipped', carrier: 'DHL', eta: '2026-10-02' },
  'A-1002': { status: 'processing', carrier: null, eta: '2026-10-06' },
};

const tools = [
  {
    name: 'get_order_status',
    description:
      'Look up the shipping status, carrier and expected delivery date of a customer order. ' +
      'Call it whenever the customer gives an order id such as A-1001.',
    parameters: {
      type: 'object',
      properties: {
        orderId: { type: 'string', description: 'The order id, for example A-1001' },
      },
      required: ['orderId'],
    },
    handler: async ({ orderId }) => {
      const order = ORDERS[orderId];
      if (!order) throw new Error(`No order found with id ${orderId}`);
      return { orderId, ...order };
    },
  },
];

module.exports = { tools };

The description says when to call the tool, not only what it does, and the orderId property shows the id format. The handler throws on an unknown id instead of returning null, because a thrown error reaches the model as text, so it can tell the customer instead of guessing.

Wording matters more than you would expect. With qwen2.5:0.5b, "What is the status of order A-1001?" triggered the tool in 16 of 19 runs. "Where is my order A-1001?" triggered it in 1 of 15 runs across the prompts we tried, and most other runs asked the customer for the id they had just typed. Test the phrasings your customers actually use on the model you plan to ship.

Run the LLM tool calling loop with runTools​

By hand, the loop is: send the messages and tool definitions, run the tools the reply asks for, append calls and results in the provider's format, and repeat until the model answers with text. Every provider formats tool calls differently, and the loop needs a step cap. runTools handles both.

// agent.js
const { Chatbot, OpenAICompatibleInput } = require('intellinode');
const { tools } = require('./order-tools');

const SYSTEM =
  'You are a support agent for an online store. ' +
  'Always call get_order_status before you answer a question about an order. Keep answers short.';

async function main() {
  const bot = new Chatbot(null, 'ollama', null, { model: process.env.OLLAMA_MODEL || 'qwen2.5:0.5b' });

  const input = new OpenAICompatibleInput(SYSTEM);
  input.addUserMessage('What is the status of order A-1001?');

  const { text, steps, toolCalls } = await bot.runTools(input, tools, {
    maxSteps: 4,
    onToolCall: (name, args) => console.log('calling', name, args),
    onToolResult: (name, result, isError) => console.log('result', name, isError ? 'error' : 'ok'),
  });

  console.log(text);
  console.log(toolCalls, steps.map((step) => step.name));
}

main();

// calling get_order_status { orderId: 'A-1001' }
// result get_order_status ok
// The order A-1001 has been shipped. The carrier is DHL and the expected delivery date is 2026-10-02.
// 1 [ 'get_order_status' ]

What to know about the result:

• text is the answer, steps lists each executed tool with its arguments, result and isError, and toolCalls is the count.
• maxSteps counts tool rounds (default 5), and the model gets one more call after the last round. So maxSteps: 4 means at most five model calls per question, which is your cost ceiling per request. If the model still wants tools, runTools throws "runTools stopped after 4 tool rounds without a final answer".
• A throwing handler does not crash the loop. Asked about order A-9999, the step came back as Error: No order found with id A-9999 with isError: true, and the model told the customer it could not find it.
• onToolCall and onToolResult are where logging and audit records go.

One caveat: runTools appends the tool calls and results to the input you pass in. Create a fresh input per customer request, or one customer's order data leaks into the next conversation.

TypeScript​

Top-level await needs an ES module, so use an .mts file or set "type": "module" in package.json.

// agent.mts
import { Chatbot, OpenAICompatibleInput, type RunToolsResult } from 'intellinode';

const bot = new Chatbot(null, 'ollama', null, { model: process.env.OLLAMA_MODEL || 'qwen2.5:0.5b' });
const input = new OpenAICompatibleInput(
  'You are a support agent for an online store. Always call get_order_status before you answer a question about an order.',
);
input.addUserMessage('What is the status of order A-1001?');

const result: RunToolsResult = await bot.runTools(input, [{
  name: 'get_order_status',
  description: 'Look up the shipping status of an order by id',
  parameters: { type: 'object', properties: { orderId: { type: 'string' } }, required: ['orderId'] },
  handler: async ({ orderId }: { orderId: string }) => ({ orderId, status: 'shipped', eta: '2026-10-02' }),
}], { maxSteps: 4 });

console.log(result.text, result.toolCalls);

Switch from Ollama to OpenAI, Claude or Gemini​

The agent above is tied to Ollama by one line and one input class. Put both behind a small factory and the provider becomes a config value:

// switch.js
const { Chatbot } = require('intellinode');
const { tools } = require('./order-tools');

const SYSTEM =
  'You are a support agent for an online store. ' +
  'Always call get_order_status before you answer a question about an order. Keep answers short.';

const bots = {
  ollama: () => new Chatbot(null, 'ollama', null, { model: process.env.OLLAMA_MODEL || 'qwen2.5:0.5b' }),
  openai: () => new Chatbot(process.env.OPENAI_API_KEY, 'openai'),
  anthropic: () => new Chatbot(process.env.ANTHROPIC_API_KEY, 'anthropic'),
  gemini: () => new Chatbot(process.env.GEMINI_API_KEY, 'gemini'),
};

async function answer(question) {
  const bot = bots[process.env.LLM_PROVIDER || 'ollama']();
  const input = Chatbot.createInput(bot.provider, SYSTEM);   // ChatGPTInput, AnthropicInput, GeminiInput...
  input.addUserMessage(question);
  const { text } = await bot.runTools(input, tools, { maxSteps: 4 });
  return text;
}

answer('What is the status of order A-1002?').then(console.log);

Chatbot.createInput picks the matching input class. The same tool definition is converted for each API, and so are the calls and results: function call items for the OpenAI Responses API, tool_use blocks for Claude and functionCall parts for Gemini. LLM_PROVIDER=anthropic node switch.js is the whole migration.

The current defaults are gpt-5.5, claude-sonnet-5 and gemini-3.6-flash. Pin a model in production with model in the third argument of createInput, so a library upgrade never changes your bill. On Claude, maxTokens defaults to 2048 and thinking counts toward it, so raise it if answers get cut.

The business reason is lock-in. Most Node.js tutorials on OpenAI function calling are written against one vendor's SDK, so moving means rewriting the loop. Here the loop, tools and tests stay put, and you can price one workload on three vendors in an afternoon. The same code reaches Groq, OpenRouter or LM Studio through the OpenAI-compatible providers. One exception: Cohere's input never sends tools, so runTools on Cohere returns plain text with zero steps and no error.

Use MCP servers as agent tools in Node.js​

Plain functions work while the agent and tools share a repo. Once another team owns the order service, or Claude Code and Cursor should use the same tools, put them behind an MCP server. MCPServer takes almost the same shape, with inputSchema in place of parameters:

// order-server.js: the same tools, served over MCP
const { MCPServer } = require('intellinode');
const { tools } = require('./order-tools');

const server = new MCPServer({
  name: 'order-tools',
  version: '1.0.0',
  instructions: 'Tools for looking up customer orders.',
  tools: tools.map(({ name, description, parameters, handler }) => ({
    name,
    description,
    inputSchema: parameters,
    handler,
  })),
});

server.startStdio();   // stdout carries the protocol, so log to stderr

The agent passes an MCPClient where the tools array used to be:

// mcp-agent.js
const path = require('path');
const { Chatbot, OpenAICompatibleInput, MCPClient } = require('intellinode');

const SYSTEM =
  'You are a support agent for an online store. ' +
  'Always call get_order_status before you answer a question about an order. Keep answers short.';

async function main() {
  const orders = new MCPClient({ command: 'node', args: [path.join(__dirname, 'order-server.js')] });

  try {
    const bot = new Chatbot(null, 'ollama', null, { model: process.env.OLLAMA_MODEL || 'qwen2.5:0.5b' });
    const input = new OpenAICompatibleInput(SYSTEM);
    input.addUserMessage('What is the status of order A-1001?');

    // runTools lists the server's tools on first use, no connect() needed
    const { text, steps } = await bot.runTools(input, orders, { maxSteps: 4 });
    console.log(text);
    console.log(steps.map((step) => step.name));
  } finally {
    await orders.close();   // stops the server subprocess
  }
}

main();

Before you rely on it:

• The client runs order-server.js as a stdio subprocess. For a remote server, use new MCPClient({ url, headers }) over Streamable HTTP. It handles both the 2026-07-28 protocol and the older initialize handshake.
• Always call close(). A test script that skipped it was still running six seconds after its last line, held open by the subprocess.
• Community servers plug in the same way: command: 'npx', args: ['-y', '@modelcontextprotocol/server-filesystem', './kb'] gives the agent file tools limited to one folder.
• runTools takes one tool source per call, so an agent that needs both kinds should get all its tools from one MCP server.
• MCPServer serves tools only, checks only top-level required, type and enum, and has no authentication. Over HTTP it binds to 127.0.0.1 by default; add your own auth before you expose it.

Over MCP the small model used the tool in 12 of 18 runs, and in one miss it invented a "pending confirmation" status that exists nowhere in the data, a case the production section handles.

The official Build an MCP client tutorial writes this loop by hand against the Anthropic SDK, a good way to learn the protocol. The MCP client and MCP server pages list every option, plus npx -y intellinode mcp, a ready server of cross-provider tools for Claude Code and Cursor.

Keep a human in the loop for risky actions​

runTools runs every tool it is given as soon as the model asks. That is right for reads and wrong for refunds. For actions that move money, keep the tool out of the loop: put the definition on the input, read tool_calls from chat(), and continue only after someone approves.

// refund.js: the model proposes, a person approves
const readline = require('readline/promises');
const { Chatbot, OpenAICompatibleInput } = require('intellinode');

const issueRefund = {
  type: 'function',
  function: {
    name: 'issue_refund',
    description: 'Refund a customer order. Use it only when the customer asks for a refund.',
    parameters: {
      type: 'object',
      properties: {
        orderId: { type: 'string' },
        amount: { type: 'number', description: 'Amount in USD' },
      },
      required: ['orderId', 'amount'],
    },
  },
};

async function main() {
  const bot = new Chatbot(null, 'ollama', null, { model: process.env.OLLAMA_MODEL || 'qwen2.5:0.5b' });
  const input = new OpenAICompatibleInput(
    'You are a support agent for an online store. Always call issue_refund when a customer asks for a refund.',
    {
      tools: [issueRefund],
      toolChoice: 'auto',   // 'auto' | 'none' | 'required'
    },
  );
  input.addUserMessage('Order A-1002 arrived broken. Please refund the 49.90 USD I paid.');

  const [reply] = await bot.chat(input);
  if (!reply || !reply.tool_calls) return console.log(reply);

  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
  const results = [];
  for (const call of reply.tool_calls) {
    const args = JSON.parse(call.function.arguments);   // arguments arrive as a JSON string
    const ok = call.function.name === 'issue_refund'   // small models sometimes invent tool names
      ? await rl.question(`Approve ${call.function.name} ${JSON.stringify(args)}? (y/n) `)
      : 'n';
    const content = ok.trim() === 'y'
      ? { refunded: true, orderId: args.orderId, amount: args.amount }   // call your payments API here
      : { refunded: false, reason: 'A support lead declined the refund.' };
    results.push({ id: call.id, name: call.function.name, content });
  }
  rl.close();

  input.addToolCalls(reply.tool_calls, reply.content);
  input.addToolResults(results);
  const [answer] = await bot.chat(input);
  console.log(answer);
}

main();

In about half our runs the model proposed issue_refund, most often as {"amount":49.9,"orderId":"A-1002"}; in the rest it skipped the tool, usually asking for the order number again. addToolCalls records that request, addToolResults records the outcome, and the second chat() writes the reply. A declined refund is a normal result: with "n", the model apologized and pointed the customer to the support team.

The small model also invented things. After an approval it added that the refund was "sent to your billing address", which no tool returned. Some proposals asked for 51 or -49.9 USD instead of 49.90, and once it called a made-up getOrderId tool. That is why the approver sees the exact arguments and only issue_refund reaches the prompt. That argues for a larger model, and for letting the approver see the final message while you build trust. In a real service the approval is a queue in your admin tool, not a terminal prompt. Store the pending call id, name and arguments with the ticket, and rebuild the input with addToolCalls when the decision arrives.

Production checklist for a Node.js AI agent​

Here is the agent from switch.js with request limits and fallback lanes added:

// support-agent.js
const { Chatbot } = require('intellinode');
const { tools } = require('./order-tools');

const SYSTEM =
  'You are a support agent for an online store. ' +
  'Always call get_order_status before you answer a question about an order. Keep answers short.';

const REQUEST = { timeout: 30000, retries: 2, retryDelay: 500 };

const lanes = {
  primary: (signal) => new Chatbot(process.env.OPENAI_API_KEY, 'openai', null, { ...REQUEST, signal }),
  backup: (signal) => new Chatbot(process.env.ANTHROPIC_API_KEY, 'anthropic', null, { ...REQUEST, signal }),
  local: (signal) => new Chatbot(null, 'ollama', null, {
    ...REQUEST, timeout: 120000, signal, model: process.env.OLLAMA_MODEL || 'qwen2.5:0.5b',
  }),
};

// provider-side problems: move to the next lane
const isProviderProblem = (error) =>
  ['ETIMEDOUT', 'ECONNREFUSED', 'ENOTFOUND'].includes(error.code) ||
  error.status === 429 || error.status >= 500;

async function answer(question, { signal, order = ['primary', 'backup', 'local'] } = {}) {
  let lastError;
  for (const lane of order) {
    const bot = lanes[lane](signal);
    const input = Chatbot.createInput(bot.provider, SYSTEM);   // a fresh input for every attempt
    input.addUserMessage(question);
    try {
      const result = await bot.runTools(input, tools, { maxSteps: 4 });
      return { lane, ...result };
    } catch (error) {
      // AbortError, a 401 bad key or the maxSteps error should surface, not fall through
      if (!isProviderProblem(error)) throw error;
      console.warn(`lane ${lane} failed: ${error.code || error.status}`);
      lastError = error;
    }
  }
  throw lastError;
}

module.exports = { answer };

And a small endpoint, so the keys stay on the server:

// server.js: the agent behind your own endpoint, keys stay on the server
const http = require('http');
const { answer } = require('./support-agent');

http.createServer(async (req, res) => {
  const controller = new AbortController();
  res.on('close', () => { if (!res.writableEnded) controller.abort(); });   // the customer left

  try {
    const chunks = [];
    for await (const chunk of req) chunks.push(chunk);
    const { question = '' } = JSON.parse(Buffer.concat(chunks).toString() || '{}');   // in the try, so bad JSON cannot crash the server
    const { lane, text, toolCalls } = await answer(question, { signal: controller.signal });
    const needsOrderData = /\b[A-Z]-\d{4}\b/.test(question);
    const escalate = needsOrderData && toolCalls === 0;   // answered without looking anything up
    res.end(JSON.stringify({ lane, escalate, text: escalate ? null : text }));
  } catch (error) {
    if (error.name !== 'AbortError') console.error(error);
    if (!res.writableEnded) res.writeHead(502).end(JSON.stringify({ escalate: true }));
  }
}).listen(3000);

With the first two lanes pointed at dead endpoints, the log showed lane primary failed: ECONNREFUSED, then lane backup failed: ENOTFOUND, and the local lane answered. The checklist behind these files:

• Cap the steps. The maxSteps error has no status or code, so the fallback rethrows it. Treat it as a bug in your prompt or tools.
• Do the timeout math. timeout applies per attempt and per model call, and retries cover 429, the common 5xx codes and network errors. Five calls times three attempts times 30 seconds is over seven minutes in the worst case, far too long for live chat, so tune the request options per channel.
• Cancel abandoned work. The res.on('close') line aborts the call through an AbortController when the customer leaves, so you stop paying for answers nobody reads.
• Catch unreachable hosts. Network failures have no HTTP status, so a check on status alone never falls back when a host is down. Hence ECONNREFUSED and ENOTFOUND. A 401 is your bug, so it surfaces.
• Use a fresh input per attempt. A half-finished tool conversation from OpenAI is not valid input for Claude.
• Distrust answers that skipped the tools. The toolCalls === 0 check sends those to a person.
• Check authorization in the handler. A customer can type anyone's order id. Look the order up with the customer id from your session. A system prompt is not access control.
• Keep the automatic loop read-only. Fallback reruns the loop on the next lane, so a tool can run twice.

The model routing page extends the lanes idea to quality, cost and private data.

When a bigger agent framework fits better​

For agents, IntelliNode is deliberately small: a Chatbot class with one tool loop, an MCP client and server, and a ready coding agent. It has no memory store, tracing UI, React hooks or durable execution, and when you need those, other tools fit better. From their official docs, checked on September 30, 2026:

• OpenAI Agents SDK (@openai/agents): handoffs, guardrails, sessions, tracing and MCP tools, with other models through an AI SDK extension. Good for multi-agent handoffs with tracing built in.
• Vercel AI SDK: a ToolLoopAgent with stopWhen loop control, an MCP client (createMCPClient in @ai-sdk/mcp) and UI hooks such as useChat for React, Vue, Svelte and Angular. Pick it when the agent streams into a web UI.
• Mastra: a TypeScript framework with agents, workflows that can suspend and resume, memory backed by a storage provider, and an interactive Studio UI. Pick it when you want those pieces included.
• LangGraph.js: low-level orchestration for long-running, stateful agents, with durable execution, checkpointing and human-in-the-loop support. Pick it when an agent must resume after a crash or a day-long wait.

Choose IntelliNode for a backend agent that swaps providers by config, runs locally on Ollama, and stays small enough for a new teammate to read in an hour. For a wider comparison, see How to Choose a Node.js LLM Library in 2026.

FAQ​

What is the best model for an AI agent in Node.js?​

Use the model that picks the right tool for your own questions, not the best benchmark score. Run 20 or so real customer questions through a cloud model such as gpt-5.5 or claude-sonnet-5 and a local model of about 8B parameters. A 0.5B model is fine for wiring code, but even with our best prompt it skipped the tool in 3 of 19 direct runs and 6 of 18 over MCP.

Can a Node.js AI agent run fully offline with Ollama?​

Yes. new Chatbot(null, 'ollama', null, { model }) needs no key, and the same runTools and MCPClient code runs with no internet connection. The limit is model quality on your hardware, not the code.

How many tool steps should an AI agent be allowed?​

Allow the tool rounds a correct answer needs, plus a little room. A lookup agent like this needs one or two, so maxSteps: 4 leaves slack without letting a confused model loop. If you hit the maxSteps error often, fix the tool descriptions before raising the limit.

Can I build the agent in TypeScript?​

Yes. The package ships index.d.ts, so Chatbot, the input classes and RunToolsResult are typed with no @types package. The code is CommonJS, and ESM named imports work, as agent.mts shows. Import RunToolsResult with the type modifier: it exists only as a type, so a plain import fails under verbatimModuleSyntax and under Node's type stripping.

Can Claude Code or Cursor use the same tools?​

Yes. order-server.js is a standard stdio MCP server, so you can register it with claude mcp add order-tools -- node /path/to/order-server.js or add it to .cursor/mcp.json. Your agent and your coding assistant then share one implementation of the tools.

Next step​

Install the package, pull a local model, and run agent.js from this guide:

npm i intellinode
ollama pull qwen2.5:0.5b
node agent.js

Then read the tool calling guide for the other tool formats and the manual tool call API. For a cloud model, run switch.js with LLM_PROVIDER and your key set.

This guide builds each common AI agent orchestration pattern with Intelli, an Apache 2.0 Python library for multi-model agent flows. The examples mix OpenAI, Claude and Gemini in one flow and can run on a local Ollama model. It closes by comparing Intelli with LangGraph, CrewAI and plain code, including where each of them wins.

Workflow or agent: how much autonomy you need​

Anthropic's engineering team draws a useful line in Building effective agents. In a workflow, models and tools follow predefined code paths. In an agent, the model directs its own process and chooses its tools. The post recommends adding autonomy only when simpler setups fall short.

For most business processes the workflow wins on cost and audits. Take a SaaS support team handling 12,000 tickets a month. A workflow that triages, extracts facts and risks in parallel, and drafts a reply makes four model calls per ticket, every time. That is 48,000 calls a month, a number finance can budget and QA can test. An autonomous agent might use 3 calls on one ticket and 25 on the next.

Fix the known steps in code and give the model freedom only inside a step. If you have not built a single tool calling agent yet, start with How to Build an AI Agent in Python and come back when one step is not enough.

The building blocks of an agentic workflow in Python​

For AI agent orchestration in Python, Intelli gives you four pieces:

• Agent: one model or tool, with a mission (the system prompt), a provider and model settings.
• Task: one unit of work for an agent, with optional pre_process and post_process hooks.
• SequenceFlow: runs tasks in a straight line.
• Flow: runs a graph of tasks. map_paths says which task feeds which, independent tasks run in parallel, and connectors add routing.

Each agent picks its own provider, so a cheap fast model can classify while a stronger one writes. Install with pip install intelli, then put the provider setup in one file so the pattern examples stay short:

# providers.py
import os
from intelli.flow import Agent

def gpt(mission, **params):
    return Agent("text", "openai", mission,
                 {"key": os.environ["OPENAI_API_KEY"], "model": "gpt-5.5", **params})

def claude(mission, **params):
    return Agent("text", "anthropic", mission,
                 {"key": os.environ["ANTHROPIC_API_KEY"], "model": "claude-sonnet-5", **params})

def gemini(mission, **params):
    return Agent("text", "gemini", mission,
                 {"key": os.environ["GEMINI_API_KEY"], "model": "gemini-2.5-flash", **params})

def local(mission, **params):
    # Ollama or vLLM on your own machine: no API key, no per-token bill
    return Agent("text", "vllm", mission, {"model": "qwen2.5:0.5b", **params},
                 options={"baseUrl": "http://localhost:11434"})

This file is also your insurance against vendor lock-in: moving a step from Claude to Gemini is a one-word change.

Pattern 1: the sequential chain​

Anthropic's post calls this prompt chaining: each step works on the previous step's output. Here GPT writes release notes from commit messages, and Claude turns them into a two-sentence banner for the app.

from intelli.flow import Task, SequenceFlow, TextTaskInput, TextProcessor
from providers import gpt, claude

commits = """feat: export invoices as CSV
fix: weekly report used the wrong timezone
perf: dashboard loads 40% faster"""

notes = Task(TextTaskInput("Write release notes for these commits, one short paragraph each."),
             gpt("You write clear release notes for B2B customers."))
banner = Task(TextTaskInput("Summarize the release notes in two sentences for an in-app banner."),
              claude("You write short product announcements."),
              pre_process=TextProcessor.text_head)  # hand off the first 800 characters only

result = SequenceFlow([notes, banner], log=True).start(initial_input=commits)
print(result["task2"])

Two details matter. TextProcessor.text_head trims the handoff to 800 characters, which caps what the second call costs. And SequenceFlow returns positional keys (task1, task2) with raw outputs as values, so update the code that reads them if you reorder tasks.

Pattern 2: parallel fan-out and merge​

When two steps do not depend on each other, run them at the same time. This support flow extracts facts with Gemini and churn risks with GPT in parallel, then Claude writes the reply from both.

import asyncio
from intelli.flow import Task, Flow, TextTaskInput
from providers import gpt, claude, gemini

ticket = ("Order #1001 arrived with a cracked screen. This is our second damaged "
          "delivery this quarter, and our 40 seats are up for renewal in May.")

tasks = {
    "facts": Task(TextTaskInput("List the facts in this ticket as short bullets."),
                  gemini("You extract facts from support tickets.")),
    "risks": Task(TextTaskInput("List the churn risks in this ticket."),
                  gpt("You are a customer success analyst.")),
    "reply": Task(TextTaskInput("Write a short, calm reply to the customer."),
                  claude("You synthesize analyst notes into customer replies.")),
}
flow = Flow(tasks=tasks,
            map_paths={"facts": ["reply"], "risks": ["reply"]},
            output_memory_map={"reply": "final_reply"})

result = asyncio.run(flow.start(max_workers=4, initial_input=ticket))
print(result["reply"]["output"])
print(flow.errors)                        # {} when every step worked
saved = flow.memory.retrieve("final_reply")

initial_input goes to every root task, so both analysts see the ticket. The reply step waits for both parents and receives their outputs joined. Because its mission contains "synthesize", Intelli wraps each parent's output in a labeled block, so the writer can tell facts from risks. output_memory_map copies the reply into flow.memory.

max_workers caps how many tasks run at once, and Intelli also limits each provider to 10 concurrent tasks, which helps with rate limits. A Flow returns output and type for each task name. The async flow docs walk through a larger graph.

Pattern 3: routing with a classifier​

A cheap Gemini call classifies inbound email, and a DynamicConnector sends it to the billing, bug or sales desk. Only the chosen branch runs, so you pay for one specialist instead of three.

import asyncio
from intelli.flow import Task, Flow, TextTaskInput, DynamicConnector, ConnectorMode
from intelli.flow.utils.dynamic_utils import text_content_router
from providers import gpt, claude, gemini

email = "I was charged twice for the March invoice."

triage = Task(TextTaskInput("Classify this email as billing, bug or sales. Reply with one word."),
              gemini("You triage inbound customer email."))
desks = {   # memory_key: each desk reads the email itself, not the one word label
    "billing": Task(TextTaskInput("Draft a reply about the charge."), gpt("You work on the billing desk."),
                    memory_key="email"),
    "bug": Task(TextTaskInput("Write a bug report for engineering."), claude("You are a QA lead."),
                memory_key="email"),
    "sales": Task(TextTaskInput("Draft a sales follow up."), gpt("You are an account executive."),
                  memory_key="email"),
}

def route(output, output_type):
    if str(output).startswith("Error"):
        return None   # unknown key: stop here, flow.errors has the details
    return text_content_router(output, output_type, {
        "billing": ["billing", "invoice", "charge"],   # first key is the fallback
        "bug": ["bug", "error", "crash"],
        "sales": ["sales", "pricing", "demo"],
    })

flow = Flow(
    tasks={"triage": triage, **desks},
    map_paths={},
    dynamic_connectors={"triage": DynamicConnector(
        route, {"billing": "billing", "bug": "bug", "sales": "sales"},
        name="email_triage", mode=ConnectorMode.CONTENT_BASED)},
)
flow.memory.store("email", email)
result = asyncio.run(flow.start(initial_input=email))
print(sorted(result))   # ['billing', 'triage']: only the chosen desk ran

A few rules that matter in production:

• A destination receives its parent's output, here the one-word label. The desks read the full email from flow.memory through memory_key.
• A connector supports at most 4 destinations. For more, route in two levels.
• text_content_router falls back to the first key when nothing matches, so list your safest desk first.
• An unknown key stops the branch. The Error check uses that on purpose: without it, a failed classifier returns text containing "error" and lands on the bug desk. We hit exactly this in testing.
• A shared step fed by all three desks never runs, because a Flow task waits for all of its parents. Give each branch its own follow-up step.

Length, sentiment, error and type routers are in the dynamic path docs.

Pattern 4: loops for self-review​

Some outputs need a few passes, such as a subject line that must fit in 60 characters. LoopTask repeats its steps until a stop condition passes or max_loops is reached.

import asyncio
from intelli.flow import Task, Flow, TextTaskInput, LoopTask
from providers import gpt

rewrite = Task(TextTaskInput("Rewrite this email subject line to be shorter and clearer."),
               gpt("You write email subject lines. Reply with the subject line only."))

loop = LoopTask("shorten subject", [rewrite], max_loops=4,
                stop_condition=lambda i, out, out_type, mem: len(str(out)) <= 60,
                store_history_memory_key="subject_history")

flow = Flow(tasks={"subject": loop}, map_paths={})
result = asyncio.run(flow.start(initial_input=(
    "Important information regarding upcoming changes to your monthly subscription billing cycle")))

print(result["subject"]["output"])
for step in flow.memory.retrieve("subject_history"):
    print(step["iteration"], step["output"])

The stop check is plain Python, which is free and deterministic. You can add a reviewer model to steps, but LoopTask returns the last step's output, so you would get the review instead of the draft. max_loops=4 doubles as a cost ceiling.

Flow requires an acyclic graph and raises ValueError on a cycle, so repetition lives inside one node and the graph stays easy to review. The loop docs cover the stop condition and history.

Pattern 5: tool calls routed to MCP servers​

Here the model decides whether it needs data, and the flow runs the tool. First, a small MCP server with one tool (install the extra with pip install "intelli[mcp]"):

# order_server.py
from intelli.mcp import MCPServerBuilder

server = MCPServerBuilder("OrderTools")

@server.add_tool
def lookup_order(order_id: str) -> str:
    """Return the shipping status of an order"""
    orders = {"A-1001": "shipped on 28 Sep, arrives Friday", "A-1002": "waiting for stock"}
    return f"Order {order_id}: {orders.get(order_id, 'not found')}"

if __name__ == "__main__":
    server.run(transport="stdio", print_info=False)  # stdout carries the MCP protocol

If GPT calls lookup_order, a ToolDynamicConnector routes to an MCP task that runs the tool. If it answers in text, the flow sends that answer to a direct step.

import asyncio, json, sys
from intelli.flow import Agent, Task, Flow, TextTaskInput, ToolDynamicConnector
from providers import gpt

TOOLS = [{"type": "function", "function": {
    "name": "lookup_order",
    "description": "Get the shipping status of an order by id, for example A-1001",
    "parameters": {"type": "object",
                   "properties": {"order_id": {"type": "string"}},
                   "required": ["order_id"]}}}]

def tool_call_to_mcp(tool_output):
    call = tool_output["tool_calls"][0]["function"]
    args = json.loads(call["arguments"])
    return {"update_model_params": {"tool": call["name"],
                                    **{f"arg_{k}": v for k, v in args.items()}}}

router = Task(TextTaskInput("Answer the customer. Call a tool when you need order data."),
              gpt("You are a support assistant for an online store.", model="gpt-4.1", tools=TOOLS))
lookup = Task(TextTaskInput("Run the order lookup"),
              Agent("mcp", "mcp", "Order tools",
                    {"command": sys.executable, "args": ["order_server.py"]}),
              pre_process=tool_call_to_mcp, model_params={})
direct = Task(TextTaskInput("Rewrite this answer for the customer in two sentences."),
              gpt("You answer store policy questions."))

flow = Flow(
    tasks={"router": router, "lookup": lookup, "direct": direct},
    map_paths={},
    dynamic_connectors={"router": ToolDynamicConnector(
        destinations={"tool_called": "lookup", "no_tool": "direct"})},
)
result = asyncio.run(flow.start(initial_input="Where is my order A-1001?"))
print(result.get("lookup", result.get("direct"))["output"])

Details that are easy to miss:

• Intelli does not map the tool call to MCP arguments for you. The tool_call_to_mcp pre-process turns it into tool and arg_* params.
• Each destination receives the router's output: lookup gets the tool call and direct gets the model's text answer, not the customer's question.
• Pass model_params={} on the MCP task. Task has a shared mutable default, and updated params would otherwise leak into other tasks.
• The router must be an OpenAI or Anthropic agent, because Gemini and Mistral tool calls are not parsed into the shape the connector checks. Intelli passes the tools list through unchanged. This one uses the chat completions format, hence gpt-4.1. GPT-5 models go through the Responses API, which expects the flat tool format, and Anthropic expects input_schema.
• Tool choice depends on the model. In our tests a 0.5B local model called lookup_order for a return policy question and sometimes skipped it for a real order id.

See the dynamic tool docs for the connector and the MCP server docs for streamable HTTP servers.

Pattern 6: your own code and approval steps​

Not every step should be a model. A CustomAgent wraps your own Python, such as a CRM lookup, and sits in the graph like any other agent. The same shape works as a human approval gate before an action.

import asyncio
from intelli.flow import CustomAgent, Task, Flow, TextTaskInput, DynamicConnector
from providers import claude

class CRMLookup(CustomAgent):
    def execute(self, agent_input, new_params=None):
        account = agent_input.desc.strip()
        # call your CRM API or database here
        return f"Account {account}: Business plan, 40 seats, renews 1 May, 2 open tickets"

class ApprovalGate(CustomAgent):
    def execute(self, agent_input, new_params=None):
        draft = agent_input.desc.split("\n\n", 1)[-1]   # drop the task header Intelli adds
        print("\n--- draft for review ---\n" + draft)
        approved = input("Approve and send? [y/N] ").strip().lower() == "y"
        return "APPROVED\n" + draft if approved else "REJECTED"

class SendEmail(CustomAgent):
    def execute(self, agent_input, new_params=None):
        # call your email provider here
        return "sent"

flow = Flow(
    tasks={
        "crm": Task(TextTaskInput("acme corp"), CRMLookup("text")),
        "draft": Task(TextTaskInput("Write a short renewal check-in email using the CRM note."),
                      claude("You write emails for account managers.")),
        "approve": Task(TextTaskInput("Human review"), ApprovalGate("text")),
        "send": Task(TextTaskInput("Send the approved email"), SendEmail("text")),
    },
    map_paths={"crm": ["draft"], "draft": ["approve"]},
    dynamic_connectors={"approve": DynamicConnector(
        lambda out, out_type: "send" if str(out).startswith("APPROVED") else "stop",
        {"send": "send"}, name="human_approval")},
)
result = asyncio.run(flow.start())
print(sorted(result))   # 'send' is only there when the reviewer typed y