Agents API

Manage agent definitions including protocols and prompts.

Permissions

Endpoint	Method	Permission Required
`/api/agents`	GET	Agents OR Sessions
`/api/agents/:id`	GET	Agents OR Sessions
`/api/agents`	POST	Agents
`/api/agents/:id`	PATCH	Agents
`/api/agents/:id`	DELETE	Agents
`/api/agents/validate`	POST	Agents

Read endpoints work with either permission since both the CLI (for sync) and Server SDK (for sessions) need to read agent definitions.

List Agents

Get all agents in the project.

text

Response

json

Example

bash

Get Agent

Get a single agent by ID.

text

Response

json

Example

bash

Tip: You can also view and edit agents directly in the platform, or use the CLI (octavus list) for local workflows.

Create Agent

Create a new agent.

text

Request Body

json

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 `worker`
`protocol`	string	Yes	YAML protocol definition
`prompts`	array	Yes	Prompt files

Response

json

Example

bash

Update Agent

Update an existing agent.

text

Request Body

json

All fields are optional. Only provided fields are updated.

Response

json

Example

bash

Archive Agent

Archive an agent (soft delete). The agent is removed from the active agent list and its slug is freed for reuse. Session history is preserved.

text

Supports ?by=slug query parameter to look up by slug instead of ID.

Response

json

Example

bash

Creating and Managing Agents

There are two ways to manage agents:

Platform UI

Create and edit agents directly at octavus.ai. The web editor provides real-time validation and is the easiest way to get started. Copy the agent ID from the URL to use in your application.

CLI (Local Development)

For version-controlled agent definitions, use the Octavus CLI:

bash

This creates the agent if it doesn't exist, or updates it if it does. The CLI outputs the agent ID which you should store in an environment variable.

For CI/CD integration, see the CLI documentation.