Skip to content
Hoard Hoard

Orchestrator (Beta)

Hoard Orchestrator (Beta) adds a coordination layer on top of the shared memory and search index. It lets multiple agents register, pull tasks, publish events, and track workflows with artifacts and cost reporting.

What It Does

  • Agents register and announce capabilities
  • Tasks represent units of work an agent can claim and complete
  • Workflows chain tasks into multi-step automation
  • Artifacts store outputs (inline or on disk)
  • Events publish state changes for polling
  • Cost records usage and budgets

Execution Model (Agents Pull)

Agents poll for work, claim a task, then complete it. The server does not push tasks to agents.

flowchart LR
  A[Agent registers] --> B[Agent polls tasks]
  B --> C{Task available?}
  C -- yes --> D[Agent claims task]
  D --> E[Agent completes task]
  E --> F[Artifacts + cost + events]
  F --> G[Workflow status updated]
  C -- no --> B

Workflow Definitions

Workflows are JSON with a steps array. Each step must include a step_key.

Common fields:

  • step_key (required)
  • name and description
  • depends_on_steps (list of step keys)
  • requires_capability and requires_proficiency
  • timeout_seconds and max_attempts
  • on_failure (retry, skip, fail_workflow, fallback)
  • fallback_step_id (required if on_failure is fallback)

Task Statuses

  • pending
  • queued
  • claimed
  • running
  • completed
  • failed
  • cancelled
  • timed_out

Workflow Statuses

  • draft
  • running
  • paused
  • completed
  • failed
  • cancelled

Workflow Step Statuses

  • pending
  • ready
  • running
  • completed
  • failed
  • skipped

Artifacts and Events

Artifacts attach outputs to tasks. Text can be stored inline or written to a blob path.

Events are an append-only log of orchestration changes. Agents poll events with event.poll.

Cost Tracking

Agents can report cost usage via cost.report. Budgets are configured per agent, per workflow, and globally.

Security and Tokens

  • Registration token: HOARD_REGISTRATION_TOKEN is required for agent.register.
  • Server secret: HOARD_SERVER_SECRET is required to run the write-enabled server.
  • Scopes: Orchestrator tools require specific scopes such as task.claim, task.execute, workflow.manage, and artifact.write.

See Security and MCP Tools for full scope maps.

Storage

Orchestrator data is stored in the same SQLite database as entities and memory:

  • Agents and capabilities
  • Tasks and dependencies
  • Workflows and steps
  • Artifacts and events
  • Cost ledger

See Data Model for table details.