DOCSEARCHbyAlgolia
Submit Docs

Volcano Agent SDK

repository·main·Indexed 19 days ago

https://github.com/kong/volcano-agent-sdk

A TypeScript-first framework for building multi-provider AI agents that combine LLM reasoning with real-world actions via Model Context Protocol (MCP) tools. The SDK supports coordinating complex multi-agent workflows, connecting to MCP servers via HTTP or stdio transport, and implementing advanced patterns like parallel execution, branching, and autonomous delegation.

Tokens
50.8K
Snippets
153
Records
184
Agent score
63%

What's inside volcano-agent-sdk

  1. Build autonomous multi-agent crews

    main

    You can build crews of specialized agents that automatically coordinate with each other. Instead of manual orchestration or complex state machines, you define agents with specific name and description properties. An LLM coordinator then intelligently routes tasks to the appropriate agent based on those descriptions.

    To implement a crew:

    1. Define specialized agents using agent({ llm, name, description }).
    2. Create a coordinator agent using agent({ llm }).
    3. Use .then({ prompt, agents: [...] }) to provide the coordinator with the list of available agents.
    4. Call .run() to execute the autonomous workflow.
    import { agent, llmOpenAI } from "@volcano.dev/agent";

const llm = llmOpenAI({ apiKey: process.env.OPENAI_API_KEY! });

// 1. Define specialized agents with clear roles
const researcher = agent({
  llm,
  name: "researcher",
  description: "Analyzes topics, gathers data, and provides factual information.",
});

const writer = agent({
  llm,
  name: "writer",
  description: "Creates engaging, well-structured articles and content.",
});

// 2. Create a coordinator that autonomously delegates tasks
const results = await agent({ llm })
  .then({
    prompt: "Create a comprehensive blog post about AI safety",
    agents: [researcher, writer],
  })
  .run();

  2. Compose agents using .runAgent()

    main

    For modular and reusable workflows, you can treat an existing agent as a component within another agent. Use the .runAgent(subAgent) method to explicitly compose a workflow where the output of one agent is passed to another.

    const analyzer = agent({ llm })
  .then({ prompt: "Analyze sentiment" })
  .then({ prompt: "Extract topics" });

await agent({ llm })
  .then({ prompt: "Customer feedback: ..." })
  .runAgent(analyzer) // Explicit composition
  .run();

  3. Implement conditional branching and parallel execution

    main

    Volcano supports advanced control flows:

    • Branching: Use .branch() to route the workflow based on LLM output.
    • Parallel Execution: Use .parallel() to run multiple prompts simultaneously.
    • Switching: Use .switch() to route based on results from a parallel execution block.
    // Branching Example
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();

// Parallel and Switch Example
await agent({ llm })
  .parallel({
    sentiment: { prompt: "Analyze sentiment" },
    topics: { prompt: "Extract topics" },
    violations: { prompt: "Check policy violations" },
  })
  .switch(
    (h) =>
      h[0].parallel?.violations.llmOutput?.includes("VIOLATION")
        ? "flag"
        : "approve",
    {
      flag: (a) => a.then({ mcp: moderation, tool: "flag_content" }),
      approve: (a) => a.then({ mcp: cms, tool: "publish" }),
    }
  )
  .run();

  6. Use different step types in a workflow

    main

    Workflows are composed of different types of steps:

    LLM-Only Step

    Generates text with an LLM without using any tools.

    { prompt: string; llm?: LLMHandle; ... }

    Automatic MCP Tool Selection

    Allows the LLM to autonomously choose and call tools from provided MCP handles.

    { prompt: string; mcps: MCPHandle[]; maxToolIterations?: number; ... }

    Explicit MCP Tool Call

    Calls a specific tool directly.

    { mcp: MCPHandle; tool: string; args?: Record<string, any>; ... }

    Multi-Agent Coordination

    Delegates tasks to specialized sub-agents. The coordinator LLM uses the name and description of the provided AgentBuilder instances to decide which agent to use.

    { prompt: string; agents: AgentBuilder[]; ... }

  7. How Automatic Tool Selection works

    main

    Automatic tool selection is the recommended approach where the LLM intelligently chooses which tools to call based on the prompt.

    The workflow follows these steps:

    1. Tool Discovery: Volcano fetches available tools from MCP servers (cached with TTL).
    2. LLM Selection: The LLM analyzes the prompt and chooses relevant tools.
    3. Schema Validation: Arguments are validated against JSON Schema before execution.
    4. Iterative Calling: The LLM can make multiple tool calls in sequence (default: 4 iterations).
    5. Parallel Execution: Multiple tool calls are executed simultaneously when safe.
    6. Context Flow: Tool results are automatically included in subsequent steps.

  8. Provider Support Matrix

    main

    Volcano Agent SDK supports 100s of models from 7 providers. All providers support automatic tool selection and multi-step workflows. The following matrix outlines the capabilities of each supported provider:

    ProviderBasic GenerationFunction CallingStreamingMCP Integration
    OpenAI✅ Full✅ Native✅ Native✅ Complete
    Anthropic✅ Full✅ Native (tool_use)✅ Native✅ Complete
    Mistral✅ Full✅ Native✅ Native✅ Complete
    Llama✅ Full✅ Via Ollama✅ Native✅ Complete
    AWS Bedrock✅ Full✅ Native (Converse API)✅ Native✅ Complete
    Google Vertex Studio✅ Full✅ Native (Function calling)✅ Native✅ Complete
    Azure AI✅ Full✅ Native (Responses API)✅ Native✅ Complete

  9. Compose workflows using Sub-Agents

    main

    Build modular, reusable agent components using agent() and compose them into larger workflows using .runAgent(subAgent).

    Context Propagation: Sub-agents automatically inherit the parent agent's context, including conversation history, LLM outputs, and tool results. This allows a sub-agent to 'know' about the data fetched or analyzed by the parent in previous steps.

    // Define a reusable sub-agent
const emailAnalyzer = agent({ llm: claude })
  .then({ prompt: "Extract sender intent" })
  .then({ prompt: "Classify urgency level" });

// Compose in a main workflow
await agent({ llm })
  .then({ mcp: gmail, tool: "fetch_unread" })
  .runAgent(emailAnalyzer) // Inherits context from fetch_unread
  .run();

  10. Use MCP tools with automatic selection

    main

    The SDK supports Model Context Protocol (MCP) for tool use. You can provide a list of MCP servers via the mcps option, and the agent will automatically discover and select the appropriate tools based on the prompt.

    // Example pattern for tool discovery
const agentInstance = agent({ 
  llm, 
  mcps: [/* MCP server configurations */] 
});

  11. Analyze agent execution with Conversational Results

    main

    Instead of manually parsing the StepResult[] array, you can use the Conversational Results API to ask natural language questions about what the agent did. This uses an LLM to analyze the execution history (prompts, outputs, tool calls, and timing) and provide contextual answers.

    Available Methods

    • results.ask(llm, question): Ask any arbitrary question about the execution.
    • results.summary(llm): Get a high-level overview of the workflow (e.g., "The agent completed 3 steps in 15.2 seconds...").
    • results.toolsUsed(llm): Get a description of which tools were called and why.
    • results.errors(llm): Check for issues or failures within the execution.

    Cost Optimization Tip

    For better efficiency, use a high-performance model (e.g., GPT-5) for the actual agent work, but use a cheaper, faster model (e.g., GPT-4o-mini) for the results.ask() or results.summary() calls.

    const results = await agent({ llm })
  .then({ prompt: "Analyze sales data", mcps: [database] })
  .then({ prompt: "Generate report" })
  .run();

// Use a cheap model for post-analysis
const summaryLlm = llmOpenAI({ model: "gpt-4o-mini" });

const summary = await results.summary(summaryLlm);
const tools = await results.toolsUsed(summaryLlm);
const answer = await results.ask(summaryLlm, "What were the key findings?");

  12. Understand MCP Connection Pooling and Caching

    main

    Volcano Agent SDK optimizes MCP interactions through several internal mechanisms:

    Connection Pooling

    • Automatic pooling: TCP sessions are reused across steps.
    • Per-endpoint pools: Each MCP server maintains its own pool.
    • Auth-aware: Authenticated connections are pooled separately.
    • Defaults: Max 16 connections, 30s idle timeout.

    Tool Discovery Cache

    • TTL Caching: Results from listTools() are cached for 60s to reduce latency.
    • Invalidation: The cache is cleared if a server becomes unavailable.

    Schema Validation

    Tool arguments are validated against the MCP server's JSON Schema before execution. If arguments do not match the required properties or allowed enum values, a ValidationError is thrown.