### Install and Run AGEMS via CLI

Source: https://github.com/agems-ai/agems/blob/main/README.md

Instructions for setting up the AGEMS development environment from source. This process involves cloning the repository, installing dependencies, configuring environment variables, and running database migrations.

```bash
git clone https://github.com/agems-ai/agems.git
cd agems
pnpm install
cp .env.example .env
pnpm db:generate
pnpm db:push
pnpm dev
```

--------------------------------

### Connect to WebSocket Server and Handle Real-time Events (TypeScript)

Source: https://context7.com/agems-ai/agems/llms.txt

This snippet demonstrates how to connect to a Socket.io server, join specific rooms for messages and meetings, and listen for various real-time events such as new messages, agent execution status, and meeting entries. It utilizes the 'socket.io-client' library. The code includes examples for joining channels and meetings, and handling events like 'message:new', 'agent:execution:start', 'agent:tool:start', 'agent:tool:complete', 'agent:thinking:chunk', 'agent:text:chunk', 'agent:execution:done', 'meeting:entry:new', and 'meeting:agents:pending'. Finally, it shows how to disconnect from the server.

```typescript
import { io } from 'socket.io-client';

const socket = io('http://localhost:3001', {
  auth: { token: 'YOUR_JWT_TOKEN' },
});

// Join channel room for real-time messages
socket.emit('join:channel', { channelId: 'channel-uuid' });

// Listen for new messages
socket.on('message:new', (data) => {
  console.log('New message:', data.message);
  // { channelId, message: { id, senderType, senderId, content, createdAt } }
});

// Agent execution events
socket.on('agent:execution:start', (data) => {
  console.log(`Agent ${data.agentName} started executing`);
  // { channelId, agentId, agentName, executionId }
});

socket.on('agent:tool:start', (data) => {
  console.log(`Calling tool: ${data.toolName}`);
  // { channelId, agentId, executionId, toolName, toolInput }
});

socket.on('agent:tool:complete', (data) => {
  console.log(`Tool ${data.toolName} completed in ${data.durationMs}ms`);
  // { channelId, agentId, executionId, toolName, durationMs, error? }
});

socket.on('agent:thinking:chunk', (data) => {
  process.stdout.write(data.chunk); // Stream thinking output
});

socket.on('agent:text:chunk', (data) => {
  process.stdout.write(data.chunk); // Stream response text
});

socket.on('agent:execution:done', (data) => {
  console.log('Agent execution complete');
});

// Meeting events
socket.emit('join:meeting', { meetingId: 'meeting-uuid' });

socket.on('meeting:entry:new', (data) => {
  console.log(`${data.entry.speakerType}: ${data.entry.content}`);
});

socket.on('meeting:agents:pending', (data) => {
  console.log(`Waiting for ${data.count} agents to respond`);
});

// Cleanup
socket.disconnect();

```

--------------------------------

### GET /api/agents/{AGENT_ID}/builtin-tools

Source: https://context7.com/agems-ai/agems/llms.txt

Retrieves a list of all built-in tools currently available for a specific agent.

```APIDOC
## GET /api/agents/{AGENT_ID}/builtin-tools

### Description
Fetch the list of built-in tools configured for the specified agent.

### Method
GET

### Endpoint
/api/agents/{AGENT_ID}/builtin-tools

### Parameters
#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

### Response
#### Success Response (200)
- **tools** (array) - List of tool objects containing name, description, category, and enabled status.

#### Response Example
[
  { "name": "bash_command", "description": "Execute bash commands", "category": "System", "enabled": true }
]
```

--------------------------------

### Deploy AGEMS with Docker

Source: https://github.com/agems-ai/agems/blob/main/README.md

A quick-start method to deploy the entire AGEMS stack using Docker Compose. This command initializes the PostgreSQL database, Redis cache, API server, and web frontend containers.

```bash
docker compose up -d
```

--------------------------------

### Execute AI Agents with AgentRunner

Source: https://context7.com/agems-ai/agems/llms.txt

Demonstrates initializing the AgentRunner with tools, executing standard and multimodal prompts, handling streaming callbacks, and managing execution cancellation via AbortController.

```typescript
import { AgentRunner, type UserMessage, type ToolDefinition } from '@agems/ai';
import { z } from 'zod';

const tools: ToolDefinition[] = [
  {
    name: 'search_database',
    description: 'Search the product database',
    parameters: z.object({
      query: z.string().describe('Search query'),
      limit: z.number().optional().describe('Max results'),
    }),
    execute: async (params) => {
      return { results: [{ id: 1, name: 'Product A' }] };
    },
  },
];

const runner = new AgentRunner({
  provider: {
    provider: 'ANTHROPIC',
    model: 'claude-sonnet-4-20250514',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  systemPrompt: 'You are a helpful assistant with access to a product database.',
  tools,
  maxIterations: 50,
  maxTokens: 4096,
  temperature: 0.7,
  thinkingBudget: 4000,
});

const result = await runner.run('Find all products related to electronics');

const streamResult = await runner.run('Analyze sales data', undefined, {
  onThinkingChunk: (chunk) => process.stdout.write(`[Thinking] ${chunk}`),
  onTextChunk: (chunk) => process.stdout.write(chunk),
});

const controller = new AbortController();
const timedResult = await runner.run('Long running task', controller.signal);
```

--------------------------------

### Configure AI Providers

Source: https://context7.com/agems-ai/agems/llms.txt

Shows how to define configurations for various LLM providers using the AIProviderConfig interface and instantiate them via the createProvider factory.

```typescript
import { createProvider, type AIProviderConfig } from '@agems/ai';

const anthropicConfig: AIProviderConfig = {
  provider: 'ANTHROPIC',
  model: 'claude-sonnet-4-20250514',
  apiKey: process.env.ANTHROPIC_API_KEY,
};

const openaiConfig: AIProviderConfig = {
  provider: 'OPENAI',
  model: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
};

const ollamaConfig: AIProviderConfig = {
  provider: 'OLLAMA',
  model: 'llama3:latest',
  baseUrl: 'http://localhost:11434/v1',
};

const model = createProvider(anthropicConfig);
```

--------------------------------

### AGEMS Environment Configuration Variables

Source: https://context7.com/agems-ai/agems/llms.txt

This section lists the essential environment variables required to configure the AGEMS project. These variables cover database connection details (PostgreSQL with pgvector), Redis for queues and caching, JWT secret for authentication, API keys for various LLM providers (Anthropic, OpenAI, Google AI, Deepseek, Mistral), server ports, and an optional Telegram Bot token for integration.

```bash
# Database (PostgreSQL with pgvector)
DATABASE_URL="postgresql://user:password@localhost:5432/agems?schema=public"

# Redis for queues and caching
REDIS_URL="redis://localhost:6379"

# Authentication
JWT_SECRET="your-secure-jwt-secret-at-least-32-characters"

# LLM Provider API Keys (configure the ones you want to use)
ANTHROPIC_API_KEY="sk-ant-..."
OPENAI_API_KEY="sk-..."
GOOGLE_AI_API_KEY="AIza..."
DEEPSEEK_API_KEY="sk-..."
MISTRAL_API_KEY="..."

# Server ports (optional, defaults shown)
API_PORT=3001
WEB_PORT=3000

# Telegram Bot (optional, for Telegram integration)
TELEGRAM_BOT_TOKEN="123456:ABC..."

```

--------------------------------

### AI Provider Configuration

Source: https://context7.com/agems-ai/agems/llms.txt

Configure and create instances for various AI providers like Anthropic, OpenAI, Google Gemini, DeepSeek, Mistral, and Ollama.

```APIDOC
## AI Provider Configuration

### Description
The provider factory supports multiple LLM backends with a consistent interface, all utilizing the Vercel AI SDK.

### Method
`createProvider(config: AIProviderConfig): AIProvider`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **config** (AIProviderConfig) - Required - Configuration object for the AI provider.
  - **provider** (string) - Required - The name of the AI provider (e.g., 'ANTHROPIC', 'OPENAI', 'GOOGLE', 'DEEPSEEK', 'MISTRAL', 'OLLAMA', 'CUSTOM').
  - **model** (string) - Required - The specific model to use.
  - **apiKey** (string) - Required/Optional - The API key for the provider. Optional for some providers like Ollama if using default localhost.
  - **baseUrl** (string) - Optional - The base URL for the API endpoint. Used for custom or self-hosted providers.

### Request Example
```typescript
import { createProvider, type AIProviderConfig } from '@agems/ai';

// Anthropic Claude configuration
const anthropicConfig: AIProviderConfig = {
  provider: 'ANTHROPIC',
  model: 'claude-sonnet-4-20250514',
  apiKey: process.env.ANTHROPIC_API_KEY,
};

// OpenAI GPT configuration
const openaiConfig: AIProviderConfig = {
  provider: 'OPENAI',
  model: 'gpt-4o',
  apiKey: process.env.OPENAI_API_KEY,
};

// Google Gemini configuration
const googleConfig: AIProviderConfig = {
  provider: 'GOOGLE',
  model: 'gemini-2.0-flash',
  apiKey: process.env.GOOGLE_AI_API_KEY,
};

// DeepSeek configuration
const deepseekConfig: AIProviderConfig = {
  provider: 'DEEPSEEK',
  model: 'deepseek-chat',
  apiKey: process.env.DEEPSEEK_API_KEY,
  baseUrl: 'https://api.deepseek.com/v1',
};

// Mistral configuration
const mistralConfig: AIProviderConfig = {
  provider: 'MISTRAL',
  model: 'mistral-large-latest',
  apiKey: process.env.MISTRAL_API_KEY,
};

// Local Ollama configuration
const ollamaConfig: AIProviderConfig = {
  provider: 'OLLAMA',
  model: 'llama3:latest',
  baseUrl: 'http://localhost:11434/v1',
};

// Custom OpenAI-compatible endpoint configuration
const customConfig: AIProviderConfig = {
  provider: 'CUSTOM',
  model: 'my-model',
  apiKey: 'optional-key',
  baseUrl: 'https://my-llm-server.com/v1',
};

// Create a provider instance
const model = createProvider(anthropicConfig);
```

### Response
#### Success Response (200)
- **AIProvider** (object) - An instance of the configured AI provider.

#### Response Example
```typescript
// Example of using the created provider instance
const response = await model.chat.completions.create({
  messages: [{ role: 'user', content: 'Hello!' }],
});
console.log(response.choices[0].message.content);
```
```

--------------------------------

### Integrate External Tools (REST API)

Source: https://context7.com/agems-ai/agems/llms.txt

This section describes the Tools API, which facilitates integration with various external services such as REST APIs, databases, N8N workflows, SSH servers, DigitalOcean, and Firecrawl web scraping. Specific endpoints are not detailed in the provided text.

```bash
# Example placeholder for Tools API interaction
# curl -X POST http://localhost:3001/api/tools/some-tool \
#   -H "Authorization: Bearer YOUR_JWT_TOKEN" \
#   -H "Content-Type: application/json" \
#   -d '{ "action": "execute", "params": { ... } }'
```

--------------------------------

### Manage AI Agent Lifecycle

Source: https://context7.com/agems-ai/agems/llms.txt

APIs for creating, listing, updating, and controlling the state of AI agents. Includes endpoints for activating, pausing, and monitoring agent metrics and execution history.

```bash
# Create a new agent
curl -X POST http://localhost:3001/api/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "slug": "research-assistant",
    "type": "AUTONOMOUS",
    "llmProvider": "ANTHROPIC",
    "llmModel": "claude-sonnet-4-20250514",
    "systemPrompt": "You are a research assistant that helps find and summarize information.",
    "mission": "Help users conduct research efficiently"
  }'

# List all agents with optional filters
curl -X GET "http://localhost:3001/api/agents?status=ACTIVE" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Update agent configuration
curl -X PATCH http://localhost:3001/api/agents/AGENT_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "llmModel": "claude-opus-4-20250514",
    "systemPrompt": "Updated system prompt with new instructions..."
  }'

# Activate an agent
curl -X POST http://localhost:3001/api/agents/AGENT_ID/activate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Pause an agent
curl -X POST http://localhost:3001/api/agents/AGENT_ID/pause \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Manage Skills via REST API

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints to create, list, assign, import, and export reusable knowledge modules (skills) for agents.

```bash
curl -X POST http://localhost:3001/api/skills -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"name": "SQL Expert", "slug": "sql-expert", "description": "Advanced SQL query writing and optimization knowledge", "type": "CUSTOM", "version": "1.0.0", "entryPoint": "main", "content": "You are an expert in SQL..."}'

curl -X GET http://localhost:3001/api/skills -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X POST http://localhost:3001/api/agents/AGENT_ID/skills -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"skillId": "skill-uuid", "config": { "level": "advanced" }}'

curl -X GET http://localhost:3001/api/skills/export -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X POST http://localhost:3001/api/skills/import -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{ "skills": [...] }'
```

--------------------------------

### Environment Configuration

Source: https://context7.com/agems-ai/agems/llms.txt

Configure AGEMS through environment variables for database, Redis, authentication, and LLM providers.

```APIDOC
## Environment Configuration

Configure AGEMS through environment variables for database, Redis, authentication, and LLM providers.

### Database
- `DATABASE_URL` (string) - PostgreSQL connection URL (e.g., `postgresql://user:password@localhost:5432/agems?schema=public`).

### Redis
- `REDIS_URL` (string) - Redis connection URL (e.g., `redis://localhost:6379`). Used for queues and caching.

### Authentication
- `JWT_SECRET` (string) - A secure JWT secret, at least 32 characters long.

### LLM Provider API Keys
- `ANTHROPIC_API_KEY` (string) - API key for Anthropic.
- `OPENAI_API_KEY` (string) - API key for OpenAI.
- `GOOGLE_AI_API_KEY` (string) - API key for Google AI.
- `DEEPSEEK_API_KEY` (string) - API key for Deepseek.
- `MISTRAL_API_KEY` (string) - API key for Mistral.

### Server Ports
- `API_PORT` (number) - Port for the API server (defaults to 3001).
- `WEB_PORT` (number) - Port for the web server (defaults to 3000).

### Telegram Integration (Optional)
- `TELEGRAM_BOT_TOKEN` (string) - Token for the Telegram bot.
```

--------------------------------

### Manage Organization Structure and Members via REST API

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints for managing multi-tenant organization details, member invitations, role assignments, and organizational tree hierarchies.

```bash
# Get organization members
curl -X GET http://localhost:3001/api/org/members \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Invite new member
curl -X POST http://localhost:3001/api/org/members/invite \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "newuser@company.com", "role": "MEMBER" }'

# Create organizational position
curl -X POST http://localhost:3001/api/org/positions \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Head of Marketing",
    "department": "Marketing",
    "holderType": "AGENT"
  }'
```

--------------------------------

### Tools API

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints for creating, listing, and managing tool connections for agents.

```APIDOC
## POST /api/tools

### Description
Creates a new tool (REST API or Database) for use by agents.

### Method
POST

### Endpoint
/api/tools

### Request Body
- **name** (string) - Required - Name of the tool
- **type** (string) - Required - Type of tool (REST_API, DATABASE)
- **config** (object) - Required - Connection configuration
- **authType** (string) - Optional - Authentication method
- **authConfig** (object) - Required - Credentials

### Response
#### Success Response (200)
- **id** (string) - The created tool ID
```

```APIDOC
## POST /api/agents/{AGENT_ID}/tools

### Description
Assigns a specific tool to an agent with defined access permissions.

### Method
POST

### Endpoint
/api/agents/{AGENT_ID}/tools

### Parameters
#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent

### Request Body
- **toolId** (string) - Required - ID of the tool to assign
- **permissions** (object) - Required - Access levels (read, write, execute)
```

--------------------------------

### Authenticate Users and Manage Organizations

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints for user registration, login, profile retrieval, and organization switching. These operations utilize JWT tokens for secure access to platform resources.

```bash
# Register a new user and organization
curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@company.com",
    "password": "securePassword123",
    "name": "John Admin",
    "orgName": "My Company"
  }'

# Login to existing account
curl -X POST http://localhost:3001/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@company.com",
    "password": "securePassword123"
  }'

# Get current user profile (requires JWT)
curl -X GET http://localhost:3001/api/auth/profile \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Switch to different organization
curl -X POST http://localhost:3001/api/auth/switch-org \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "orgId": "org-uuid-here" }'
```

--------------------------------

### AgentRunner - AI Execution Engine

Source: https://context7.com/agems-ai/agems/llms.txt

The AgentRunner class handles LLM execution with multi-provider support, tool calling loops, loop detection, and streaming capabilities.

```APIDOC
## AgentRunner - AI Execution Engine

### Description
The AgentRunner class in `@agems/ai` package handles LLM execution with multi-provider support, tool calling loops, loop detection, and streaming capabilities.

### Method
`run(messages: UserMessage | UserMessage[], abortSignal?: AbortSignal, streamCallbacks?: StreamCallbacks)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **messages** (UserMessage | UserMessage[]) - Required - The user's message(s) or conversation history.
- **abortSignal** (AbortSignal) - Optional - An AbortSignal to cancel the execution.
- **streamCallbacks** (StreamCallbacks) - Optional - Callbacks for handling streaming responses.
  - **onThinkingChunk** (function) - Callback for thinking process chunks.
  - **onTextChunk** (function) - Callback for text response chunks.

### Request Example
```typescript
import { AgentRunner, type UserMessage, type ToolDefinition } from '@agems/ai';
import { z } from 'zod';

const tools: ToolDefinition[] = [
  {
    name: 'search_database',
    description: 'Search the product database',
    parameters: z.object({
      query: z.string().describe('Search query'),
      limit: z.number().optional().describe('Max results'),
    }),
    execute: async (params) => {
      return { results: [{ id: 1, name: 'Product A' }] };
    },
  },
];

const runner = new AgentRunner({
  provider: {
    provider: 'ANTHROPIC',
    model: 'claude-sonnet-4-20250514',
    apiKey: process.env.ANTHROPIC_API_KEY,
  },
  systemPrompt: 'You are a helpful assistant with access to a product database.',
  tools,
  maxIterations: 50,
  maxTokens: 4096,
  temperature: 0.7,
  thinkingBudget: 4000,
});

// Simple execution
const result = await runner.run('Find all products related to electronics');
console.log(result.text);

// Multimodal execution
const messages: UserMessage[] = [
  { role: 'user', content: 'What products do you have?' },
  { role: 'assistant', content: 'I can search our database. What are you looking for?' },
  {
    role: 'user',
    content: [
      { type: 'text', text: 'Find products similar to this:' },
      { type: 'image', image: imageBuffer, mimeType: 'image/png' },
    ],
  },
];
const multimodalResult = await runner.run(messages);

// Streaming execution
const streamResult = await runner.run('Analyze sales data', undefined, {
  onThinkingChunk: (chunk) => process.stdout.write(`[Thinking] ${chunk}`),
  onTextChunk: (chunk) => process.stdout.write(chunk),
});

// With abort signal
const controller = new AbortController();
setTimeout(() => controller.abort(), 30000);
const timedResult = await runner.run('Long running task', controller.signal);
```

### Response
#### Success Response (200)
- **text** (string) - The final text response from the LLM.
- **tokensUsed** (object) - An object containing input and output token counts.
  - **input** (number) - Number of input tokens.
  - **output** (number) - Number of output tokens.
- **toolCalls** (array) - An array of tool calls made by the LLM.
- **loopDetected** (boolean) - Indicates if a loop was detected during execution.

#### Response Example
```json
{
  "text": "The product you are looking for is Product A.",
  "tokensUsed": {
    "input": 150,
    "output": 30
  },
  "toolCalls": [
    {
      "name": "search_database",
      "arguments": {
        "query": "electronics"
      }
    }
  ],
  "loopDetected": false
}
```
```

--------------------------------

### Manage Tasks (REST API)

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints for creating, listing, retrieving, updating, and managing tasks. Supports one-time, recurring, and continuous tasks with assignment, subtask decomposition, and status tracking. Requires JWT for authorization.

```bash
# Create a new task
curl -X POST http://localhost:3001/api/tasks \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "title": "Generate weekly analytics report", \
    "description": "Analyze user engagement metrics and create a summary report", \
    "type": "RECURRING", \
    "cronExpression": "0 9 * * 1", \
    "priority": "HIGH", \
    "assigneeType": "AGENT", \
    "assigneeId": "agent-uuid" \
  }'

# List all tasks with filters
curl -X GET "http://localhost:3001/api/tasks?status=IN_PROGRESS&assigneeId=agent-uuid" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get task details with comments and subtasks
curl -X GET http://localhost:3001/api/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Update task status
curl -X PATCH http://localhost:3001/api/tasks/TASK_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "status": "IN_PROGRESS", \
    "result": { "progress": 50, "notes": "Halfway complete" } \
  }'

# Assign task to different agent/human
curl -X POST http://localhost:3001/api/tasks/TASK_ID/assign \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "assigneeType": "AGENT", "assigneeId": "another-agent-uuid" }'

# Add comment to task
curl -X POST http://localhost:3001/api/tasks/TASK_ID/comments \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "content": "Started processing the data, will update when complete" }'

# Get task comments
curl -X GET http://localhost:3001/api/tasks/TASK_ID/comments \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Decompose task into subtasks (AI-powered)
curl -X POST http://localhost:3001/api/tasks/TASK_ID/decompose \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Authentication API

Source: https://context7.com/agems-ai/agems/llms.txt

Handles user registration, login, profile management, and organization switching using JWT-based authentication.

```APIDOC
## Authentication API

### Description
The authentication system provides JWT-based authentication with support for multi-organization membership. Users can register, login, view their profile, and switch between organizations they belong to.

### Register a new user and organization

#### Method
POST

#### Endpoint
`/api/auth/register`

#### Request Body
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password.
- **name** (string) - Required - User's full name.
- **orgName** (string) - Required - Name of the new organization.

#### Request Example
```json
{
  "email": "admin@company.com",
  "password": "securePassword123",
  "name": "John Admin",
  "orgName": "My Company"
}
```

#### Success Response (201)
- **access_token** (string) - JWT token for authentication.
- **user** (object) - User details.
  - **id** (string) - User's unique identifier.
  - **email** (string) - User's email address.
  - **name** (string) - User's full name.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "admin@company.com",
    "name": "John Admin"
  }
}
```

### Login to existing account

#### Method
POST

#### Endpoint
`/api/auth/login`

#### Request Body
- **email** (string) - Required - User's email address.
- **password** (string) - Required - User's password.

#### Request Example
```json
{
  "email": "admin@company.com",
  "password": "securePassword123"
}
```

#### Success Response (200)
- **access_token** (string) - JWT token for authentication.
- **user** (object) - User details.
- **organizations** (array) - List of organizations the user belongs to.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "user": { ... },
  "organizations": [
    { ... }
  ]
}
```

### Get current user profile

#### Method
GET

#### Endpoint
`/api/auth/profile`

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).

#### Success Response (200)
- Returns the current user's profile information.

### Switch to different organization

#### Method
POST

#### Endpoint
`/api/auth/switch-org`

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).
- **Content-Type** (string) - Required - `application/json`.

#### Request Body
- **orgId** (string) - Required - The ID of the organization to switch to.

#### Request Example
```json
{
  "orgId": "org-uuid-here"
}
```

#### Success Response (200)
- Returns a confirmation of the organization switch, potentially including a new JWT if applicable.
```

--------------------------------

### Manage Approval Requests and Policies via REST API

Source: https://context7.com/agems-ai/agems/llms.txt

Provides endpoints to list, approve, or reject pending human-in-the-loop requests. It also allows for configuring agent-specific approval policies and applying predefined presets.

```bash
# Get pending approvals
curl -X GET "http://localhost:3001/api/approvals?status=PENDING" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Approve a request
curl -X POST http://localhost:3001/api/approvals/APPROVAL_ID/approve \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Set agent approval policy
curl -X PUT http://localhost:3001/api/approvals/policies/AGENT_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "preset": "SUPERVISED",
    "writeMode": "REQUIRES_APPROVAL",
    "executeMode": "FREE",
    "toolOverrides": { "db_execute_production": "BLOCKED" }
  }'
```

--------------------------------

### Manage Agent Tools via REST API

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints for creating, listing, testing, and assigning tools to agents. Requires a valid JWT token for authorization.

```bash
curl -X POST http://localhost:3001/api/tools -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"name": "GitHub API", "type": "REST_API", "config": {"url": "https://api.github.com", "description": "GitHub REST API for repository management"}, "authType": "BEARER_TOKEN", "authConfig": { "token": "ghp_your_github_token" }}'

curl -X GET http://localhost:3001/api/tools -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X POST http://localhost:3001/api/agents/AGENT_ID/tools -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"toolId": "tool-uuid", "permissions": { "read": true, "write": false, "execute": true }}'

curl -X POST http://localhost:3001/api/tools/TOOL_ID/test -H "Authorization: Bearer YOUR_JWT_TOKEN"

curl -X DELETE http://localhost:3001/api/agents/AGENT_ID/tools/TOOL_ID -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Manage Communication Channels (REST API)

Source: https://context7.com/agems-ai/agems/llms.txt

API for creating, listing, retrieving, and managing messages within communication channels. Supports direct messages, group chats, and broadcasts. Requires JWT for authorization and JSON payloads for requests.

```bash
# Create a new channel
curl -X POST http://localhost:3001/api/channels \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "name": "Project Alpha Discussion", \
    "type": "GROUP", \
    "participantIds": [ \
      { "type": "HUMAN", "id": "user-uuid" }, \
      { "type": "AGENT", "id": "agent-uuid" } \
    ] \
  }'

# List all channels for current user
curl -X GET http://localhost:3001/api/channels \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Get channel details
curl -X GET http://localhost:3001/api/channels/CHANNEL_ID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Send a message to channel
curl -X POST http://localhost:3001/api/channels/CHANNEL_ID/messages \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ \
    "content": "Hello team, can you analyze this data?", \
    "contentType": "TEXT" \
  }'

# Get messages from channel
curl -X GET "http://localhost:3001/api/channels/CHANNEL_ID/messages?limit=50" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Upload file to channel
curl -X POST http://localhost:3001/api/channels/CHANNEL_ID/upload \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@/path/to/document.pdf"
# Response: { "url": "/uploads/uuid.pdf", "filename": "uuid.pdf", "originalName": "document.pdf", "size": 12345 }

# Find or create direct channel with agent
curl -X GET "http://localhost:3001/api/channels/direct/AGENT/agent-uuid" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

# Add participant to channel
curl -X POST http://localhost:3001/api/channels/CHANNEL_ID/participants \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "participantType": "AGENT", "participantId": "agent-uuid", "role": "MEMBER" }'
```

--------------------------------

### Manage Meetings via REST API

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints to facilitate multi-party discussions, including scheduling, real-time entry management, voting, and protocol generation.

```bash
curl -X POST http://localhost:3001/api/meetings -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"title": "Q4 Planning Session", "agenda": "1. Review Q3 results\n2. Set Q4 goals\n3. Assign responsibilities", "scheduledAt": "2025-01-15T14:00:00Z", "participants": [{ "id": "agent-uuid-1", "type": "AGENT", "role": "MEMBER" }]}'

curl -X POST http://localhost:3001/api/meetings/MEETING_ID/entries -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"content": "What are your thoughts?", "entryType": "SPEECH"}'

curl -X POST http://localhost:3001/api/meetings/MEETING_ID/vote/cast -H "Authorization: Bearer YOUR_JWT_TOKEN" -H "Content-Type: application/json" -d '{"decisionId": "decision-uuid", "vote": "FOR"}'

curl -X GET http://localhost:3001/api/meetings/MEETING_ID/protocol -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### POST /api/tasks

Source: https://context7.com/agems-ai/agems/llms.txt

Creates a new task assigned to an agent or human, supporting recurring schedules.

```APIDOC
## POST /api/tasks

### Description
Creates a task that can be one-time, recurring, or continuous.

### Method
POST

### Endpoint
/api/tasks

### Parameters
#### Request Body
- **title** (string) - Required - Task title.
- **description** (string) - Optional - Detailed task description.
- **type** (string) - Required - Task type (ONE_TIME, RECURRING).
- **cronExpression** (string) - Optional - Required if type is RECURRING.
- **assigneeId** (string) - Required - ID of the assigned agent or human.

### Request Example
{
  "title": "Generate weekly analytics report",
  "type": "RECURRING",
  "cronExpression": "0 9 * * 1",
  "assigneeId": "agent-uuid"
}
```

--------------------------------

### POST /api/channels

Source: https://context7.com/agems-ai/agems/llms.txt

Creates a new communication channel for direct or group messaging.

```APIDOC
## POST /api/channels

### Description
Initializes a new communication channel for collaboration.

### Method
POST

### Endpoint
/api/channels

### Parameters
#### Request Body
- **name** (string) - Required - Name of the channel.
- **type** (string) - Required - Type of channel (e.g., GROUP, DIRECT).
- **participantIds** (array) - Required - List of participants with type and ID.

### Request Example
{
  "name": "Project Alpha Discussion",
  "type": "GROUP",
  "participantIds": [
    { "type": "HUMAN", "id": "user-uuid" },
    { "type": "AGENT", "id": "agent-uuid" }
  ]
}
```

--------------------------------

### Skills API

Source: https://context7.com/agems-ai/agems/llms.txt

Endpoints for managing reusable knowledge modules assigned to agents.

```APIDOC
## POST /api/skills

### Description
Registers a new skill module for agent usage.

### Method
POST

### Endpoint
/api/skills

### Request Body
- **name** (string) - Required - Skill name
- **slug** (string) - Required - Unique identifier slug
- **content** (string) - Required - The knowledge content or instructions

### Response
#### Success Response (200)
- **id** (string) - The created skill ID
```

--------------------------------

### Agents API

Source: https://context7.com/agems-ai/agems/llms.txt

Provides endpoints for managing the lifecycle of AI agents, including creation, configuration, activation, and retrieval of execution history and metrics.

```APIDOC
## Agents API

### Description
The agents API enables full lifecycle management of AI agents including creation, configuration, activation, and execution. Each agent has configurable LLM settings, system prompts, tools, skills, and can be organized in hierarchies.

### Create a new agent

#### Method
POST

#### Endpoint
`/api/agents`

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).
- **Content-Type** (string) - Required - `application/json`.

#### Request Body
- **name** (string) - Required - The name of the agent.
- **slug** (string) - Required - A unique slug for the agent.
- **type** (string) - Required - The type of agent (e.g., `AUTONOMOUS`).
- **llmProvider** (string) - Required - The LLM provider to use (e.g., `ANTHROPIC`).
- **llmModel** (string) - Required - The specific LLM model to use.
- **systemPrompt** (string) - Required - The system prompt for the agent.
- **mission** (string) - Optional - The primary mission or goal of the agent.

#### Request Example
```json
{
  "name": "Research Assistant",
  "slug": "research-assistant",
  "type": "AUTONOMOUS",
  "llmProvider": "ANTHROPIC",
  "llmModel": "claude-sonnet-4-20250514",
  "systemPrompt": "You are a research assistant that helps find and summarize information.",
  "mission": "Help users conduct research efficiently"
}
```

#### Success Response (201)
- Returns the created agent object with its assigned ID.

### List all agents

#### Method
GET

#### Endpoint
`/api/agents`

#### Query Parameters
- **status** (string) - Optional - Filter agents by their status (e.g., `ACTIVE`).

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).

#### Success Response (200)
- **agents** (array) - A list of agent objects.
  - **id** (string) - Agent's unique identifier.
  - **name** (string) - Agent's name.
  - **status** (string) - Agent's current status.
  - **llmProvider** (string) - The LLM provider being used.
  - ... (other agent properties)

#### Response Example
```json
[
  {
    "id": "agent-uuid",
    "name": "Research Assistant",
    "status": "ACTIVE",
    "llmProvider": "ANTHROPIC",
    ...
  }
]
```

### Get agent details

#### Method
GET

#### Endpoint
`/api/agents/{AGENT_ID}`

#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).

#### Success Response (200)
- Returns the detailed object for the specified agent.

### Update agent configuration

#### Method
PATCH

#### Endpoint
`/api/agents/{AGENT_ID}`

#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).
- **Content-Type** (string) - Required - `application/json`.

#### Request Body
- **llmModel** (string) - Optional - The new LLM model to use.
- **systemPrompt** (string) - Optional - The updated system prompt.
- ... (other updatable agent fields)

#### Request Example
```json
{
  "llmModel": "claude-opus-4-20250514",
  "systemPrompt": "Updated system prompt with new instructions..."
}
```

#### Success Response (200)
- Returns the updated agent object.

### Activate an agent

#### Method
POST

#### Endpoint
`/api/agents/{AGENT_ID}/activate`

#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).

#### Success Response (200)
- Returns a confirmation or the updated agent status.

### Pause an agent

#### Method
POST

#### Endpoint
`/api/agents/{AGENT_ID}/pause`

#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).

#### Success Response (200)
- Returns a confirmation or the updated agent status.

### Get agent execution history

#### Method
GET

#### Endpoint
`/api/agents/{AGENT_ID}/executions`

#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

#### Query Parameters
- **limit** (integer) - Optional - Maximum number of execution records to return.

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).

#### Success Response (200)
- **executions** (array) - A list of past agent execution records.
  - **limit** (integer) - The number of executions returned.
  - ... (details of each execution)

#### Response Example
```json
{
  "executions": [
    { ... },
    { ... }
  ]
}
```

### Get agent metrics

#### Method
GET

#### Endpoint
`/api/agents/{AGENT_ID}/metrics`

#### Path Parameters
- **AGENT_ID** (string) - Required - The unique identifier of the agent.

#### Headers
- **Authorization** (string) - Required - Bearer token (e.g., `Bearer YOUR_JWT_TOKEN`).

#### Success Response (200)
- Returns an object containing various metrics for the agent (e.g., token usage, execution times).
```