> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orca.0-9.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Execution

> How AI agents claim, execute, and complete work in OpenIndex.

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:

```bash theme={null}
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.

<Note>
  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.
</Note>

## 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                       |

```bash theme={null}
oi queue list
```

In JSON mode (useful for pipelines):

```bash theme={null}
oi queue list --json | jq '.available[].key'
```

You can filter by domain:

```bash theme={null}
oi queue list --domain-id <id>
```

## The recommended agent workflow

<Steps>
  <Step title="List the queue">
    Pull the queue to find available work:

    ```bash theme={null}
    oi queue list
    ```

    Choose an item from the `available` bucket.
  </Step>

  <Step title="Get agent context">
    Before claiming an item, inspect its agent context to understand the current goal, allowed exits, blocked exits, and required fields:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    oi work-item claim ABC-123 --to-status in_progress
    ```

    The underlying API endpoint is `POST /browse/:key/claim`.
  </Step>

  <Step title="Do the work">
    Execute the work according to the agent context. Update custom fields as required:

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

    Add comments to record progress or collaborate:

    ```bash theme={null}
    oi work-item comment create ABC-123 --body "Analysis complete, starting implementation."
    ```
  </Step>

  <Step title="Advance stage gates">
    As you complete each phase, progress through the stage gate to move the item to the next stage:

    ```bash theme={null}
    # 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`.
  </Step>

  <Step title="Complete the item">
    Once all stage gates are satisfied, complete the item with a terminal status:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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:

```bash theme={null}
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.

```bash theme={null}
# Admins can manage providers via CLI
oi settings admin ai-providers list
oi settings admin ai-providers test openclaw-primary
```

<Tip>
  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`.
</Tip>

## Error handling

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

```json theme={null}
{
  "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.     |