nuxt-volcano

nuxt-volcano

Nuxt module for the Volcano Agent SDK — build AI agents that combine LLM reasoning with real-world actions via MCP tools.

Features

• 🔒 Server-side only: API keys stay safe in runtime config
• 🔌 Auto-imports: useVolcanoAgent(), useVolcanoLLM(), agent(), and mcp() available in server routes
• 💬 Client composable: useVolcanoChat() for building chat UIs with streaming support
• 🌊 SSE streaming: defineVolcanoStreamHandler() streams tokens to the browser in real-time
• 🤖 Multi-provider: OpenAI, Anthropic, Mistral, Llama, Bedrock, Vertex, Azure
• ⚡ Zero config: set an API key env var and go

Quick Setup

Install the module:

npx nuxi module add nuxt-volcano

Add to nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['nuxt-volcano'],
  volcano: {
    defaultProvider: 'openai',
    defaultModel: 'gpt-4o-mini',
  },
})

Set your API key via environment variable:

NUXT_VOLCANO_OPENAI_API_KEY=sk-...

Usage

Server API Route

// server/api/agent.post.ts
export default defineEventHandler(async (event) => {
  const { prompt } = await readBody(event)

  const myAgent = useVolcanoAgent()

  const results = await myAgent
    .then({ prompt })
    .run()

  return { output: results[0]?.llmOutput }
})

With MCP Tools

// server/api/research.post.ts
export default defineEventHandler(async (event) => {
  const { prompt } = await readBody(event)

  const myAgent = useVolcanoAgent()
  const webTools = mcp('http://localhost:3211/mcp')

  const results = await myAgent
    .then({ prompt, mcps: [webTools] })
    .then({ prompt: 'Summarize the findings.' })
    .run()

  return { output: results.at(-1)?.llmOutput }
})

Using a Different Provider Per-Request

const agent = useVolcanoAgent({ provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' })

Direct LLM Access

const llm = useVolcanoLLM({ provider: 'openai', model: 'gpt-4o' })
const response = await llm.gen('Hello!')

Client-Side

useVolcanoChat() Chat UI Composable

A Vue composable for building chat interfaces with optional SSE streaming:

<script setup>
const { messages, input, isLoading, error, send, stop, clear } = useVolcanoChat({
  api: '/api/chat',
  stream: true, // Enable real-time token streaming
  onToken: (token) => console.log(token),
  onFinish: (msg) => console.log('Done:', msg.content),
})
</script>

<template>
  <div v-for="msg in messages" :key="msg.content">
    <strong>{{ msg.role }}:</strong> {{ msg.content }}
  </div>
  <form @submit.prevent="send()">
    <input v-model="input" placeholder="Type a message..." />
    <button v-if="!isLoading" type="submit">Send</button>
    <button v-else type="button" @click="stop()">Stop</button>
  </form>
</template>

Options

Return Value

defineVolcanoStreamHandler() SSE Server Endpoint

A server utility that creates an endpoint supporting both JSON and SSE streaming. Automatically detects the Accept: text/event-stream header:

// server/api/chat.post.ts
export default defineVolcanoStreamHandler({
  async handler(event, { prompt, onToken }) {
    const myAgent = useVolcanoAgent()
    const results = await myAgent
      .then({ prompt, onToken })
      .run()
    return results[0]?.llmOutput ?? ''
  },
})

• With stream: true on the client → SSE response, tokens arrive in real-time
• Without streaming (regular $fetch) → JSON response { output: "..." }

Configuration

Module Options (nuxt.config.ts)

Environment Variables

API keys are set via NUXT_VOLCANO_* environment variables:

Development

# Install dependencies
pnpm install

# Develop with the playground
pnpm dev

# Run tests
pnpm test

# Build the module
pnpm prepack