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
# Agent inputs (provided when creating a session)
input:
  COMPANY_NAME: { type: string }
  USER_ID: { type: string, optional: true }

# Persistent resources the agent can read/write
resources:
  CONVERSATION_SUMMARY:
    description: Summary for handoff
    default: ''

# How the agent can be invoked
triggers:
  user-message:
    input:
      USER_MESSAGE: { type: string }
  request-human:
    description: User clicks "Talk to Human"

# Temporary variables for execution (with types)
variables:
  SUMMARY:
    type: string
  TICKET:
    type: unknown

# Tools the agent can use
tools:
  get-user-account:
    description: Looking up your account
    parameters:
      userId: { type: string }

# MCP servers (remote services and device capabilities)
mcpServers:
  figma:
    description: Figma design tool integration
    source: remote
    display: description

# Octavus skills (provider-agnostic code execution)
skills:
  qr-code:
    display: description
    description: Generating QR codes

# Agent configuration (model, tools, etc.)
agent:
  model: anthropic/claude-sonnet-4-5
  system: system # References prompts/system.md
  tools: [get-user-account]
  mcpServers: [figma] # Enable MCP servers
  skills: [qr-code] # Enable skills
  imageModel: google/gemini-2.5-flash-image # Enable image generation
  webSearch: true # Enable web search
  todoList: true # Enable structured task tracking
  agentic: true # Allow multiple tool calls
  thinking: medium # Extended reasoning

# What happens when triggers fire
handlers:
  user-message:
    Add user message:
      block: add-message
      role: user
      prompt: user-message
      input: [USER_MESSAGE]

    Respond to user:
      block: next-message

File Structure

Each agent is a folder with:

text
my-agent/
├── protocol.yaml           # Main logic (required)
├── settings.json           # Agent metadata (required)
├── prompts/               # Prompt templates (supports subdirectories)
│   ├── system.md
│   ├── user-message.md
│   └── shared/
│       ├── company-info.md
│       └── formatting-rules.md
└── references/            # On-demand context documents (optional)
    └── api-guidelines.md

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
{
  "slug": "my-agent",
  "name": "My Agent",
  "description": "What this agent does",
  "format": "interactive"
}
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
<!-- prompts/system.md -->

You are a support agent for {{COMPANY_NAME}}.

Help users with their {{PRODUCT_NAME}} questions.

## Support Policies

{{SUPPORT_POLICIES}}

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
<!-- prompts/system.md -->

You are a customer support agent.

{{@shared/company-info.md}}

{{@shared/formatting-rules.md}}

Help users with their questions.

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