Skip to main content
Octavus Docs

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:

FormatUse CaseStructure
interactiveChat and multi-turn dialoguetriggers + handlers + agent
workerBackground tasks and pipelinessteps + 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

Prompts can be organized in subdirectories. In the protocol, reference nested prompts by their path relative to prompts/ (without .md): shared/company-info.

References are markdown files with YAML frontmatter that the agent can fetch on demand during execution. See References.

settings.json

json
FieldRequiredDescription
slugYesURL-safe identifier (lowercase, digits, dashes)
nameYesHuman-readable name
descriptionNoBrief description
formatYesinteractive (chat) or worker (background)

Naming Conventions

  • Slugs: lowercase-with-dashes
  • Variables: UPPERCASE_SNAKE_CASE
  • Prompts: lowercase-with-dashes.md (paths use / for subdirectories)
  • 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, the placeholder is kept as-is.

Prompt Interpolation

Include other prompts inside a prompt with {{@path.md}}:

markdown

The referenced prompt content is inserted before variable interpolation, so variables in included prompts work the same way. Circular references are not allowed and will be caught during validation.

Next Steps