VercelAISDK

Vercel AI SDK — algenta-tools

createAlgentaTools — a factory that connects to your engine's MCP endpoint via @ai-sdk/mcp's real MCP client and returns an Algenta-aware AI SDK ToolSet for generateText / streamText / an Agent, with typed ExecutionReceipt results and ExecutionBlockedError denials.

Install

npm install algenta-tools ai zod

ai (^7) and zod (^4) are peer dependencies. Node.js 22+. The only real dependency is @ai-sdk/mcp (the AI SDK's MCP client moved out of ai itself into that package); deliberately no algenta-sdk dependency — its hosted-default constants are exactly what this package must never use.

Quickstart

import { streamText } from "ai";
import { createAlgentaTools } from "algenta-tools";

const tools = await createAlgentaTools({ baseUrl: "http://localhost:8000/mcp", profile: "observe" });
const result = streamText({
  model: "openai/gpt-5",
  tools,
  prompt: "What's the expected value of scenario X?",
});

Endpoint resolves from baseUrl → ALGENTA_BASE_URL → http://localhost:8000/mcp (see Self-Hosted).

Profiles

All four, per the contract: observe (default) · govern · execute · full (opt-in). force/override_safety are stripped from every advertised JSON Schema and scrubbed from forwarded arguments, in every profile.

Notes

• Denials: a blocked execute_decision throws ExecutionBlockedError from execute() — the AI SDK's native "tool call failed" idiom — carrying gate ("idempotency" | "confidence" | "risk_floor"), code, and overrideHint, so your code branches on error.gate instead of re-parsing a message. No needsApproval pause is set — there is no asynchronous approval state to pause on.
• Factory, not a class: an AI SDK ToolSet is just Record<string, Tool> — the idiomatic shape in this ecosystem, rather than an invented "toolset" abstraction.
• Bring your own client: connectAlgentaMCPClient returns a reusable connected client (multiple profiles, custom headers, OAuth), and the tools option wraps a pre-built tool set with no MCP round trip.
• Try it locally: pnpm --filter algenta-tools example runs examples/try-it-locally.ts — stub server, real receipts, and a real ExecutionBlockedError (the idempotency gate), no engine required.
• Tests: real @modelcontextprotocol/sdk McpServer over a real node:http socket — pnpm --filter algenta-tools test.

Full reference: package README (full outcome mapping table, @ai-sdk/mcp rationale, advanced options).