Volcano SDK

https://volcano.dev/docs
Admin
A TypeScript SDK for building AI agents that combine LLM reasoning with real-world actions via Model...
Tokens:21,251
Snippets:111
Trust Score:5.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Volcano SDK with npm

Source: https://volcano.dev/docs/index

Installs the core Volcano SDK, which includes support for OpenAI, Anthropic, Mistral, Llama, and Google Vertex providers. This is the primary command for getting started with the SDK.

```bash
npm install volcano-sdk
```

--------------------------------

### Untitled

No description

--------------------------------

### Install Optional OpenTelemetry Observability Packages

Source: https://volcano.dev/docs/index

Installs packages for integrating OpenTelemetry for distributed tracing and metrics. These are optional and used for production observability, allowing monitoring and debugging.

```bash
# For distributed tracing and metrics
npm install @opentelemetry/api
npm install @opentelemetry/sdk-node
npm install @opentelemetry/exporter-trace-otlp-http
```

--------------------------------

### Volcano SDK Agent Workflow Example (JavaScript)

Source: https://volcano.dev/docs/api

Demonstrates how to create an agent workflow using the Volcano SDK, chaining steps with `.then()`, and executing the workflow with `.run()`. It shows how to access results from individual steps and aggregated metrics from the final step.

```javascript
const results = await agent({ llm })
  .then({ prompt: "Analyze sentiment", mcps: [analytics] })
  .then({ prompt: "Generate summary" })
  .run();


// Access first step results
console.log(results[0].prompt); // "Analyze sentiment"
console.log(results[0].llmOutput); // LLM response
console.log(results[0].toolCalls); // Tools that were called
console.log(results[0].durationMs); // Step duration
console.log(results[0].llmMs); // LLM time


// Access aggregated metrics (on last step)
const last = results[results.length - 1];
console.log(last.totalDurationMs); // Total workflow time
console.log(last.totalLlmMs); // Total LLM time
console.log(last.totalMcpMs); // Total MCP time

```

--------------------------------

### Install Optional AWS Bedrock Dependencies

Source: https://volcano.dev/docs/index

Installs necessary packages for AWS Bedrock provider support, including runtime clients and credential providers. These are optional and only needed if you plan to use AWS Bedrock.

```bash
# For AWS Bedrock
npm install @aws-sdk/client-bedrock-runtime @aws-sdk/credential-providers
```

--------------------------------

### Volcano SDK Hello World Agent (TypeScript)

Source: https://volcano.dev/docs/index

A basic example demonstrating how to create a simple AI agent using Volcano SDK. It initializes an OpenAI LLM and runs a single step to generate a greeting. Requires OpenAI API key set in environment variables.

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


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


const results = await agent({ llm })
  .then({ prompt: "Say hello to Marco in one short sentence." })
  .run();


console.log(results[0].llmOutput);
// Output: "Hello Marco! Hope you're having a great day!"
```

--------------------------------

### Initialize Llama LLM Locally with Volcano SDK and Ollama

Source: https://volcano.dev/docs/providers

Initializes the Llama LLM client using the `llmLlama` function from `volcano-sdk`, configured for local execution via Ollama. Requires the `baseURL` pointing to the Ollama instance and the specific `model` identifier. An API key is optional for local Ollama setups. Generation options like temperature, max tokens, and repeat penalty are configurable. Dependencies include `volcano-sdk` and a local Ollama installation with the specified model pulled.

```typescript
import { llmLlama } from "volcano-sdk";


// Local Ollama setup
const llama = llmLlama({
  baseURL: "http://127.0.0.1:11434",
  model: "llama3.2:3b",
  apiKey: "", // Optional, not needed for local Ollama
  options: {
    temperature: 0.7,
    max_tokens: 2000,
    top_p: 0.9,
    top_k: 40,
    repeat_penalty: 1.1,
    seed: 42,
    num_predict: 2000,
  },
});
```

--------------------------------

### Install OpenTelemetry Dependencies for Volcano SDK

Source: https://volcano.dev/docs/observability

This command installs the necessary OpenTelemetry packages for enabling telemetry with the Volcano SDK. `@opentelemetry/api` is a required peer dependency for telemetry to function; if not installed, telemetry acts as a no-op. The other packages are optional for specific backends like Jaeger, Prometheus, or OTLP.

```bash
# Required for telemetry
npm install @opentelemetry/api


# Optional: SDK and exporters for backends
npm install @opentelemetry/sdk-node
npm install @opentelemetry/exporter-jaeger
npm install @opentelemetry/exporter-prometheus
npm install @opentelemetry/exporter-otlp-http

```

--------------------------------

### Data Processing Workflows (JavaScript)

Source: https://volcano.dev/docs/index

Shows how to implement data processing workflows with loops in Volcano SDK. This example iterates over a list of documents, summarizing each using a local LLM, and then aggregates all summaries into a final report using GPT-4.

```javascript
await agent()
  .forEach(documents, (doc, a) =>
    a.then({ llm: llama, prompt: `Summarize: ${doc}` })
  )
  .then({ llm: gpt4, prompt: "Aggregate all summaries into final report" })
  .run();
```

--------------------------------

### Customer Support Automation (JavaScript)

Source: https://volcano.dev/docs/index

Example of building a customer support automation agent. It classifies ticket urgency using an LLM and MCP tools, then branches execution based on urgency to either create an incident via PagerDuty or draft a response with another LLM.

```javascript
await agent({ llm: gpt4 })
  .then({ prompt: "Classify ticket urgency", mcps: [ticketing] })
  .branch((h) => h[0].llmOutput?.includes("URGENT"), {
    true: (a) => a.then({ mcp: pagerduty, tool: "create_incident" }),
    false: (a) => a.then({ llm: claude, prompt: "Draft response" }),
  })
  .run();
```

--------------------------------

### Install Optional Azure AI Dependencies

Source: https://volcano.dev/docs/index

Installs the Azure identity package, which is required for Azure AI provider features, specifically when using a credential chain. This is an optional dependency.

```bash
# For Azure AI (if using credential chain)
npm install @azure/identity
```

--------------------------------

### Configure OpenTelemetry SDK for Node.js

Source: https://volcano.dev/docs/observability

This snippet shows the one-time setup for the OpenTelemetry SDK in a Node.js application. It configures the service name and an OTLP trace exporter to send traces to a specified observability backend. Ensure the correct URL for your OTEL collector is provided. Dependencies: @opentelemetry/sdk-node, @opentelemetry/exporter-otlp-http.

```typescript
// app.ts or index.ts - run once at startup
import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";


// Configure OTEL to send to your observability backend
const sdk = new NodeSDK({
  serviceName: "my-agent-service",
  traceExporter: new OTLPTraceExporter({
    url: "http://localhost:4318/v1/traces", // Your OTEL collector
    // For production: configure your observability backend URL
    // url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
    // headers: { 'Authorization': `Bearer ${process.env.API_KEY}` }
  }),
});


sdk.start();


// Optional: Graceful shutdown
process.on("SIGTERM", async () => {
  await sdk.shutdown();
});

```

--------------------------------

### Azure OpenAI Authentication Examples (TypeScript)

Source: https://volcano.dev/docs/providers

Demonstrates three ways to authenticate with Azure OpenAI: using an API key, an Entra ID access token, and Azure's Default Credential chain. Ensure necessary environment variables (AZURE_AI_API_KEY, AZURE_ACCESS_TOKEN) are set for the first two methods.

```typescript
const azure1 = llmAzure({
  model: "gpt-4o-mini",
  endpoint: "https://your-resource.openai.azure.com/openai/responses",
  apiKey: process.env.AZURE_AI_API_KEY!,
});

const azure2 = llmAzure({
  model: "gpt-4o-mini",
  endpoint: "https://your-resource.openai.azure.com/openai/responses",
  accessToken: process.env.AZURE_ACCESS_TOKEN!,
});

const azure3 = llmAzure({
  model: "gpt-4o-mini",
  endpoint: "https://your-resource.openai.azure.com/openai/responses",
  // Uses Azure SDK credential providers automatically
});
```

--------------------------------

### Using a Custom LLM Provider with Volcano SDK (TypeScript)

Source: https://volcano.dev/docs/providers

Demonstrates how to integrate a custom LLM provider, created using the `llmCustom` function, with the Volcano SDK's `agent` function. This example shows initializing the agent with the custom provider and running a simple prompt.

```typescript
import { agent } from "volcano-sdk";
import { llmCustom } from "./my-custom-provider";

const customLLM = llmCustom({
  apiKey: process.env.CUSTOM_API_KEY!,
  model: "my-model-v1",
  baseURL: "https://api.myservice.com/v1",
});

const results = await agent({ llm: customLLM })
  .then({ prompt: "Hello from custom provider!" })
  .run();

console.log(results[0].llmOutput);
```

--------------------------------

### Multi-Provider Workflow with MCP Tools in Volcano SDK

Source: https://volcano.dev/docs/patterns

Combines different LLM providers with automatic MCP (Multi-Cloud Platform) tool selection for enhanced agent capabilities. This example shows how to integrate external services like databases and analytics platforms into the workflow.

```typescript
const database = mcp("http://localhost:5000/mcp");
const analytics = mcp("http://localhost:5001/mcp");


await agent()
  .then({
    llm: gpt,
    prompt: "Query user data from database",
    mcps: [database],
  })
  .then({
    llm: claude,
    prompt: "Perform statistical analysis",
    mcps: [analytics],
  })
  .then({
    llm: mistral,
    prompt: "Generate executive summary",
  })
  .run();

```

--------------------------------

### Untitled

No description

--------------------------------

### Multi-Step Research Agent with Streaming (JavaScript)

Source: https://volcano.dev/docs/index

An example of a multi-step research agent that uses MCP tools for data gathering, multiple LLMs for analysis, and implements streaming for real-time progress updates. The `stream()` method allows observing each step's completion as it happens.

```javascript
for await (const step of agent({ llm: gpt4 })
  .then({ prompt: "Research topic X", mcps: [web, database] })
  .then({ llm: claude, prompt: "Analyze findings" })
  .then({ llm: mistral, prompt: "Write comprehensive report" })
  .stream()) {
  updateUI(step); // Real-time progress
}
```

--------------------------------

### Custom LLM Provider Implementation (TypeScript)

Source: https://volcano.dev/docs/providers

Provides a concrete implementation of the `LLMHandle` interface for a custom LLM provider. This example demonstrates how to set up the provider, including its `gen`, `genWithTools`, and `genStream` methods, interacting with a hypothetical custom LLM API.

```typescript
import type { LLMHandle, ToolDefinition, LLMToolResult } from "volcano-sdk";

export function llmCustom(config: {
  apiKey: string;
  model: string;
  baseURL: string;
}): LLMHandle {
  return {
    id: "custom",
    model: config.model,
    client: null, // Your HTTP client or SDK instance

    async gen(prompt: string): Promise<string> {
      // Call your LLM API
      const response = await fetch(`${config.baseURL}/generate`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${config.apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          model: config.model,
          prompt: prompt,
        }),
      });

      const data = await response.json();
      return data.text;
    },

    async genWithTools(
      prompt: string,
      tools: ToolDefinition[]
    ): Promise<LLMToolResult> {
      // Call your LLM API with tool definitions
      const response = await fetch(`${config.baseURL}/generate-with-tools`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${config.apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          model: config.model,
          prompt: prompt,
          tools: tools.map((t) => ({
            name: t.name,
            description: t.description,
            parameters: t.parameters,
          })),
        }),
      });

      const data = await response.json();

      // Map your API response to LLMToolResult format
      return {
        content: data.text,
        toolCalls:
          data.tool_calls?.map((tc: any) => ({
            name: tc.name,
            arguments: tc.arguments,
            mcpHandle: tools.find((t) => t.name === tc.name)?.mcpHandle,
          })) || [],
      };
    },

    async *genStream(prompt: string): AsyncGenerator<string, void, unknown> {
      // Implement streaming if your provider supports it
      const response = await fetch(`${config.baseURL}/stream`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${config.apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          model: config.model,
          prompt: prompt,
        }),
      });

      const reader = response.body?.getReader();
      if (!reader) return;

      const decoder = new TextDecoder();
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        yield decoder.decode(value);
      }
    },
  };
}
```

--------------------------------

### Handle-Level MCP Authentication Configuration (JavaScript)

Source: https://volcano.dev/docs/mcp-tools

Provides examples of configuring authentication directly on an MCP handle for secure API interactions. Supports both OAuth 2.1 and Bearer token authentication methods as per the MCP specification.

```javascript
// OAuth on handle
const protectedMcp = mcp("https://api.example.com/mcp", {
  auth: {
    type: "oauth",
    clientId: process.env.MCP_CLIENT_ID!,
    clientSecret: process.env.MCP_CLIENT_SECRET!,
    tokenEndpoint: "https://api.example.com/oauth/token",
  },
});


// Bearer token on handle
const bearerMcp = mcp("https://api.example.com/mcp", {
  auth: {
    type: "bearer",
    token: process.env.MCP_BEARER_TOKEN!,
  },
});

```

--------------------------------

### Untitled

No description

--------------------------------

### Enable Volcano SDK Telemetry in Agents

Source: https://volcano.dev/docs/observability

This example demonstrates how to enable telemetry for your Volcano agents after configuring the OpenTelemetry SDK. It creates a telemetry instance using `createVolcanoTelemetry` and passes it to the agent configuration. This ensures that traces and metrics generated by the agent's workflow are automatically sent to your configured observability backend. Dependencies: volcano-sdk.

```typescript
import { agent, llmOpenAI, createVolcanoTelemetry } from "volcano-sdk";


// Create telemetry (uses global OTEL SDK configured above)
const telemetry = createVolcanoTelemetry({
  serviceName: "my-agent-service",
});


// Pass to agent
const results = await agent({
  llm: llmOpenAI({ apiKey: process.env.OPENAI_API_KEY! }),
  telemetry, // Enable observability
})
  .then({ prompt: "Analyze data" })
  .then({ prompt: "Generate report" })
  .run();


// Traces and metrics automatically sent to your configured backend!

```

--------------------------------

### Untitled

No description

--------------------------------

### Untitled

No description

--------------------------------

### Tool Arguments Schema Validation Example (JavaScript)

Source: https://volcano.dev/docs/mcp-tools

This code snippet illustrates how Volcano SDK validates tool arguments against a provided JSON schema before execution. It shows an example of a tool schema and a subsequent agent call where the arguments fail validation due to a missing required field and an invalid enum value. The expected outcome is a `ValidationError`.

```javascript
// If the MCP tool has this schema:
{
  "type": "object",
  "properties": {
    "city": { "type": "string" },
    "units": { "type": "string", "enum": ["celsius", "fahrenheit"] }
  },
  "required": ["city"]
}


// This call would fail validation:
await agent({ llm })
  .then({
    mcp: weather,
    tool: "get_weather",
    args: { units: "kelvin" }  // ❌ Missing required "city", invalid enum
  })
  .run();


// Error: ValidationError
// Message: "arguments failed schema validation: city is required; units must be one of..."
```

--------------------------------

### Two-Step Agent with MCP Tools (JavaScript)

Source: https://volcano.dev/docs/index

Demonstrates a two-step agent workflow using Volcano SDK, automatically discovering and utilizing MCP tools across steps. It initializes an LLM, connects to an MCP service, and executes sequential agent steps.

```javascript
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 steps = await agent({ llm })
  .then({
    prompt: "Determine the astrological sign for 1993-07-11.",
    mcps: [astro], // Automatic tool selection
  })
  .then({
    prompt: "Write a one-line fortune for that sign.",
    // Context from previous step is automatically included
  })
  .run();


console.log(steps[0].toolCalls); // Tools that were called
console.log(steps[1].llmOutput); // Fortune based on the sign
```

--------------------------------

### Untitled

No description

--------------------------------

### Create a Volcano Agent with Configuration

Source: https://volcano.dev/docs/index

Demonstrates how to create a new agent instance with optional configurations for LLM provider, instructions, timeout, retries, and context limits. The minimal configuration requires only an LLM provider.

```typescript
const myAgent = agent({
  llm,
  instructions: "...",
  timeout: 60,
  retry: { retries: 3 },
  contextMaxChars: 20480,
  contextMaxToolResults: 8,
});
```

--------------------------------

### Untitled

No description

--------------------------------

### Untitled

No description

--------------------------------

### Basic Multi-Provider Workflow with Volcano SDK

Source: https://volcano.dev/docs/patterns

Demonstrates how to use different LLM providers (OpenAI, Anthropic, Mistral) within a single agent workflow. Each step can leverage the unique strengths of different models, with context flowing automatically between them.

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


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


const claude = llmAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-3-5-haiku-20241022",
});


const mistral = llmMistral({
  apiKey: process.env.MISTRAL_API_KEY!,
  model: "mistral-small-latest",
});


// Each step uses a different LLM
await agent()
  .then({ llm: gpt, prompt: "Extract key data from this report..." })
  .then({ llm: claude, prompt: "Analyze the extracted data for patterns" })
  .then({ llm: mistral, prompt: "Write a creative summary in French" })
  .run();


// Context flows automatically between steps, regardless of provider

```

--------------------------------

### Untitled

No description

--------------------------------

### Volcano SDK - OpenAI Provider Configuration

Source: https://volcano.dev/docs/providers

This snippet shows how to initialize the OpenAI LLM provider using the Volcano SDK, including API key, model selection, and optional base URL.

```APIDOC
## POST /llm/openai

### Description
Initializes the OpenAI LLM provider with specified configuration.

### Method
POST

### Endpoint
/llm/openai

### Parameters
#### Request Body
- **apiKey** (string) - Required - OpenAI API key from platform.openai.com
- **model** (string) - Required - Model identifier (e.g., gpt-4o-mini, gpt-4o)
- **baseURL** (string) - Optional - Custom API endpoint (default: https://api.openai.com/v1)
- **options** (object) - Optional - Model-specific parameters
  - **temperature** (number) - 0-2 - Controls randomness.
  - **max_completion_tokens** (number) - Required - Maximum tokens to generate.
  - **top_p** (number) - 0-1 - Nucleus sampling.
  - **frequency_penalty** (number) - -2 to 2 - Reduces repetition.
  - **presence_penalty** (number) - -2 to 2 - Encourages topic diversity.
  - **stop** (string | string[]) - Stop sequences to end generation.
  - **seed** (number) - For deterministic outputs.
  - **response_format** (object) - Force JSON output: `{ type: "json_object" }`

### Request Example
```json
{
  "apiKey": "process.env.OPENAI_API_KEY!",
  "model": "gpt-4o-mini",
  "baseURL": "https://api.openai.com/v1",
  "options": {
    "temperature": 0.7,
    "max_completion_tokens": 2000,
    "top_p": 0.9,
    "seed": 42
  }
}
```

### Response
#### Success Response (200)
- **providerInstance** (object) - An instance of the configured OpenAI LLM provider.
```

--------------------------------

### Configure Timeouts for Agent Steps - JavaScript

Source: https://volcano.dev/docs/features

Timeouts can be configured globally for the agent or overridden on a per-step basis to limit execution time. Timeouts are specified in seconds. This example shows a global timeout of 60 seconds with a specific step overriding it to 5 seconds.

```javascript
await agent({ llm, timeout: 60 })
  .then({ prompt: "Quick check", timeout: 5 }) // Override to 5s
  .then({ prompt: "Next step uses agent default (60s)" })
  .run();
```

--------------------------------

### Explicit Tool Calling with Arguments (JavaScript)

Source: https://volcano.dev/docs/mcp-tools

Demonstrates how to explicitly call a specific tool on a given MCP server with predefined arguments. This is useful when the exact tool and its parameters are known.

```javascript
const cafe = mcp("http://localhost:3000/mcp");


await agent({ llm })
  .then({ prompt: "Recommend a coffee for Ava from Naples" })
  .then({
    mcp: cafe,
    tool: "order_item",
    args: { item_id: "espresso", quantity: 2 },
  })
  .run();

```

--------------------------------

### Configure Bearer Token Authentication for MCP (JavaScript)

Source: https://volcano.dev/docs/mcp-tools

This example shows how to configure Bearer Token authentication for an MCP server. This method is suitable for pre-acquired tokens or custom authentication flows. The token is passed directly within the `auth` configuration object to the `mcp` function.

```javascript
const authMcp = mcp("https://api.example.com/mcp", {
  auth: {
    type: "bearer",
    token: process.env.MCP_BEARER_TOKEN!,
  },
});


await agent({ llm })
  .then({ mcp: authMcp, tool: "secure_action", args: {} })
  .run();
```

--------------------------------

### Cost-Optimized Pipeline with Volcano SDK (Local & Cloud LLMs)

Source: https://volcano.dev/docs/patterns

Illustrates a cost-optimization strategy using local models (Llama) for initial processing and expensive cloud models (GPT-4o) for critical tasks. This approach reduces costs by performing cheaper preprocessing locally before engaging high-cost, high-quality models.

```typescript
import { agent, llmLlama, llmOpenAI } from "volcano-sdk";


const llama = llmLlama({
  baseURL: "http://127.0.0.1:11434",
  model: "llama3.2:3b", // Free, local
});


const gpt4 = llmOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o", // Expensive, high-quality
});


// Process 100 documents
await agent()
  .forEach(
    documents,
    (doc, a) => a.then({ llm: llama, prompt: `Summarize: ${doc}` }) // Cheap preprocessing
  )
  .then({ llm: gpt4, prompt: "Analyze all summaries and create final report" }) // Quality output
  .run();

```

--------------------------------

### Multi-Provider Workflow (JavaScript)

Source: https://volcano.dev/docs/index

Illustrates a workflow where different LLM providers (OpenAI, Anthropic, Mistral) are used for distinct steps within the same agent execution. This allows leveraging the strengths of various LLMs for different tasks.

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


const openai = llmOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o-mini",
});
const claude = llmAnthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: "claude-3-5-haiku-20241022",
});
const mistral = llmMistral({
  apiKey: process.env.MISTRAL_API_KEY!,
  model: "mistral-small-latest",
});


const results = await agent()
  .then({ llm: openai, prompt: "Extract key data from this report..." })
  .then({ llm: claude, prompt: "Analyze the data for patterns" })
  .then({ llm: mistral, prompt: "Write a creative summary" })
  .run();


// Each step uses a different provider. Context flows automatically.
```

--------------------------------

### Build Multi-Provider Workflows in TypeScript

Source: https://volcano.dev/docs/index

Shows how to configure and use different LLM providers (OpenAI, Anthropic, Mistral) within the same agent workflow. Each step can be assigned a specific LLM instance, enabling flexible model utilization for diverse tasks.

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

const openai = 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! });

await agent()
  .then({ llm: openai, prompt: "Get astrological sign for 1993-07-11" })
  .then({ llm: claude, prompt: "Analyze personality traits" })
  .then({ llm: mistral, prompt: "Write a creative horoscope" })
  .run();
```

--------------------------------

### Initialize OpenAI LLM Provider with Volcano SDK

Source: https://volcano.dev/docs/providers

Initializes the OpenAI LLM provider using the Volcano SDK. Requires an API key and supports model selection, custom base URLs, and various generation options like temperature and top_p. Dependencies include the 'volcano-sdk' package.

```javascript
import { llmOpenAI } from "volcano-sdk";


const openai = llmOpenAI({
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o-mini",
  baseURL: "https://api.openai.com/v1", // Optional
  options: {
    temperature: 0.7,
    max_completion_tokens: 2000,
    top_p: 0.9,
    seed: 42,
  },
});
```

--------------------------------

### Automatic Tool Selection with Multiple MCP Servers (JavaScript)

Source: https://volcano.dev/docs/mcp-tools

Demonstrates how the Volcano SDK's agent can automatically discover, select, and execute tools from multiple MCP servers based on a natural language prompt. The LLM orchestrates calls across different services to fulfill the request.

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


const weather = mcp("http://localhost:3000/mcp");
const notifications = mcp("http://localhost:4000/mcp");
const llm = llmOpenAI({ apiKey: process.env.OPENAI_API_KEY! });


await agent({ llm })
  .then({
    prompt: "Check SF weather for tomorrow and send me a notification.",
    mcps: [weather, notifications],
  })
  .run();


// The LLM automatically:
// 1. Discovers available tools from both servers
// 2. Selects the appropriate tools
// 3. Calls them with correct arguments
// 4. Returns the results

```

--------------------------------

### Provide Custom Tracer and Meter Instances (Node.js)

Source: https://volcano.dev/docs/observability

Shows how to explicitly provide custom OpenTelemetry tracer and meter instances when initializing the Volcano telemetry. This allows for more granular control over the telemetry context. It requires '@opentelemetry/api' and 'volcano-sdk'.

```javascript
import { trace, metrics } from "@opentelemetry/api";
import { createVolcanoTelemetry } from "volcano-sdk";


const tracer = trace.getTracer("my-custom-tracer");
const meter = metrics.getMeter("my-custom-meter");


const telemetry = createVolcanoTelemetry({
  serviceName: "my-agent",
  tracer,
  meter,
});

```

--------------------------------

### Agent Creation and Configuration

Source: https://volcano.dev/docs/api

This section describes how to create an agent workflow builder with various configuration options.

```APIDOC
## POST /agent

### Description
Creates an agent workflow builder.

### Method
POST

### Endpoint
`/agent`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **llm** (LLMHandle) - Required - Default LLM provider for all steps
- **instructions** (string) - Optional - Global system instructions
- **timeout** (number) - Optional - Default timeout per step (seconds). Default: 60
- **retry** (RetryConfig) - Optional - Retry configuration. Default: `{ retries: 3 }`
- **contextMaxChars** (number) - Optional - Soft cap for injected context size. Default: 20480
- **contextMaxToolResults** (number) - Optional - Number of recent tool results to include. Default: 8

### Request Example
```json
{
  "llm": "llmProvider",
  "instructions": "You are a helpful assistant",
  "timeout": 60,
  "retry": {
    "retries": 3
  }
}
```

### Response
#### Success Response (200)
- **AgentBuilder** (object) - An object that allows chaining methods to build an agent workflow.

#### Response Example
```json
{
  "agentBuilder": "..."
}
```
```

--------------------------------

### Untitled

No description

--------------------------------

### Configure OpenTelemetry via Environment Variables (Shell)

Source: https://volcano.dev/docs/observability

Demonstrates how to configure OpenTelemetry using standard environment variables. This includes setting the OTLP endpoint, service name, headers for authentication, and specifying which exporters to use for traces and metrics. These variables are crucial for directing telemetry data to the correct backend.

```shell
# OTLP endpoint (your observability backend)
export OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"


# Service name
export OTEL_SERVICE_NAME="my-agent"


# Headers (API keys, etc.)
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-api-key"


# Traces only, metrics only, or both
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"

```

--------------------------------

### Untitled

No description

--------------------------------

### Initialize Google Vertex AI Studio Provider

Source: https://volcano.dev/docs/providers

Initializes the Google Vertex AI Studio LLM provider for accessing Gemini models. Requires an API key and can optionally configure a baseURL and model-specific options like temperature, max_output_tokens, and top_k.

```typescript
import { llmVertexStudio } from "volcano-sdk";


const vertex = llmVertexStudio({
  model: "gemini-2.0-flash-exp",
  apiKey: process.env.GCP_VERTEX_API_KEY!,
  baseURL: "https://aiplatform.googleapis.com/v1", // Optional
  options: {
    temperature: 0.8,
    max_output_tokens: 2048,
    top_k: 40,
    top_p: 0.95,
    stop_sequences: ["\n\n"],
    candidate_count: 1,
    response_mime_type: "text/plain",
  },
});
```

--------------------------------

### Step Types

Source: https://volcano.dev/docs/api

Details the different types of steps supported by the Volcano SDK: LLM-Only, Automatic MCP Tool Selection, and Explicit MCP Tool Call.

```APIDOC
## Step Types

### Description
Volcano SDK supports three types of steps for defining agent behavior.

### 1. LLM-Only Step
Generate text with an LLM without tools.

#### Request Body Example
```json
{
  "prompt": "string",
  "llm": "LLMHandle",
  "instructions": "string",
  "timeout": "number",
  "retry": "RetryConfig",
  "contextMaxChars": "number",
  "contextMaxToolResults": "number",
  "pre": "() => void",
  "post": "() => void"
}
```

### 2. Automatic MCP Tool Selection
Let the LLM automatically choose which tools to call.

#### Request Body Example
```json
{
  "prompt": "string",
  "mcps": ["MCPHandle"],
  "llm": "LLMHandle",
  "instructions": "string",
  "timeout": "number",
  "retry": "RetryConfig",
  "contextMaxChars": "number",
  "contextMaxToolResults": "number",
  "pre": "() => void",
  "post": "() => void"
}
```

### 3. Explicit MCP Tool Call
Call a specific tool directly.

#### Request Body Example
```json
{
  "mcp": "MCPHandle",
  "tool": "string",
  "args": "Record<string, any>",
  "prompt": "string",
  "llm": "LLMHandle",
  "instructions": "string",
  "timeout": "number",
  "retry": "RetryConfig",
  "contextMaxChars": "number",
  "contextMaxToolResults": "number",
  "pre": "() => void",
  "post": "() => void"
}
```

### Common Step Fields
- **llm** (LLMHandle): Override the LLM for this step.
- **instructions** (string): Override system instructions for this step.
- **timeout** (number): Step timeout in seconds (overrides agent default).
- **retry** (RetryConfig): Retry config for this step (overrides agent default).
- **pre** (() => void): Hook called before step execution.
- **post** (() => void): Hook called after successful step execution.
```
Tokens:
Raw