🌋 Volcano SDK

The TypeScript SDK for Multi-Provider AI Agents

Build agents that chain LLM reasoning with MCP tools. Mix OpenAI, Claude, Mistral in one workflow. Parallel execution, branching, loops. Native retries, streaming, and typed errors.

📚 Read the full documentation at volcano.dev →

✨ Features

⚡️ Chainable API

Chain steps with .then() and .run(). Promise-like syntax for building multi-step workflows.

✨ Automatic Tool Selection

LLM automatically selects and calls appropriate MCP tools based on the prompt. No manual routing required.

🔧 100s of Models

OpenAI, Anthropic, Mistral, Llama, Bedrock, Vertex, Azure. Switch providers per-step or use globally.

🧩 Multi-Agent Crews

Define specialized agents that autonomously coordinate based on descriptions. LLM automatically selects the right agent for each task - like automatic tool selection, but for agents.

🔄 Advanced Patterns

Parallel execution, conditional branching, loops, and sub-agent composition for complex workflows.

⏱️ Retries & Timeouts

Three retry strategies: immediate, delayed, and exponential backoff. Per-step timeout configuration.

📡 Streaming Workflows

Stream step results as they complete, or stream individual tokens in real-time with metadata. Perfect for SSE, real-time chat UIs, and long-running tasks.

🎯 MCP Integration

Native Model Context Protocol support with connection pooling, tool discovery, and authentication.

🛡️ TypeScript-First

Full TypeScript support with type inference and IntelliSense for all APIs.

📊 OpenTelemetry Observability

Production-ready distributed tracing and metrics. Monitor performance, debug failures. Export to Jaeger, Prometheus, DataDog, NewRelic.

🔐 MCP OAuth Authentication

OAuth 2.1 and Bearer token authentication per MCP specification. Agent-level or handle-level configuration with automatic token refresh.

⚡ Performance Optimized

Intelligent connection pooling for MCP servers, tool discovery caching with TTL, and JSON schema validation for reliability.

💬 Conversational Results

Ask questions about agent execution in natural language. Use an LLM to analyze results, explain what happened, and extract insights.

Explore all features →

Quick Start

Installation

npm install volcano-sdk

That's it! Includes MCP support and all common LLM providers (OpenAI, Anthropic, Mistral, Llama, Vertex).

View installation guide →

Hello World

import { agent, llmOpenAI, mcp } from "volcano-sdk";

const llm = llmOpenAI({ 
  apiKey: process.env.OPENAI_API_KEY!, 
  model: "gpt-4o-mini" 
});

const astro = mcp("http://localhost:3211/mcp");

const results = await agent({ llm })
  .then({ 
    prompt: "Find the astrological sign for birthdate 1993-07-11",
    mcps: [astro]  // Automatic tool selection
  })
  .then({ 
    prompt: "Write a one-line fortune for that sign" 
  })
  .run();

console.log(results[1].llmOutput);
// Output: "Fortune based on the astrological sign"

Multi-Provider Workflow

import { agent, llmOpenAI, llmAnthropic, llmMistral } from "volcano-sdk";

const gpt = llmOpenAI({ apiKey: process.env.OPENAI_API_KEY! });
const claude = llmAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });
const mistral = llmMistral({ apiKey: process.env.MISTRAL_API_KEY! });

// Use different LLMs for different steps
await agent()
  .then({ llm: gpt, prompt: "Extract data from report" })
  .then({ llm: claude, prompt: "Analyze for patterns" })
  .then({ llm: mistral, prompt: "Write creative summary" })
  .run();

View more examples →

Documentation

📖 Comprehensive Guides

• Getting Started - Installation, quick start, core concepts
• LLM Providers - OpenAI, Anthropic, Mistral, Llama, Bedrock, Vertex, Azure
• MCP Tools - Automatic selection, OAuth authentication, connection pooling
• Advanced Patterns - Parallel, branching, loops, multi-LLM workflows
• Features - Streaming, retries, timeouts, hooks, error handling
• Observability - OpenTelemetry traces and metrics
• API Reference - Complete API documentation
• Examples - Ready-to-run code examples

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Questions or Feature Requests?

• 📝 Report bugs or issues
• 💡 Request features or ask questions
• ⭐ Star the project if you find it useful

License

Apache 2.0 - see LICENSE file for details.