Robutler

Server Overview

Deploy agents as OpenAI-compatible API servers.

Quick Start

Basic Server

import { BaseAgent } from 'webagents';
import { serve } from 'webagents/server/node';

const agent = new BaseAgent({
  name: 'assistant',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-4o',
});

await serve(agent, { host: '0.0.0.0', port: 8000 });

Multiple Agents

import { BaseAgent } from 'webagents';
import { createAgentApp } from 'webagents/server';
import { serve } from 'webagents/server/node';

const agents = [
  new BaseAgent({
    name: 'support',
    instructions: 'You are a customer service agent',
    model: 'openai/gpt-4o',
  }),
  new BaseAgent({
    name: 'analyst',
    instructions: 'You are a data analyst',
    model: 'anthropic/claude-3-sonnet',
  }),
];

const app = createAgentApp({ agents, title: 'Multi-Agent Server' });
await serve(app, { host: '0.0.0.0', port: 8000 });

[!NOTE] Agent names can include dots for namespace hierarchy (e.g. alice.my-bot, alice.my-bot.helper). Dots are ordinary characters in URL path segments, so names like alice.my-bot are served at /agents/alice.my-bot/chat/completions with zero routing changes.

Server Parameters

The create_server() function accepts these key parameters:

ParameterTypeDefaultDescription
titlestr"WebAgents Server"Server title for OpenAPI docs
descriptionstr"AI Agent Server..."Server description
versionstr"1.0.0"API version
agentsList[BaseAgent][]Static agents to serve
dynamic_agentsCallableNoneDynamic agent resolver function
url_prefixstr""URL prefix (e.g., "/agents")

Advanced Parameters

import { createAgentApp } from 'webagents/server';

const app = createAgentApp({
  agents,
  title: 'Production Server',
  urlPrefix: '/api/v1',
  enableCors: true,
  requestTimeoutMs: 300_000,
  // dynamicAgents: resolveAgent,  // see ../server/dynamic-agents.md
});

API Endpoints

The server automatically creates these endpoints for each agent:

GET  /                              # Server info
GET  /health                        # Health check
GET  /{agent_name}                  # Agent info
POST /{agent_name}/chat/completions # OpenAI-compatible chat
GET  /{agent_name}/health           # Agent health

With url_prefix="/agents":

POST /agents/{agent_name}/chat/completions

Client Usage

OpenAI SDK Compatible

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'http://localhost:8000/assistant',
  apiKey: 'your-api-key',
});

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});

Streaming

const stream = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Tell me a story' }],
  stream: true,
});

for await (const chunk of stream) {
  const delta = chunk.choices[0].delta.content;
  if (delta) process.stdout.write(delta);
}

Environment Variables

# LLM Provider Keys
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key

# Optional Server Configuration
ROBUTLER_HOST=0.0.0.0
ROBUTLER_PORT=8000

See Also

On this page