https://github.com/arashsheyda/nuxt-volcano
🌋 Nuxt module for Volcano Agent SDK - build AI agents with LLM reasoning and MCP tools
https://github.com/arashsheyda/nuxt-volcano
agent nuxt volcano
Last synced: 6 days ago
JSON representation
🌋 Nuxt module for Volcano Agent SDK - build AI agents with LLM reasoning and MCP tools
- Host: GitHub
- URL: https://github.com/arashsheyda/nuxt-volcano
- Owner: arashsheyda
- Created: 2026-05-29T04:48:50.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-05-29T06:47:39.000Z (19 days ago)
- Last Synced: 2026-05-29T07:08:37.172Z (19 days ago)
- Topics: agent, nuxt, volcano
- Language: TypeScript
- Homepage: https://npmx.dev/package/nuxt-volcano
- Size: 337 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
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:
```bash
npx nuxi module add nuxt-volcano
```
Add to `nuxt.config.ts`:
```ts
export default defineNuxtConfig({
modules: ['nuxt-volcano'],
volcano: {
defaultProvider: 'openai',
defaultModel: 'gpt-4o-mini',
},
})
```
Set your API key via environment variable:
```bash
NUXT_VOLCANO_OPENAI_API_KEY=sk-...
```
## Usage
### Server API Route
```ts
// 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
```ts
// 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
```ts
const agent = useVolcanoAgent({ provider: 'anthropic', model: 'claude-3-5-sonnet-20241022' })
```
### Direct LLM Access
```ts
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:
```vue
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),
})
{{ msg.role }}: {{ msg.content }}
Send
Stop
```
#### Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `api` | `string` | `'/api/agent'` | Server endpoint URL |
| `stream` | `boolean` | `false` | Enable SSE token streaming |
| `initialMessages` | `ChatMessage[]` | `[]` | Pre-populate chat history |
| `body` | `object` | -- | Extra fields sent with every request |
| `headers` | `object` | -- | Extra headers sent with every request |
| `onToken` | `(token: string) => void` | -- | Callback per streamed token |
| `onFinish` | `(msg: ChatMessage) => void` | -- | Callback when response completes |
| `onError` | `(err: Error) => void` | -- | Callback on error |
#### Return Value
| Property | Type | Description |
|----------|------|-------------|
| `messages` | `Ref` | Reactive message history |
| `input` | `Ref` | Bound to your text input |
| `isLoading` | `Ref` | True while waiting for a response |
| `error` | `Ref` | Last error, if any |
| `send(content?)` | `(string?) => Promise` | Send a message (uses `input` if no arg) |
| `stop()` | `() => void` | Abort the current request |
| `clear()` | `() => void` | Reset messages to initial state |
| `setMessages()` | `(msgs) => void` | Replace message history |
### `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:
```ts
// 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`)
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `defaultProvider` | `string` | `'openai'` | Default LLM provider |
| `defaultModel` | `string` | -- | Default model identifier |
| `instructions` | `string` | -- | Global system instructions |
| `timeout` | `number` | `60` | Default step timeout (seconds) |
| `retry` | `RetryConfig` | -- | Retry configuration |
| `contextMaxChars` | `number` | `20480` | Context size limit |
| `contextMaxToolResults` | `number` | `8` | Tool results in context |
| `maxToolIterations` | `number` | `4` | Max tool calls per step |
| `disableParallelToolExecution` | `boolean` | `false` | Force sequential tool execution |
| `hideProgress` | `boolean` | `false` | Suppress progress output |
### Environment Variables
API keys are set via `NUXT_VOLCANO_*` environment variables:
| Variable | Provider |
|----------|----------|
| `NUXT_VOLCANO_OPENAI_API_KEY` | OpenAI |
| `NUXT_VOLCANO_ANTHROPIC_API_KEY` | Anthropic |
| `NUXT_VOLCANO_MISTRAL_API_KEY` | Mistral |
| `NUXT_VOLCANO_VERTEX_API_KEY` | Google Vertex |
| `NUXT_VOLCANO_AZURE_API_KEY` | Azure AI |
| `NUXT_VOLCANO_AZURE_ENDPOINT` | Azure AI endpoint |
| `NUXT_VOLCANO_BEDROCK_ACCESS_KEY_ID` | AWS Bedrock |
| `NUXT_VOLCANO_BEDROCK_SECRET_ACCESS_KEY` | AWS Bedrock |
| `NUXT_VOLCANO_BEDROCK_REGION` | AWS Bedrock region |
## Development
```bash
# Install dependencies
pnpm install
# Develop with the playground
pnpm dev
# Run tests
pnpm test
# Build the module
pnpm prepack
```