Agent Server

Cognipeer Agent Server

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

• Package @cognipeer/agent-server
• Storage PostgreSQL · MongoDB
• Frameworks Express · Next.js · custom adapters

Register agents built with @cognipeer/agent-sdk directly, or bring an agent from any other library through a simple handler interface. Either way you get the same REST surface: conversations, messages, files, and streaming, backed by a storage provider that auto-migrates.

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,
  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

Architecture

How the server, storage, and framework adapters fit together.

Reference

API reference

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

Guide

Task system

Long-running work tracked alongside a conversation.

Examples

Examples

Working setups you can copy into a real project.

Project

Release notes

What shipped, release by release.

---

What it gives you

Agent SDK integration

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

Custom handler support

Integrate agents from any library with a simple handler interface.

Multiple storage backends

Built-in PostgreSQL and MongoDB providers with auto-migration support.

Authentication

Token-based and JWT authentication with customizable providers.

SSE streaming

Real-time response streaming with Server-Sent Events.

Swagger UI

Automatic OpenAPI documentation with interactive Swagger UI.

File management

Built-in file upload and download with storage integration.

Framework agnostic

Works with Express, Next.js, and other frameworks via adapters.

The REST surface

Method	Endpoint	Description
GET	/agents	List all agents
GET	/agents/:agentId	Get agent details
GET / POST	/conversations	List / create conversations
GET / PATCH / DELETE	/conversations/:id	Get, update, or delete a conversation
GET / POST	/conversations/:id/messages	List or send messages
POST	/files	Upload file
GET	/files/:fileId	Get file metadata
GET	/files/:fileId/content	Download file
DELETE	/files/:fileId	Delete file

See REST Endpoints for the complete reference.

Where to go next

• Getting started — install, register an agent, mount the middleware.
• Storage providers — PostgreSQL, MongoDB, and writing your own.
• Custom agents — wiring in an agent from outside the Agent SDK.
• Streaming — Server-Sent Events for real-time responses.