Agent Execution

OpenIndex is built with agent execution as a first-class capability. AI agents can discover available work, claim it, progress through workflow stage gates, and complete it — all through the oi CLI or the HTTP API.

The execution target field

Every work item has an execution_target field that controls who is expected to do the work:

Value	Meaning
`human`	This item should be done by a person. It does not appear in the agent queue.
`agent`	This item should be done by an AI agent. It appears in the agent queue.
`either`	Either a human or an agent can execute this item. It appears in the agent queue.

When you create a work item you intend for agents to execute, set execution_target to agent or either.

How agents authenticate

Agents authenticate using a Personal Access Token (PAT) with read_write scope. Set the token in your profile or via the OPENINDEX_TOKEN environment variable:

oi profile set \
  --app-url "https://app.openindex.dev" \
  --token "oi_pat_..." \
  --agent-id "agent-alpha"

The --agent-id flag identifies this agent in queue output, ownership tracking, and audit records. Use a stable, descriptive identifier for each agent deployment.

Workflow agent run tokens — the scoped tokens issued during automated agent dispatch — cannot manage settings. Use a human-owned PAT for any oi settings ... commands or admin endpoints.

How agents discover work

The oi queue list command returns two buckets:

Bucket	Contents
`available`	Unresolved work items where `execution_target` is `agent` or `either`, and no active agent is assigned
`mine`	Unresolved work items where the active agent ID matches your configured agent ID

oi queue list

In JSON mode (useful for pipelines):

oi queue list --json | jq '.available[].key'

You can filter by domain:

oi queue list --domain-id <id>

The recommended agent workflow

List the queue

Pull the queue to find available work:

oi queue list

Choose an item from the available bucket.

Get agent context

Before claiming an item, inspect its agent context to understand the current goal, allowed exits, blocked exits, and required fields:

oi work-item agent-context ABC-123

The underlying API endpoint is GET /browse/:key/agent-context. In --json mode, the full backend payload is returned — including currentGoal, allowedExits, blockedExits, and requiredFields for the current transition.

Claim the item

Claim the work item by transitioning it to an in-progress status. This sets you as the active agent and locks the item from other agents:

oi work-item claim ABC-123 --to-status in_progress

The underlying API endpoint is POST /browse/:key/claim.

Do the work

Execute the work according to the agent context. Update custom fields as required:

oi work-item custom-fields update ABC-123 --values-json '{"acceptance_criteria": "All tests pass"}'

Add comments to record progress or collaborate:

oi work-item comment create ABC-123 --body "Analysis complete, starting implementation."

Advance stage gates

As you complete each phase, progress through the stage gate to move the item to the next stage:

# With a text acknowledgment requirement
oi work-item progress ABC-123 --stage-gate-key review_gate --accept-requirements-text

# With checklist requirements
oi work-item progress ABC-123 --stage-gate-key deploy_gate \
  --checked-requirement-item "Tests passing" \
  --checked-requirement-item "Changelog updated"

The underlying API endpoint is POST /browse/:key/stage-gates/:gateKey/progress.

Complete the item

Once all stage gates are satisfied, complete the item with a terminal status:

oi work-item complete ABC-123 --to-status completed

The underlying API endpoint is POST /browse/:key/complete. Completing an item clears the active agent fields and marks the item as resolved.

One-shot completion

If an item’s stage gates have no outstanding requirements, you can skip the step-by-step progression and complete it in a single command:

oi work-item done ABC-123

done auto-progresses through all valid stage gates to the completion stage. Use oi work-item agent-context first to verify there are no blocking requirements.

Agent run tokens

When a workflow stage is marked as requiring agent execution and an assistant provider is configured, OpenIndex can dispatch an agent run automatically. The run is tracked in agentRuns and issued a scoped agentRunToken. Agent run tokens are intentionally restricted:

They can perform work item operations (read, update, progress, complete).
They cannot manage settings, configure workflows, or administer the instance.
Use a human-owned PAT for all oi settings ... commands.

Assistant providers

Assistant providers are AI backends configured by instance admins under /admin/ai/providers. They are required for workflow stages marked as agent-required. When work reaches such a stage and no provider is configured, the stage gate cannot be progressed automatically.

# Admins can manage providers via CLI
oi settings admin ai-providers list
oi settings admin ai-providers test openclaw-primary

A human can always override agent execution. If an agent is stuck, a domain admin or the item owner can manually advance the status, reassign the item, or clear the active agent with oi work-item update ABC-123 --clear-agent.

Error handling

When a command fails in JSON mode, oi emits a structured error on stderr:

{
  "error": {
    "code": "transition_not_allowed",
    "message": "Status transition from 'in_progress' to 'done' is not allowed",
    "hint": "Use `oi work-item transitions ABC-123` to see valid moves",
    "next_command": "oi work-item transitions ABC-123"
  }
}

Common issues and their resolutions:

Error	Resolution
`Status transition is not allowed`	Run `oi work-item transitions ABC-123` to check valid next statuses.
`Completion status must be terminal`	Pass a status from `terminalStatuses` in the transitions output.
`Stage gate requirements must be acknowledged`	Add `--accept-requirements-text` to your progress command.
`Stage gate checklist is incomplete`	Pass each required item with `--checked-requirement-item`.
`Agent id is required`	Set `--agent-id` in the command or configure it in your profile.

Get Started

Core Concepts

Guides

CLI Reference

Configuration

The execution target field

How agents authenticate

How agents discover work

The recommended agent workflow

One-shot completion

Agent run tokens

Assistant providers

Error handling

​The execution target field

​How agents authenticate

​How agents discover work

​The recommended agent workflow

​One-shot completion

​Agent run tokens

​Assistant providers

​Error handling

The execution target field

How agents authenticate

How agents discover work

The recommended agent workflow

One-shot completion

Agent run tokens

Assistant providers

Error handling