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

# Your First Agent Experiment

> Understand what happens after you prompt an Onyx agent to start auto research.

After you run a prompt like `/onyx Tune my PID controller gains, minimize error`,
the orchestrator turns that goal into a validated local setup, then starts an
asynchronous session whose hypothesis workers produce measured git history.

## From Prompt to Campaign

The orchestrator first converts your prompt into campaign metadata:

| Field       | Example                                            |
| ----------- | -------------------------------------------------- |
| Name        | `tune-pid-gains`                                   |
| Metric      | `tracking_error`                                   |
| Unit        | `error` or `%`                                     |
| Direction   | `minimize`                                         |
| Description | `Tune PID gains while keeping overshoot below 5%.` |

It then creates or selects an Onyx campaign and records the current git commit as its base.

## Local Setup

Before changing product code, the orchestrator should create and commit:

* `onyx/setup.json`: the canonical local setup policy;
* `onyx/validation.json`: the latest local setup validation report;
* `onyx/onyx.md`: the generated research spec with durable project guidance;
* `onyx/tools/*`: helper scripts for reset, readiness, evaluation, guardrails, or environment control.

Then it validates the setup hash and static checks so future attempts have a
stable local measurement policy.

## Experiment Loop

Each attempt follows the same shape:

<Steps>
  <Step title="Start workflow">
    A hypothesis worker runs `onyx-worker exp run --campaign <name> --auto`. The CLI
    creates a durable workflow run using the clean worker `HEAD` as the base and
    pauses at the leading agent step.
  </Step>

  <Step title="Edit and commit">
    The worker changes scoped files based on its brief and `onyx.md`, then makes
    exactly one clean result commit.
  </Step>

  <Step title="Resume workflow">
    The worker runs `onyx-worker exp run --resume --auto`. The CLI
    verifies setup compliance, executes declared workflow tools, parses the
    primary metric, and stores step logs.
  </Step>

  <Step title="Record">
    The worker logs the terminal attempt with `onyx-worker exp log`; the CLI resolves
    the measured attempt from worker context and records status, metric, output
    summary, setup compliance, and agent notes.
  </Step>

  <Step title="Report">
    It pushes an immutable experiment ref, then reports the result directly to the Onyx API. The server accepts, deduplicates, or rejects the report.
  </Step>
</Steps>

## What Gets Recorded

Every experiment points to an exact commit and includes:

* status, such as `succeeded`, `failed`, `checks_failed`, or `setup_violation`;
* primary metric value;
* output summary;
* optional guardrail result;
* local setup compliance;
* agent notes about what was learned.

These records build the campaign review surface and best-so-far view in the app.

## How to Watch Progress

In the Onyx app:

* Graph view shows the campaign, experiments, hypotheses, workers, and current best metric.
* Campaign overview shows campaign setup summary, resources, workers, hypotheses,
  summaries, stop state, and best-so-far steps.
* File tree shows changed files plus `onyx/` context.
* Diff view compares an experiment to the previous best when possible.

In the terminal:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx status
onyx research status
onyx-worker workflow status
onyx-worker exp list --limit 20
onyx listen
```

## Manual Debugging

The agent runs the CLI for you, but these commands are useful when debugging a setup:

```bash theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
onyx-worker tools run evaluation.run
onyx-worker exp run --campaign fast-eval --auto
onyx-worker workflow status --json
onyx-worker exp log --description "manual measurement check"
```

Use `onyx-worker tools run <tool-id>` for transient smoke checks. It leaves workflow
and measured-attempt state untouched.

If the agent cannot measure progress, inspect the declared metric tool in
`onyx/setup.json`. The metric step must print a numeric line such as:

```text theme={"theme":{"light":"github-dark-dimmed","dark":"github-dark-dimmed"}}
METRIC tracking_error=0.18
```