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

> ## Agent Instructions
> To set Ambral up in a project, run `npx ambral@latest skill install` in the project's root. It installs Ambral's skill, matched to the CLI's version, and the skill says how to do everything these pages describe with the `ambral` CLI. Prefer it to working from these pages. Never ask anyone for an Ambral API key, and never handle one: the person creates it in the web app and stores it where their app reads its secrets.

# A research agent

> Judge the path and the report, half each.

Judge the path and the report, half each.

Based on the `trajectory` preset.

A research agent: it searches, reads and follows leads in whatever order the evidence suggests, then writes a report.

No single step is right or wrong on its own, so the path is judged as a whole, as the trajectory preset does: one
judge call per trace and subject sees the subject's step at each point beside the baseline's, and asks whether the
subject could have stood in for the baseline; `guidance` tells it how much a different path matters here. The
report is what the user reads, so a criteria group grades the final reply on its own terms, and `replies: mean`
brings that into the trace's score: the mean of the verdict and the report's score. Compare the coding agent, which
combines a verdict with rules that must hold at every reply instead (`all-pass`).

An example to learn from, not a starting point: start a config from `ambral tasksets scoring preset`, and take
from this one the choices that fit your agent.

```yaml theme={null}
# preset: trajectory
# title: A research agent
# A research agent: it searches, reads and follows leads in whatever order the evidence suggests, then writes a report.
#
# Goal: judge the path and the report, half each.
#
# No single step is right or wrong on its own, so the path is judged as a whole, as the trajectory preset does: one
# judge call per trace and subject sees the subject's step at each point beside the baseline's, and asks whether the
# subject could have stood in for the baseline; `guidance` tells it how much a different path matters here. The
# report is what the user reads, so a criteria group grades the final reply on its own terms, and `replies: mean`
# brings that into the trace's score: the mean of the verdict and the report's score. Compare the coding agent, which
# combines a verdict with rules that must hold at every reply instead (`all-pass`).
#
# An example to learn from, not a starting point: start a config from `ambral tasksets scoring preset`, and take
# from this one the choices that fit your agent.

id: "replay"

points:
  tools: null
  take:
    type: "sample"
    k: 8

episode:
  rewards:
    # The report group grades only the final reply, so the replies' score is the report's, and the trace scores the
    # mean of it and the verdict. Without this, the report's score would be recorded but count for nothing.
    replies:
      mode: "mean"
    trajectory:
      model: "<judge>"
      # One call per trace reads the whole session and weighs paths against each other, so the judge reasons hard.
      reasoningEffort: "high"
      # A number here skips traces scored at more points than it. With sampled points that's never more than 10, so it
      # doesn't bound a long session: the judge reads the whole recorded session either way.
      maxPoints: null
      # Research takes many valid paths, so the baseline's steps are one good route, not the bar for each step.
      guidance: "The baseline's searches and sources are one good route, not the only one: a step that searches
        elsewhere or reads in another order is fine if it still moves toward an answer as well supported as the
        baseline's. Count against the subject steps that would lose the thread, stop before the question is
        answered, or answer from no source."
      # The only bound on the judge's prompt: each message is cut here. Research reads long documents, and a session
      # too long for the judge fails its call, and so the trial; lower this if that happens.
      context:
        maxChars: 8000
    checks: {}
  metrics:
    replies: null
    trajectory: null
    checks: {}

taskset:
  # Nothing compares a single reply with the baseline's: research takes many valid paths, so whether one step matches
  # the baseline's says nothing. The verdict judges the path, and the report group the report.
  fromBaseline:
    rewards: {}
    metrics: {}
    judges: {}
  criteria:
    report:
      model: "<judge>"
      # Only the trace's last turn, the report. The verdict already covers every step before it. No tool narrows it: a
      # subject that searches again where the baseline wrote its report is graded as if that were the report, and fails
      # `answers_the_question`, since it gave none (`cites_its_sources` is n/a there: it states no finding).
      turns:
        tools: null
        final: true
        on: "reply"
      # The sources the report draws on can sit anywhere in the session, so it shows the whole session. That carries
      # the verdict's risk: a session too long for the judge fails its call, and so the trial.
      context:
        messages: null
      criteria:
        - name: "answers_the_question"
          text: "The report answers the question the user asked, not a nearby one."
          # The judge picks one: no 0, partly 0.5, yes 1. It has no `notApplicable`, so n/a isn't one of them: every
          # report answers some question.
          choices:
            - "no"
            - "partly"
            - "yes"
          meanings:
            partly: "It answers part of the question, or a narrower version of it."
        - name: "cites_its_sources"
          text: "Each finding in the report names the source it came from, one the session retrieved."
          notApplicable: "The report states no finding."

required: []
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.