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

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

OpenIndex is designed for AI agents to discover and execute work alongside humans. Agents use the same `oi` CLI and HTTP routes as human operators, with a recommended workflow that moves from discovery through execution to completion.

***

## Prerequisites

Before an agent can operate, you need:

* A Personal Access Token (PAT) with `read_write` scope
* An agent ID to track which agent is holding work

Create a PAT in OpenIndex settings (user-authenticated UI), then configure the agent profile:

```bash theme={null}
oi profile set \
  --app-url "https://app.openindex.dev" \
  --token "oi_pat_..." \
  --agent-id "agent-alpha"
```

Verify the setup:

```bash theme={null}
oi doctor
oi auth check
```

<Warning>
  Workflow agent run tokens are intentionally rejected for `oi settings ...` commands. Settings surfaces require human-owned credentials.
</Warning>

***

## The recommended agent workflow

<Steps>
  <Step title="Discover available work">
    Pull the queue to see work items that are unassigned and targeted for agent execution:

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

    The queue returns two buckets: `available` (unassigned, `executionTarget != human`) and `mine` (assigned to your agent ID).
  </Step>

  <Step title="Inspect calendar context">
    Check the current schedule before claiming work so you can place it appropriately:

    ```bash theme={null}
    oi calendar day --date 2026-03-01
    # or for a weekly view
    oi calendar week --start-date 2026-03-01
    ```
  </Step>

  <Step title="Get available transitions">
    Before claiming, confirm the work item can transition to an in-progress status:

    ```bash theme={null}
    oi work-item transitions ABC-123
    ```
  </Step>

  <Step title="Get agent context">
    Fetch the agent-oriented execution bundle for the work item. This includes the current goal, allowed exits, blocked exits, and any required fields:

    ```bash theme={null}
    oi work-item agent-context ABC-123
    ```

    In `--json` mode, this returns the full payload from `GET /browse/:key/agent-context`.
  </Step>

  <Step title="Claim the item">
    Claiming registers your agent ID on the work item and transitions it to an in-progress status:

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

  <Step title="Schedule the work (optional)">
    Place the work item on a date or time block:

    ```bash theme={null}
    oi work-item schedule ABC-123 --date 2026-03-01
    ```
  </Step>

  <Step title="Progress through stage gates">
    If the workflow has stage gates, satisfy each one before moving on:

    ```bash theme={null}
    oi work-item progress ABC-123 --stage-gate-key <gate-key>
    ```

    For checklist gates, pass every required item:

    ```bash theme={null}
    oi work-item progress ABC-123 --stage-gate-key <gate-key> \
      --checked-requirement-item "First requirement" \
      --checked-requirement-item "Second requirement"
    ```
  </Step>

  <Step title="Complete the item">
    Mark the work item as resolved with a terminal status:

    ```bash theme={null}
    oi work-item complete ABC-123 --to-status completed
    ```
  </Step>

  <Step title="One-shot shortcut">
    If the workflow allows it, `done` auto-progresses through all valid stage gates directly to completion:

    ```bash theme={null}
    oi work-item done ABC-123
    ```
  </Step>
</Steps>

***

## JSON mode for pipelines

When stdout is not a TTY (for example, in a pipeline or script), `oi` defaults to JSON output automatically. You can also force it explicitly:

```bash theme={null}
oi --json work-item get ABC-123
```

In JSON mode, command failures emit structured error output on stderr:

```json theme={null}
{
  "error": {
    "code": "transition_not_allowed",
    "message": "Status transition is not allowed",
    "hint": "Use transitions to check available statuses",
    "next_command": "oi work-item transitions ABC-123"
  }
}
```

The `next_command` field gives agents a direct path to recover from errors without human intervention.

***

## Using the schema for structured invocations

To get a machine-readable JSON Schema of all CLI commands, arguments, and flags:

```bash theme={null}
oi schema
```

This is useful for building agents that construct `oi` invocations dynamically.

***

## Updating custom fields during execution

Workflows can require structured data at specific stage transitions. Read the current values and update them as your agent executes:

```bash theme={null}
# Read current custom field values
oi work-item custom-fields get ABC-123

# Update values using a JSON object keyed by field key
oi work-item custom-fields update ABC-123 --values-json '{"field_key":"value"}'
```

***

## Collaborating via comments

Agents can leave progress notes and internal logs as comments on a work item:

```bash theme={null}
oi work-item comment create ABC-123 --body "Progress update" --visibility internal
```

Use `--visibility external` if the comment should appear in an outbound email thread visible to external participants.

***

## Troubleshooting common errors

<AccordionGroup>
  <Accordion title="Unauthorized">
    Check your token configuration:

    ```bash theme={null}
    oi profile show
    ```

    Ensure the PAT is valid, not revoked, and not expired.
  </Accordion>

  <Accordion title="Insufficient token scope">
    Work-item and queue operations require at least `read_write` scope. Create a new PAT with the correct scope in OpenIndex settings.
  </Accordion>

  <Accordion title="Status transition is not allowed">
    Query the transitions endpoint before claiming:

    ```bash theme={null}
    oi work-item transitions ABC-123
    ```
  </Accordion>

  <Accordion title="Completion status must be terminal">
    Pass a status from `terminalStatuses` in the transitions output. If you need to pass through a stage gate first:

    ```bash theme={null}
    oi work-item progress ABC-123 --to-stage completed
    ```
  </Accordion>

  <Accordion title="Stage gate requirements must be acknowledged">
    Pass `--accept-requirements-text` for text-acknowledgement gates:

    ```bash theme={null}
    oi work-item progress ABC-123 --stage-gate-key <gate-key> --accept-requirements-text
    ```
  </Accordion>

  <Accordion title="Agent ID is required">
    Set an agent ID in your profile or pass it per command:

    ```bash theme={null}
    oi profile set --agent-id agent-alpha
    # or
    oi work-item claim ABC-123 --to-status in_progress --agent-id agent-alpha
    ```
  </Accordion>
</AccordionGroup>