Skip to content

README.md

Latest commit

 

History

History
91 lines (67 loc) · 4.88 KB

README.md

File metadata and controls

91 lines (67 loc) · 4.88 KB

Optio examples

Working configurations and setup scripts for the three Task tiers in Optio. Each example is self-contained, runnable against a local Optio cluster, and idempotent (re-running setup scripts is safe).

Use these as documentation-by-example: copy a folder, modify the agents to suit your use case, re-run setup.sh. Every example follows the same shape:

<example-name>/
  README.md     # what it does, how to run, what to expect
  agents/       # one JSON per agent (or task/workflow definition)
  setup.sh      # idempotent provisioning script

Layout

examples/
├── repo-tasks/         # Repo Tasks — agents that run in a worktree, open a PR
├── standalone-tasks/   # Standalone Tasks — single-shot agents, no repo
└── persistent-agents/  # Persistent Agents — long-lived, message-driven

Pick by what shape of work you have:

You want… Tier
An agent that opens a PR and is done Repo Task
A scheduled or webhook-triggered single-shot job Standalone Task
A long-lived service that wakes on messages or events Persistent Agent
Multiple coordinating agents with dispatch + handoff Persistent Agent

Available examples

Persistent Agents

Example Agents Showcases
forge 4 A four-agent engineering team — architect dispatches specs to an implementer, reviewer reviews PRs, scribe maintains a team journal. Direct messages + broadcasts + always-on (Chronicler) vs sticky (the rest) pod lifecycle.
mars-mission-control 7 A flight-control team handling five sols of escalating incidents on Mars. A Clock agent fires scheduled "events" via a cron trigger; specialists coordinate a response broadcast by broadcast. Showcases scheduled-trigger-as-forcing-function, parallel specialist handoffs, and /workspace/-based mission log continuity.

Repo Tasks

Examples coming. Open a PR to contribute one. The shape is repo-tasks/<name>/{README.md, task.json, setup.sh} where task.json is the body of POST /api/tasks with type: "repo-blueprint".

Standalone Tasks

Examples coming. Open a PR to contribute one. The shape is standalone-tasks/<name>/{README.md, workflow.json, setup.sh} where workflow.json is the body of POST /api/jobs.

Running an example

All scripts assume an Optio API at http://localhost:30400 (the setup-local.sh default). Override with OPTIO_API_URL, and pass OPTIO_API_TOKEN if your server requires auth (local dev with OPTIO_AUTH_DISABLED=true doesn't).

# default
./examples/persistent-agents/forge/setup.sh

# remote / authed
OPTIO_API_URL=https://optio.acme.com \
OPTIO_API_TOKEN=$(cat ~/.optio-token) \
  ./examples/persistent-agents/forge/setup.sh

After provisioning, open the corresponding UI surface:

Tier UI
Persistent Agents (Agents) /agents (list) → /agents/:id
Repo Tasks (Tasks) /tasks (list) → /tasks/:id
Standalone Tasks (Jobs) /jobs (list) → /jobs/:id

The v0.4 sidebar split each tier into its own top-level route under Run (Tasks · Jobs · Reviews · Issues · Scheduled) and Live (Agents · Sessions). The legacy /tasks?tab=… URLs redirect to the dedicated pages.

Cleanup

Each example documents its own cleanup snippet in its README, but the universal form for persistent agents is:

# Delete every agent provisioned by an example
for slug in $(jq -r '.slug' examples/persistent-agents/<name>/agents/*.json); do
  id=$(curl -s "$OPTIO_API_URL/api/persistent-agents" \
        | jq -r ".agents[] | select(.slug==\"$slug\") | .id")
  [ -n "$id" ] && curl -s -X DELETE "$OPTIO_API_URL/api/persistent-agents/$id"
done