Skip to main content
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:
ValueMeaning
humanThis item should be done by a person. It does not appear in the agent queue.
agentThis item should be done by an AI agent. It appears in the agent queue.
eitherEither 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:
BucketContents
availableUnresolved work items where execution_target is agent or either, and no active agent is assigned
mineUnresolved 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>
1

List the queue

Pull the queue to find available work:
oi queue list
Choose an item from the available bucket.
2

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.
3

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.
4

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."
5

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.
6

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:
ErrorResolution
Status transition is not allowedRun oi work-item transitions ABC-123 to check valid next statuses.
Completion status must be terminalPass a status from terminalStatuses in the transitions output.
Stage gate requirements must be acknowledgedAdd --accept-requirements-text to your progress command.
Stage gate checklist is incompletePass each required item with --checked-requirement-item.
Agent id is requiredSet --agent-id in the command or configure it in your profile.