AgentOS

Deploy AI agents as production web services

AgentOS deploys agents, teams, and flows as production-ready HTTP APIs with built-in health checks, CORS, and Express integration.

AgentOS replaces AgentApp as the recommended class name. The old name still works as a silent alias.

Quick Start

1. Install

   npm install praisonai express
   
2. Create Server

   import { AgentOS, Agent } from 'praisonai';
   
   const agent = new Agent({
     name: 'assistant',
     instructions: 'You are a helpful assistant'
   });
   
   const app = new AgentOS({
     name: 'My AI App',
     agents: [agent]
   });
   
   await app.serve({ port: 8000 });
   
3. Test

   curl -X POST http://localhost:8000/api/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "Hello!"}'
   

---

How It Works

Step	Description
1	Client sends HTTP request to AgentOS endpoint
2	AgentOS routes to the appropriate agent
3	Agent processes the message and returns a response
4	AgentOS formats and returns the response as JSON

---

Configuration Options

import { AgentOS, Agent } from 'praisonai';

const app = new AgentOS({
  name: 'My AI App',
  agents: [agent],
  teams: [team],      // Optional: AgentTeam instances
  flows: [flow],      // Optional: AgentFlow instances
  config: {
    host: '0.0.0.0',
    port: 8000,
    corsOrigins: ['*'],
    apiPrefix: '/api',
    debug: false,
    timeout: 60
  }
});

Option	Type	Default	Description
name	string	"PraisonAI App"	Application name
agents	Agent[]	[]	Agents to serve
teams	AgentTeam[]	[]	Teams to serve
flows	AgentFlow[]	[]	Flows to serve
config.host	string	"0.0.0.0"	Server host
config.port	number	8000	Server port
config.corsOrigins	string[]	["*"]	Allowed CORS origins
config.apiPrefix	string	"/api"	API route prefix
config.debug	boolean	false	Enable debug mode
config.timeout	number	60	Request timeout (seconds)

---

API Endpoints

Endpoint	Method	Description
/	GET	App info (name, status, agent count)
/health	GET	Health check ({ status: 'healthy' })
/api/agents	GET	List available agents
/api/chat	POST	Chat with an agent
/api/teams	GET	List available teams
/api/flows	GET	List available flows

Chat Request

curl -X POST http://localhost:8000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello!",
    "agent_name": "assistant",
    "session_id": "user-123"
  }'

Chat Response

{
  "response": "Hello! How can I help you today?",
  "agent_name": "assistant",
  "session_id": "user-123"
}

---

Common Patterns

Single Agent

import { AgentOS, Agent } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant'
});

const app = new AgentOS({ agents: [agent] });
await app.serve();

Multi-Agent

import { AgentOS, Agent } from 'praisonai';

const researcher = new Agent({ 
  name: 'researcher',
  instructions: 'Research topics' 
});
const writer = new Agent({ 
  name: 'writer',
  instructions: 'Write content' 
});

const app = new AgentOS({
  agents: [researcher, writer],
  name: 'content-team'
});
await app.serve();

With Teams

import { AgentOS, Agent, AgentTeam } from 'praisonai';

const agent = new Agent({
  instructions: 'You are a helpful assistant'
});

const team = new AgentTeam({
  agents: [agent],
  process: 'sequential'
});

const app = new AgentOS({
  agents: [agent],
  teams: [team]
});
await app.serve();

Custom API Prefix

const app = new AgentOS({
  agents: [agent],
  config: {
    apiPrefix: '/v1'
  }
});

// Endpoints now at /v1/chat, /v1/agents, etc.

---

Best Practices

Use environment variables for port

Read port from environment for deployment flexibility.

await app.serve({
  port: parseInt(process.env.PORT || '8000')
});

Configure CORS for production

Restrict CORS origins in production instead of using ’*’.

config: {
  corsOrigins: ['https://yourdomain.com']
}

Stop server gracefully

Use the stop() method for clean shutdown.

process.on('SIGTERM', async () => {
  await app.stop();
  process.exit(0);
});

---

Backward Compatibility

AgentApp works as a silent alias with no deprecation warnings.

// Both are equivalent
import { AgentOS, AgentApp } from 'praisonai';

const app1 = new AgentOS({ agents: [agent] });
const app2 = new AgentApp({ agents: [agent] });

// They are the same class
console.log(AgentOS === AgentApp); // true

Additional config aliases:

• managers → teams (deprecated)
• workflows → flows (deprecated)

---

Related

Agent

Single agent documentation

AgentTeam

Multi-agent orchestration

AgentFlow

Step-based workflows

Server Adapters

Express, Hono, Next.js adapters