---
title: Agents
description: Agent management API endpoints.
---

# Agents API

Manage agent definitions including protocols and prompts.

## List Agents

Get all agents in the project.

```
GET /api/agents
```

### Response

```json
{
  "agents": [
    {
      "id": "cm5xvz7k80001abcd",
      "slug": "support-chat",
      "name": "Support Chat",
      "description": "Customer support agent",
      "format": "interactive",
      "createdAt": "2024-01-10T08:00:00Z",
      "updatedAt": "2024-01-15T10:00:00Z"
    }
  ]
}
```

### Example

```bash
curl https://octavus.ai/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Get Agent

Get a single agent by ID or slug.

```
GET /api/agents/:id
GET /api/agents/:slug?by=slug
```

### Response

```json
{
  "id": "cm5xvz7k80001abcd",
  "settings": {
    "slug": "support-chat",
    "name": "Support Chat",
    "description": "Customer support agent",
    "format": "interactive"
  },
  "protocol": "input:\n  COMPANY_NAME: { type: string }\n...",
  "prompts": [
    {
      "name": "system",
      "content": "You are a support agent for {{COMPANY_NAME}}..."
    },
    {
      "name": "user-message",
      "content": "{{USER_MESSAGE}}"
    }
  ]
}
```

### Example

```bash
# By ID
curl https://octavus.ai/api/agents/:agentId \
  -H "Authorization: Bearer YOUR_API_KEY"

# By slug
curl "https://octavus.ai/api/agents/:slug?by=slug" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Create Agent

Create a new agent.

```
POST /api/agents
```

### Request Body

```json
{
  "settings": {
    "slug": "support-chat",
    "name": "Support Chat",
    "description": "Customer support agent",
    "format": "interactive"
  },
  "protocol": "input:\n  COMPANY_NAME: { type: string }\n...",
  "prompts": [
    {
      "name": "system",
      "content": "You are a support agent..."
    }
  ]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `settings.slug` | string | Yes | URL-safe identifier |
| `settings.name` | string | Yes | Display name |
| `settings.description` | string | No | Agent description |
| `settings.format` | string | Yes | `interactive` or `generation` |
| `protocol` | string | Yes | YAML protocol definition |
| `prompts` | array | Yes | Prompt files |

### Response

```json
{
  "agentId": "cm5xvz7k80001abcd",
  "message": "Agent created successfully"
}
```

### Example

```bash
curl -X POST https://octavus.ai/api/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "slug": "my-agent",
      "name": "My Agent",
      "format": "interactive"
    },
    "protocol": "agent:\n  model: anthropic/claude-sonnet-4-5\n  system: system",
    "prompts": [
      { "name": "system", "content": "You are a helpful assistant." }
    ]
  }'
```

## Update Agent

Update an existing agent.

```
PATCH /api/agents/:id
PATCH /api/agents/:slug?by=slug
```

### Request Body

```json
{
  "protocol": "input:\n  COMPANY_NAME: { type: string }\n...",
  "prompts": [
    {
      "name": "system",
      "content": "Updated system prompt..."
    }
  ]
}
```

All fields are optional. Only provided fields are updated.

### Response

```json
{
  "agentId": "cm5xvz7k80001abcd",
  "message": "Agent updated successfully"
}
```

### Example

```bash
curl -X PATCH https://octavus.ai/api/agents/:agentId \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "agent:\n  model: anthropic/claude-sonnet-4-5\n  system: system\n  thinking: high"
  }'
```

## Sync Agent

The Server SDK provides a `sync` method that creates or updates an agent:

```typescript
const { agentId, created } = await client.agents.sync({
  settings: {
    slug: 'support-chat',
    name: 'Support Chat',
    format: 'interactive',
  },
  protocol: protocolYaml,
  prompts: [
    { name: 'system', content: systemPrompt },
  ],
});

if (created) {
  console.log('Created new agent:', agentId);
} else {
  console.log('Updated existing agent:', agentId);
}
```

This is useful for CI/CD pipelines to deploy agent updates.

