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 likealice.my-botare served at/agents/alice.my-bot/chat/completionswith zero routing changes.
Server Parameters
The create_server() function accepts these key parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
title | str | "WebAgents Server" | Server title for OpenAPI docs |
description | str | "AI Agent Server..." | Server description |
version | str | "1.0.0" | API version |
agents | List[BaseAgent] | [] | Static agents to serve |
dynamic_agents | Callable | None | Dynamic agent resolver function |
url_prefix | str | "" | 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 healthWith url_prefix="/agents":
POST /agents/{agent_name}/chat/completionsClient 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=8000See Also
- Dynamic Agents - Runtime agent loading
- Architecture - Production patterns
- Agent Endpoints - Custom HTTP endpoints