# Agents API

Agents are configurable AI entities with custom system prompts, model selection, capabilities, and tool access. They can be started, stopped, duplicated, and messaged directly. Agents are scoped to the authenticated user but can be shared via the isPublic flag. All endpoints require JWT authentication and are rate-limited to 100 requests per minute.

Base path: `/api/v2/agents`

---

## Agent CRUD

Create, retrieve, update, and delete agents. Ownership checks are enforced on update and delete operations. Public agents are readable by anyone.

### POST /api/v2/agents

Create a new AI agent with custom configuration.

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | Yes | Display name for the agent. |
| `description` | string | No | Brief description of purpose and capabilities. |
| `avatar` | string | No | URL to an avatar image. |
| `systemPrompt` | string | No | System prompt defining agent behavior and constraints. |
| `model` | string | No | AI model identifier (e.g. claude-sonnet, claude-haiku, claude-opus). |
| `temperature` | number | No | Sampling temperature (0.0 to 1.0). |
| `capabilities` | object | No | Capabilities configuration object. |
| `metadata` | object | No | Arbitrary metadata attached to the agent. |
| `tags` | string[] | No | Array of tags for categorization and filtering. |
| `workspaceId` | string | No | UUID of the workspace to scope this agent to. |
| `isPublic` | boolean | No | Whether the agent is visible to all users. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/agents \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Analyst",
    "description": "Analyzes datasets and produces reports with statistical insights.",
    "systemPrompt": "You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    "model": "claude-sonnet",
    "temperature": 0.3,
    "capabilities": {
      "code_interpreter": true,
      "file_analysis": true
    },
    "tags": ["analytics", "reporting"],
    "isPublic": false
  }'
```

**Response -- 201**

```json
{
  "success": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Data Analyst",
    "description": "Analyzes datasets and produces reports with statistical insights.",
    "avatar": null,
    "systemPrompt": "You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    "model": "claude-sonnet",
    "temperature": 0.3,
    "capabilities": { "code_interpreter": true, "file_analysis": true },
    "metadata": {},
    "tags": ["analytics", "reporting"],
    "status": "inactive",
    "isPublic": false,
    "user_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "created_at": "2026-03-19T16:00:00.000Z",
    "updated_at": "2026-03-19T16:00:00.000Z"
  }
}
```

---

### GET /api/v2/agents

List agents owned by the user. Supports search, filtering by status/tags, and pagination.

**Query Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `search` | string | No | Search term matched against name and description (ilike). |
| `workspaceId` | string | No | Filter by workspace UUID. |
| `status` | string | No | Filter by status: active, inactive, archived. |
| `tags` | string | No | Comma-separated tags to filter by (uses contains). |
| `includePublic` | boolean | No | Include public agents from other users. |
| `limit` | integer | No | Maximum agents to return. |
| `offset` | integer | No | Number of agents to skip. |

**Example Request**

```bash
curl -X GET "https://api.lvng.ai/api/v2/agents?search=analyst&status=active&limit=25" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response -- 200**

```json
{
  "success": true,
  "agents": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Data Analyst",
      "description": "Analyzes datasets and produces reports with statistical insights.",
      "model": "claude-sonnet",
      "status": "active",
      "capabilities": { "code_interpreter": true, "file_analysis": true },
      "tags": ["analytics", "reporting"],
      "isPublic": false,
      "created_at": "2026-03-19T16:00:00.000Z"
    }
  ],
  "total": 1,
  "limit": 25,
  "offset": 0
}
```

---

### GET /api/v2/agents/:id

Get full agent details. Returns if user is owner or agent is public.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent. |

**Example Request**

```bash
curl -X GET https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response -- 200**

```json
{
  "success": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Data Analyst",
    "description": "Analyzes datasets and produces reports with statistical insights.",
    "avatar": null,
    "systemPrompt": "You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    "model": "claude-sonnet",
    "temperature": 0.3,
    "capabilities": { "code_interpreter": true, "file_analysis": true },
    "metadata": {},
    "tags": ["analytics", "reporting"],
    "status": "active",
    "isPublic": false,
    "user_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "created_at": "2026-03-19T16:00:00.000Z",
    "updated_at": "2026-03-19T16:30:00.000Z"
  }
}
```

---

### PUT /api/v2/agents/:id

Update agent configuration. Requires ownership.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | No | Updated display name. |
| `description` | string | No | Updated description. |
| `avatar` | string | No | Updated avatar URL. |
| `systemPrompt` | string | No | Updated system prompt. |
| `model` | string | No | Updated model identifier. |
| `temperature` | number | No | Updated temperature. |
| `capabilities` | object | No | Updated capabilities. |
| `metadata` | object | No | Updated metadata. |
| `tags` | string[] | No | Updated tags. |
| `isPublic` | boolean | No | Updated visibility. |
| `status` | string | No | Updated status. |

**Example Request**

```bash
curl -X PUT https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Data Analyst",
    "description": "Advanced agent for data analysis with SQL access and visualization.",
    "tags": ["analytics", "reporting", "sql"]
  }'
```

**Response -- 200**

```json
{
  "success": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Senior Data Analyst",
    "description": "Advanced agent for data analysis with SQL access and visualization.",
    "model": "claude-sonnet",
    "temperature": 0.3,
    "capabilities": { "code_interpreter": true, "file_analysis": true },
    "tags": ["analytics", "reporting", "sql"],
    "status": "active",
    "isPublic": false,
    "updated_at": "2026-03-19T16:45:00.000Z"
  }
}
```

---

### DELETE /api/v2/agents/:id

Soft-delete an agent. Sets deleted_at and status='archived'. Requires ownership.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent to delete. |

**Example Request**

```bash
curl -X DELETE https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response -- 200**

```json
{
  "success": true,
  "message": "Agent deleted successfully"
}
```

---

## Agent Operations

Control agent lifecycle. Duplicate agents as templates, view usage statistics, and update capabilities independently of other configuration.

### POST /api/v2/agents/:id/duplicate

Create a copy of an existing agent with all configuration. Copy starts as inactive.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent to duplicate. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `name` | string | No | Name for the copy. Defaults to original name with "(Copy)" suffix. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/duplicate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data Analyst v2"
  }'
```

**Response -- 201**

```json
{
  "success": true,
  "agent": {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "name": "Data Analyst v2",
    "description": "Analyzes datasets and produces reports with statistical insights.",
    "systemPrompt": "You are a senior data analyst. Analyze data thoroughly and provide clear statistical insights.",
    "model": "claude-sonnet",
    "temperature": 0.3,
    "capabilities": { "code_interpreter": true, "file_analysis": true },
    "tags": ["analytics", "reporting"],
    "status": "inactive",
    "isPublic": false,
    "user_id": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
    "created_at": "2026-03-19T17:00:00.000Z",
    "updated_at": "2026-03-19T17:00:00.000Z"
  }
}
```

---

### GET /api/v2/agents/:id/stats

Get usage statistics for an agent over a time period.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent. |

**Query Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `period` | string | No | Time period: 7d, 30d, 90d. Defaults to 7d. |

**Example Request**

```bash
curl -X GET "https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/stats?period=30d" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response -- 200**

```json
{
  "success": true,
  "stats": {
    "conversations": 89,
    "tokens": { "input": 523400, "output": 198750 },
    "startDate": "2026-02-17T00:00:00.000Z",
    "endDate": "2026-03-19T17:00:00.000Z"
  }
}
```

---

### PUT /api/v2/agents/:id/capabilities

Update agent capabilities. Deep merges with existing capabilities object.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `capabilities` | object | Yes | Capabilities object. Deep merged with existing values. |

**Example Request**

```bash
curl -X PUT https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/capabilities \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": {
      "code_interpreter": true,
      "file_analysis": true,
      "web_search": true
    }
  }'
```

**Response -- 200**

```json
{
  "success": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Senior Data Analyst",
    "capabilities": { "code_interpreter": true, "file_analysis": true, "web_search": true },
    "updated_at": "2026-03-19T17:10:00.000Z"
  }
}
```

---

## Lifecycle Control

Start and stop agents. Active agents can process messages and execute tools. Inactive agents reject incoming requests.

### POST /api/v2/agents/:id/start

Start an agent. Sets status to 'active'.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/start \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response -- 200**

```json
{
  "success": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Senior Data Analyst",
    "status": "active",
    "updated_at": "2026-03-19T17:15:00.000Z"
  }
}
```

---

### POST /api/v2/agents/:id/stop

Stop an agent. Sets status to 'inactive'.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/stop \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

**Response -- 200**

```json
{
  "success": true,
  "agent": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Senior Data Analyst",
    "status": "inactive",
    "updated_at": "2026-03-19T17:20:00.000Z"
  }
}
```

---

## Agent Messaging

Send a message directly to an agent outside of a channel context. The agent loads its configuration, fetches conversation history, and calls the Claude API with its configured system prompt and tools.

### POST /api/v2/agents/:id/message

Send a message to an agent and receive a response. Loads agent config, fetches history, and calls Claude.

**Path Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | UUID of the agent. Agent must be active. |

**Body Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `message` | string | Yes | The message to send to the agent. |
| `context` | object | No | Additional context passed to the agent. Available in the system prompt and tool calls. |

**Example Request**

```bash
curl -X POST https://api.lvng.ai/api/v2/agents/550e8400-e29b-41d4-a716-446655440000/message \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What were the top 3 products by revenue last quarter?",
    "context": {
      "database": "analytics_prod",
      "time_range": "Q1_2026"
    }
  }'
```

**Response -- 200**

```json
{
  "success": true,
  "response": "Based on Q1 2026 revenue data, the top 3 products were:\n\n1. Enterprise Plan -- $1.8M (43% of total)\n2. Team Plan -- $1.2M (29% of total)\n3. API Access -- $780K (19% of total)\n\nEnterprise showed the strongest growth at 31% YoY.",
  "model": "claude-sonnet",
  "toolsUsed": ["query_database"],
  "usage": {
    "input_tokens": 856,
    "output_tokens": 423
  }
}
```