# AI agents

Klineo agents produce evidence-backed investigations, saved-proposal reviews and hypothetical research. A durable agent run has a reviewed source, a bounded workflow, saved progress and a result that can be reopened. Availability depends on your workspace permissions, enabled workflow policy and configured worker and provider infrastructure.

The AI Agent conversation also offers public-market research. That request-and-response experience has a different persistence and control contract; see [Research workflows](/guides/workflows).

## Choose a workflow

| Workflow | Reviewed source | Purpose | Required capabilities |
| --- | --- | --- | --- |
| `HEALTH_INVESTIGATION` | A vault version or a saved public project with exact observation references | Inspect captured evidence and compare supported observations | `ai:read`, `ai:generate`, `vault:read` |
| `PROPOSAL_REVIEW` | A V1 proposal timestamp, V2 proposal resource version, or decision-pack version and content hash | Review the saved packet and surface deterministic findings, missing evidence and next checks | `ai:read`, `ai:proposal-review`, `vault:read` |
| `WHAT_IF_RESEARCH` | An issuer-intent resource version | Plan and run a reviewed hypothetical experiment | `ai:read`, `ai:generate`, `vault:read`, `simulation:run` |

These capabilities authorize the workflow. They do not grant transaction signing, proposal approval or financial execution. A Proposal Review result does not approve the proposal. Research confirmation authorizes a bounded study; financial actions use their separate product controls.

Public-project Health compares recorded reserve observations and a deterministic finding catalog. It does not establish continuous-period market activity, causality, executable depth or issuer control. Vault Health uses the latest fully closed UTC calendar day and the preceding UTC day as baseline. Review the exact dates before starting; they are not rolling 24-hour windows.

## Start a run

1. Sign in and select an authorized workspace.
2. Open the source and review its current version. Keep version tokens exactly as returned, including timestamp precision for V1 sources.
3. Review the question, captured source and workflow-specific inputs.
4. Submit the request with a stable `Idempotency-Key` of 8–200 characters.
5. Keep the returned `runId` and read its current detail and activity.

Admission is `POST /api/liquidity-studio/v2/agent-runs`. A new accepted run returns HTTP `202`; an identical accepted replay returns `200`. The admission receipt describes queueing and its deadline, rather than a completed report.

The server derives requester and organization authority from the authenticated session and selected workspace. Request bodies cannot choose a different actor, tenant, model, tools or budget. The admission transaction rechecks current membership, role, subject version, workspace enablement and reservations. Missing or stale source versions require a fresh read and review.

An exact retry uses the original key and payload. Changing a request under the same key conflicts. If a request loses its response, recover with the same key before creating a new run. An HTTP timeout alone does not establish that admission failed.

## Follow progress

| State | Meaning | Next action |
| --- | --- | --- |
| `QUEUED` | Accepted and waiting for a worker checkpoint | Read current status |
| `RUNNING` | Processing a bounded checkpoint | Inspect activity; cancel if the control is available |
| `WAITING_FOR_INPUT` | A specific clarification or Research proposal needs the requester | Review the pending question or typed Research proposal |
| `WAITING_FOR_CHILDREN` | Private Research studies are outstanding | Inspect Research progress |
| `COMPLETED` | The workflow reached its validated completion | Read the result when `resultAvailable` is true |
| `PARTIAL` | A validated result has incomplete evidence or coverage | Inspect the limitations and missing checks |
| `ABSTAINED` | The workflow withheld a conclusion | Read the recorded reason |
| `FAILED` | The run stopped with a recorded failure | Inspect status and start a newly reviewed run if appropriate |
| `CANCELLED` | The requester cancelled the run | Inspect retained settled evidence |

Terminal runs are immutable. Completion describes the bounded workflow and its report validation; it does not prove financial correctness or current applicability. Always compare the saved source, cutoff and limitations with the decision you intend to make.

## Waiting, resuming and cancellation

There is no generic agent `PAUSE` or `RESUME` command. A waiting run resumes through the specific human input it requested. `RESPOND` selects an existing option for the current clarification and returns the run to `QUEUED`. Research uses `REVISE_ASSUMPTIONS` and `CONFIRM_RESEARCH`; see [What-if Research](/guides/research).

Commands use `POST /api/liquidity-studio/v2/agent-runs/{runId}/commands` with an `If-Match` header containing the quoted current run resource version and an `Idempotency-Key`. The command body contains the action and its required fields, while the version comes from the header. For example:

```json
{ "action": "CANCEL" }
```

```json
{
  "action": "RESPOND",
  "questionId": "the-current-question-id",
  "optionId": "an-option-from-that-question"
}
```

Controls belong to the initiating interactive user and are reauthorized when submitted. Another member's read access does not grant cancellation authority. The detail response's `controls` flags help render available actions; they are not authorization tokens.

Cancellation retains already settled evidence and prevents later checkpoint evidence from being committed to the terminal run. An in-flight external provider request may still finish or incur usage. Cancellation does not undo a completed report or reverse a financial action. Waiting states also have deadlines; they cannot remain available indefinitely.

After an ambiguous command response, retry the exact command with its original key and reviewed version. A recovered receipt can describe the previously accepted state, so read current run detail after recovery. Do not infer current state from a replayed receipt alone.

## Read APIs

All paths below use the `/api/liquidity-studio/v2` prefix and require current authenticated workspace access.

| Method and path | Returns |
| --- | --- |
| `GET /agent-runs` | Scoped history with kind, state and subject filters and an opaque pagination cursor |
| `GET /agent-runs/{runId}` | State, phase, source binding, deadline, result availability and control flags |
| `GET /agent-runs/{runId}/events` | Ordered activity with continuation metadata |
| `GET /agent-runs/{runId}/result` | A supported saved report, subject to current read authorization |
| `GET /agent-runs/{runId}/evidence/{evidenceId}` | An authorized captured vault Health evidence record, after its saved result is verified |
| `GET /agent-runs/{runId}/research-planning` | The typed pending proposal or completed planning successor |
| `GET /agent-runs/{runId}/research-progress` | Private-study progress |
| `GET /agent-runs/{runId}/research-trials/{trialKey}` | Admitted trial inputs and inspection commitments |

Treat cursors and resource versions as opaque values. Start a fresh history request when the organization or filters change. Evidence reads can have a narrower permission boundary than summary reads. Service identities and developer service-account credentials cannot use this interactive-user agent surface.

## Provider and trust boundaries

Deterministic data collection and calculation precede model interpretation. The durable worker freezes a configured provider profile and uses a ledger to reserve attempts, tokens and estimated cost. An ambiguous dispatched attempt is recovered through its gateway receipt rather than blindly resending the provider generation.

Configured ceilings are limits, not measured bills. Unresolved usage remains unknown; a gateway-reported cost estimate is not a reconciled provider invoice. A validated model schema and bound citations constrain the output but do not establish that every interpretation is correct.

The admission endpoint can return `503` while saved reads remain available. Enabling a deployment flag alone does not provision workspace policy, worker coverage or a compliant provider gateway. This documentation describes the implemented contract; the environment's live availability remains authoritative.