Protocol Overview

Agent protocols define how an AI agent behaves. They're written in YAML and specify inputs, triggers, tools, and execution handlers.

Why Protocols?

Protocols provide:

Declarative definition — Define behavior, not implementation
Portable agents — Move agents between projects
Versioning — Track changes with git
Validation — Catch errors before runtime
Visualization — Debug execution flows

Agent Formats

Octavus supports two agent formats:

Format	Use Case	Structure
`interactive`	Chat and multi-turn dialogue	`triggers` + `handlers` + `agent`
`worker`	Background tasks and pipelines	`steps` + `output`

Interactive agents handle conversations — they respond to triggers (like user messages) and maintain session state across interactions.

Worker agents execute tasks — they run steps sequentially and return an output value. Workers can be called independently or composed into interactive agents.

See Workers for the worker protocol reference.

Interactive Protocol Structure

yaml

File Structure

Each agent is a folder with:

text

settings.json

json

Field	Required	Description
`slug`	Yes	URL-safe identifier (lowercase, digits, dashes)
`name`	Yes	Human-readable name
`description`	No	Brief description
`format`	Yes	`interactive` (chat) or `worker` (background)

Naming Conventions

Slugs: lowercase-with-dashes
Variables: UPPERCASE_SNAKE_CASE
Prompts: lowercase-with-dashes.md
Tools: lowercase-with-dashes
Triggers: lowercase-with-dashes

Variables in Prompts

Reference variables with {{VARIABLE_NAME}}:

markdown

Variables are replaced with their values at runtime. If a variable is not provided, it's replaced with an empty string.

Next Steps

Input & Resources — Defining agent inputs
Triggers — How agents are invoked
Tools — External capabilities
Skills — Code execution and knowledge packages
Handlers — Execution blocks
Agent Config — Model and settings
Workers — Worker agent format
Provider Options — Provider-specific features
Types — Custom type definitions