Agent Server

Cognipeer Agent Server

REST API infrastructure for AI agents. Register an agent once and get conversations, storage, authentication, streaming, human approvals, files, budgets and interactive API docs, without writing that plumbing yourself.

• Package @cognipeer/agent-server 0.3.0
• Storage PostgreSQL · MongoDB · SQLite · memory
• Frameworks Express · Next.js · Fastify · Node http · custom adapters
• Node 18 or newer

Register agents built with @cognipeer/agent-sdk directly, serve your own backend as a host-backed agent, bring an agent from any other library through a simple handler, or point the server at an OpenAI-compatible endpoint. Whichever you choose, you get the same REST surface: conversations, messages, files, approvals and streaming, backed by a storage provider that migrates itself.

import express from 'express';
import {
  createAgentServer,
  createPostgresProvider,
  createExpressMiddleware,
} from '@cognipeer/agent-server';
import { createSmartAgent } from '@cognipeer/agent-sdk';

const storage = createPostgresProvider({
  connectionString: 'postgresql://user:pass@localhost:5432/mydb',
});

const agentServer = createAgentServer({
  basePath: '/api/agents',
  storage,
  allowAnonymousList: true, // a quick start with no sign-in: see "Who may list" in Request Context
  swagger: { enabled: true, path: '/docs', title: 'My Agent API' },
});

const myAgent = createSmartAgent({ name: 'Assistant', model: myLLMModel, tools: [...] });
agentServer.registerSDKAgent('assistant', myAgent, { description: 'A helpful assistant' });

const app = express();
app.use(express.json());
await storage.connect();
app.use(createExpressMiddleware(agentServer));
app.listen(3000);

Guide

Getting started

Install the package, register an agent, and mount the middleware.

Guide

Upgrading to 0.3.0

What changes behaviour for a 0.1.x or 0.2.x server, and what is new.

Guide

Approvals & questions

Pause a turn for a tool approval, a question or a client tool, and carry on when a person answers.

Guide

Runs, cancel & reattach

Turns that outlive the connection, a Stop button that works, and an event log to follow.

Guide

Files

Uploads the agent reads: inline, in pages, images by reference, with ownership and retention.

Guide

Usage & budgets

What every turn cost, and a spend limit per conversation that a person can raise.

Guide

Host-backed agents

Serve an agent that runs in your own backend as a first-class agent.

Guide

Chat experience

Regenerate, edit, pin, rename, titles, starters, feedback and export.

Guide

Embedding & limits

Bearer auth for chats in other sites, rate limits and an audit trail.

Guide

Storage providers

PostgreSQL, MongoDB, SQLite and memory, held to one contract.

Reference

API reference

Server, types, adapters, storage providers, auth providers, and REST endpoints.

Guide

Troubleshooting & FAQ

Symptoms, causes and fixes, and the questions that come up most.

Guide

Task system

Background work that runs in a conversation of its own.

Examples

Examples

A standalone server you can run, and snippets to copy.

Project

Release notes

What shipped, release by release.

---

What's new in 0.3.0

• Human in the loop. An agent can pause for a tool approval, a question or a tool that runs in the embedding page; the server stores the pause, expires it, checks who may answer, validates edited arguments and records how each request ended. Approvals & Questions
• Runs that outlive the connection. A turn is independent of the request that started it: closing the tab no longer stops it, POST /conversations/:id/cancel does, one turn runs at a time per conversation across server instances, and an event log plus a reattach stream bring a client back where it was. Runs, Cancel & Reattach
• Files the agent reads. Documents inline or in pages, images by reference, raw uploads, ownership, per-conversation limits and retention. Files
• Usage and budgets. Per-turn usage and cost, a spend limit per conversation, and a continue route. Usage & Budgets
• Host-backed agents. registerHostAgent serves an agent whose work runs in your backend: it streams, pauses and is cancelled like any other. Host-backed agents
• Chat experience. Regenerate, edit and resend, pin, rename, bulk delete, generated titles, starters, feedback with reasons and export. Chat experience
• Embeddable. Per-request bearer auth, client tools, rateLimit and audit hooks. Embedding & limits
• Storage held to one contract. Memory, SQLite, PostgreSQL and MongoDB pass one suite against real databases; GridFS for MongoDB files; a durable event log and leases. Storage Providers
• Safer defaults. Listing needs a user, JWT signatures are verified, files belong to their uploader and expire. Upgrading to 0.3.0

What it gives you

Agent SDK integration

Register agents created with @cognipeer/agent-sdk directly and expose them as REST APIs, with approvals, questions and files.

Your own backend as an agent

A host-backed agent streams, reports tool calls, pauses for approvals and is cancelled through a signal, while the work stays where it is.

Custom handler support

Integrate agents from any library with a simple handler interface, or point the server at a Chat Completions or Responses endpoint.

Durable runs

Turns outlive the connection, are stored when they finish, can be cancelled, and are recovered if the server dies.

Multiple storage backends

PostgreSQL, MongoDB, SQLite and in-memory providers with automatic schema upgrades, tested against one contract.

Authentication and identity

Token and JWT providers, or your own identity per request; conversations belong to their user.

SSE streaming

Real-time responses with Server-Sent Events, and a cursor to resume from.

Swagger UI

OpenAPI documentation of every route, with interactive Swagger UI.

Files

Upload, download, ownership and retention built in; the agent reads what people attach.

Budgets

Prices in, a cost per turn and a spend limit per conversation out.

Chat experience

Everything a chat product needs around a conversation, for every agent kind.

Framework agnostic

Express, Next.js, Fastify and plain Node, or your own adapter.

The REST surface

Method	Endpoint	Description
GET	/agents, /agents/:agentId	List agents; get an agent with its capabilities
GET / POST	/conversations	List / create conversations
GET / PATCH / DELETE	/conversations/:id	Get (a page of messages, runtime, pending actions), rename / pin / set the budget, delete
POST	/conversations/bulk-delete	Delete several conversations
GET / POST	/conversations/:id/messages	List or send messages (JSON or SSE)
POST	/conversations/:id/messages/:messageId/{regenerate,edit,feedback}	Run the newest answer again, edit and resend, rate an answer
POST	/conversations/:id/actions/:actionId	Answer a pending approval, question or client tool
POST	/conversations/:id/{cancel,continue}	Stop the running turn; carry on a turn the budget stopped
GET	/conversations/:id/events, .../events/stream	The event log, replayed and followed
GET	/conversations/:id/export	Download as Markdown, JSON, HTML or PDF
GET / DELETE	/conversations/:id/remembered-tools[/:tool]	List and forget tools the person chose not to be asked about again
POST / GET	/files, /conversations/:id/files	Upload a file; list a conversation's files
GET / DELETE	/files/:fileId, /files/:fileId/content	File metadata, download, delete
POST / GET	/tasks, /tasks/:taskId[/status|/result|/cancel|/comments]	Background tasks

See REST Endpoints for the complete reference with request and response examples.

Where to go next

• Getting started — install, register an agent, mount the middleware.
• Upgrading to 0.3.0 — what changes for an existing server.
• Storage providers — PostgreSQL, MongoDB, SQLite, and writing your own.
• Custom agents and Host-backed agents — wiring in an agent from outside the Agent SDK.
• Streaming — Server-Sent Events for real-time responses.
• Troubleshooting & FAQ — when something does not behave as described.