Nodepool Documentation

Everything you need to build, connect, and deploy conversational agents on the web — with ~900ms voice, RAG, and tools in minutes.

Get started

Platform features

Platform at a glance

Quick Start

Get a text agent live in under 5 minutes with the CLI.

1 · Install

# Install globally
npm install -g @nodepool/cli
# Authenticate
nodepool auth login --key np_live_xxxxxxxxxxxxx

2 · Create agent

nodepool init my-agent
# Generates agent.yaml

3 · Configure agent.yaml

name: my-agent
model: gemini-flash
knowledge:
  - ./docs/
  - https://yoursite.com/faq
tools:
  - mcp://store/search
context:
  language: en
  persona: Helpful support agent for Acme.
  guardrails:
    - Never discuss competitors

4 · Deploy

nodepool deploy --prod
# ✓ 1,842 chunks indexed
# ✓ Live at https://agent.nodepool.dev/a/my-agent

Agents

An agent combines a model, knowledge base, tools, and context into a single API endpoint and embeddable widget.

Lifecycle

• Draft — created, knowledge indexing may be in progress
• Active — indexed, serving requests, consuming credits
• Paused — live but not consuming credits. Resumes instantly
• Archived — soft-deleted, data retained 30 days

Fields

Knowledge Base

Knowledge bases are vector stores built from your content. Nodepool ingests, generates embeddings, and stores them in Qdrant. The most relevant chunks are retrieved at every inference.

Supported sources

• Files — PDF, DOCX, MD, TXT, CSV (up to 50 MB)
• URLs — crawled recursively up to 3 levels deep
• APIs — any REST endpoint returning JSON or HTML
• Sync — scheduled re-ingestion (hourly / daily / weekly)

nodepool kb ingest ./docs/ --kb-id kb_acme
nodepool kb ingest https://acme.com/faq --kb-id kb_acme
nodepool kb status kb_acme
# ✓ 3,204 chunks · last indexed 2 min ago

Tools & MCP Skills

Tools let agents take actions beyond answering questions. Nodepool exposes tools via the Model Context Protocol (MCP).

Built-in skills

Agent Context

Context defines the agent's identity and behavioral limits. Injected as a system prompt prefix before every turn.

Authentication

All API calls require a bearer token. Keys are prefixed np_live_ for production, np_test_ for sandbox.

Authorization: Bearer np_live_xxxxxxxxxxxxx

• Rate limit: 300 req/min per key
• Rotate via dashboard or nodepool auth rotate
• Never share keys across tenants

/v1/agents/chat

Send a message to an active agent. Returns SSE by default; pass stream: false for a single JSON response.

{
  "agent_id":    "agt_xxxx",
  "message":     "Do you have trail shoes in size 9?",
  "session_id":  "sess_123",
  "stream":      true,
  "session_vars": { "user_name": "Ana" }
}

data: {"type":"delta","text":"Yes — here are two options:"}
data: {"type":"tool_call","tool":"mcp://store/search","result":[...]}
data: {"type":"done","usage":{"credits":1,"latency_ms":912}}

/v1/agents

List all agents. Paginated, 20 per page.

Create a new agent. Triggers KB indexing if knowledge_base_id is set.

Retrieve a single agent.

Archive an agent. Data retained 30 days.

/v1/kb

Create a knowledge base. Optionally pass sources to trigger immediate ingestion.

Add content. Accepts file upload (multipart/form-data) or URL array.

{ "id": "kb_acme", "status": "ready", "chunks": 3204 }

Voice (~900ms)

Real-time voice in the browser with ~900ms end-to-end latency — speech-to-speech in a single unified pipeline.

1. Browser captures audio via getUserMedia
2. Audio streamed to Nodepool over WebSocket
3. Transcribed, processed, and synthesized in one step
4. Audio chunks stream back in real time

import { NodepoolVoice } from "@nodepool/sdk";
const voice = new NodepoolVoice({ agentId: "agt_xxxx", apiKey: "np_live_xxx" });
await voice.start();
voice.on("transcript", (text) => console.log("User:", text));
voice.on("reply",      (text) => console.log("Agent:", text));
voice.on("latency",    (ms)   => console.log("RTT:", ms + "ms"));

SSE Streaming

Every /v1/agents/chat call with stream: true returns a text/event-stream response.

Web Embed

One script tag on any HTML page. Supports text, voice, and search.

<script
  src="https://cdn.nodepool.dev/widget.js"
  data-agent="agt_xxxx"
  data-key="np_pub_xxx"
  data-mode="voice"
  async
></script>

Infrastructure

Limits & Credits

One credit = one text conversation session. Voice is billed per minute. Overage billed at period end.