Agent Runtime

The agent runtime is the execution engine at the heart of Octipus. It manages the lifecycle of autonomous agents that follow a Thought-Action-Observation loop to accomplish tasks.

Architecture Overview

The runtime consists of three main classes arranged in an inheritance hierarchy:

BaseAgentWorker (abstract)
├── AgentWorker          — LLM-based agent (OpenAI SDK / LiteLLM)
└── CLIAgentWorker       — CLI tool agent (six registered configurations)

BaseAgentWorker

The abstract base class that defines the agent lifecycle:

• Event emission: Publishes thought, action, observation, error, and status events
• Iteration loop: Runs the think-act-observe cycle up to AGENT_MAX_ITERATIONS times
• Token budget: Tracks cumulative token usage and checks usage against configured limits between execution steps; external requests can overshoot
• Timeout enforcement: Checks wall-clock time before each LLM call
• Status management: Tracks agent state (running, paused, completed, failed, stopped)

AgentWorker

Extends BaseAgentWorker for standard LLM providers (Ollama, OpenAI, Anthropic, Gemini, and LiteLLM):

• Sends messages with tool definitions using the OpenAI SDK format
• Parses tool call responses and routes them to the ToolExecutor
• Handles context compaction when the conversation exceeds token limits
• Supports metadata.extraBody for per-model custom parameters

CLIAgentWorker

Extends BaseAgentWorker for vendor CLI tools:

• Runs Claude Code, Antigravity, Codex, and Mistral Vibe, plus GLM and Kimi configurations that reuse Claude Code; see CLI Providers
• Uses CLI-specific adapters to build arguments and parse output
• Falls back to the default LLM model if the CLI tool fails (process error, vendor-side rejection, crash)

Caution

Billing, plan entitlements, and harness/scripting access for any CLI provider are vendor-managed and change over time. Octipus launches the configured binary and injects vendor credentials for the GLM/Kimi configurations; consult your vendor account for billing and access.

Structured Expert Prompts

Each expert (preset) now has a structured system prompt that goes beyond a simple role description. When an agent is spawned, the system injects three additional prompt sections:

Critical Rules

Prompt guidance the agent is asked to follow; hard constraints require runtime enforcement. These are framed as non-negotiable directives specific to the expert’s domain. For example, a Security Analyst expert might include rules like “Never recommend disabling authentication” or “Always verify TLS certificates.”

Deliverable Templates

Standardized output formats the agent should produce. These describe expected results; they do not enforce an output schema or guarantee model compliance. Examples include structured code review checklists, deployment runbooks, or security audit reports.

Success Metrics

Measurable criteria the agent uses to self-evaluate its work. These give the model a clear definition of “done” and help prevent premature task completion. Metrics might include “All tests pass,” “No critical vulnerabilities remain,” or “Coverage exceeds 80%.”

Tip

Structured expert prompts are configured per-expert in the database. Edit them through the web UI on the Experts page or via the API.

Tool Execution

The ToolExecutor handles the built-in agent tool loop. External CLI execution has different visibility:

1. Permission check: Validates the tool call against the three-tier permission system (ALLOW / ASK / DENY)
2. Secret injection: Substitutes {{secret:name}} templates in tool arguments with vault values
3. Execution: Delegates to the registered tool handler
4. Error tracking: Counts consecutive failures per tool

Consecutive Failure Protection

Tools are automatically disabled after 3 consecutive failures. When this happens:

• The tool is stripped from subsequent LLM requests
• The model is forced to respond using available information
• This prevents infinite loops where a model repeatedly calls a failing tool

Context Compaction

When a conversation exceeds the token window, the runtime applies LLM-summarized context compaction:

1. The current conversation history is sent to the LLM with a summarization prompt
2. The LLM produces a compressed summary of the conversation so far
3. The summary replaces the full history, freeing tokens for continued work

This allows long-running agents to work beyond the context window limit by compressing earlier context. Summarization can omit or distort details; preserve durable artifacts and inspect them when accuracy matters.

Agent Lifecycle

spawn → running → [paused] → completed / failed / stopped

Status	Description
running	Agent is actively processing in the think-act-observe loop
paused	Agent is temporarily suspended (can be resumed)
completed	Worker reported completion; inspect the deliverable and checks to assess correctness
failed	Agent encountered an unrecoverable error
stopped	Agent was manually stopped by a user

Configuration

Variable	Default	Description
AGENT_MAX_TOKEN_BUDGET	100000	Maximum tokens per agent (0 = unlimited)
AGENT_DEFAULT_TIMEOUT	900000	Default timeout in ms (15 minutes); swarm level settings can set different limits
AGENT_MAX_ITERATIONS	50	Maximum think-act-observe iterations

Tip

Token limits constrain execution but are not exact monetary caps. Set provider-side budgets separately; 0 disables the per-agent token bound.

Agent Events

Each agent emits events that can be consumed via the REST polling API or WebSocket:

Event Type	Description
thought	The agent’s reasoning about what to do next
action	A tool call being made
observation	The result of a tool call
error	An error encountered during execution
status	Agent status change (running, paused, completed, etc.)

Execution events have durable database records and cursor-based polling; live transport/replay buffers are not the full history. Reconnecting a client does not automatically resume interrupted work.