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

> ## Agent Instructions
> Evolve has two products behind one API key. Edith answers questions about an agent trajectory over HTTP: `POST https://api.evolvingmachines.ai/v1/decisions`. Evaluations run coding agents on tasks in cloud sandboxes, through the `evolve` CLI, the Python and TypeScript SDKs, or HTTP.
> A person creates the key at https://dashboard.evolvingmachines.ai/api-keys. Read it from `EVOLVE_API_KEY`; never ask for it in chat or write it to a file.
> Install the CLI with `npm install -g @evolvingmachines/evolve`, then confirm the connection with `evolve auth status`.
> The CLI carries the manual for its own version. `evolve skills get evals` prints the index and `evolve skills get evals <page>` prints one page, for example `evolve skills get evals cli-reference/run`. When the installed CLI is older than this site, follow the installed manual.
> Commands take `--help` for their options and `--json` for machine-readable output. Evaluations spend credits: start with one task and set `--max-trial-spend`.

# Environment-driven agent evaluation

> Run agents in isolated task environments. Compare models and harnesses, then inspect every attempt's score, trace, and cost.

Evolve is the engine for running reproducible agent evaluations at scale across tasks, sandboxes, harnesses, and models. It provides quality control during task creation, with full observability and trajectory analysis for every run.

An evaluation has three parts: **tasks** to solve, an **agent** (a harness and a model) that attempts them, and a **verifier** that scores each attempt. To check agent traces at scale, use [Edith](https://docs.evolvingmachines.ai/edith/index.md), our decision model.

```mermaid theme={"dark"}
%%{init: {
  "flowchart": {
    "nodeSpacing": 16,
    "rankSpacing": 20,
    "padding": 10
  },
  "themeVariables": {
    "fontSize": "14px",
    "fontFamily": "Google Sans Flex, sans-serif"
  }
}}%%
flowchart LR
  T["Tasks"] --> E["Evolve<br/>Cloud runs"]
  H["Harnesses"] --> E
  M["Models"] --> E
  E --> S["Scores"]
  E --> A["Trajectories"]
  E --> O["Logs and files"]
```

> [card] [Task quality checks](https://docs.evolvingmachines.ai/core-concepts/check.md)
>
> Check that tasks are solvable, instructions are clear, and verifiers score correctly.

> [card] [Agent optimization](https://docs.evolvingmachines.ai/core-concepts/jobs.md)
>
> Compare harnesses, models, and settings on the same tasks. Measure rewards and costs.

> [card] [Trajectory analysis](https://docs.evolvingmachines.ai/core-concepts/analyze.md)
>
> Review the agent’s actions, failures, and the evidence behind its score.

> [card] [Full observability](https://docs.evolvingmachines.ai/core-concepts/trial-outputs.md)
>
> Inspect traces, files, verifier logs, timing, token usage, and costs.

## Run one task

After [installation and authentication](https://docs.evolvingmachines.ai/getting-started/installation.md), run one DeepSWE task:

```bash theme={"dark"}
evolve run \
  -d deepswe@1.1 \
  -i anko-default-function-arguments \
  -a codex \
  -m gpt-6-luna \
  --max-trial-spend 1 \
  --max-retries 0 \
  --watch
```

The job runs in the cloud. Closing the terminal does not cancel it. The cap applies to one trial's model spend; an in-flight call can exceed it.

> [card] [First evaluation](https://docs.evolvingmachines.ai/getting-started/quick-start.md)
>
> Run one task, then read its score and trace.

> [card] [Your own tasks](https://docs.evolvingmachines.ai/core-concepts/tasks.md)
>
> Define the instruction, environment, and verifier.

> [card] [Python and TypeScript](https://docs.evolvingmachines.ai/sdk-reference/index.md)
>
> Run evaluations from your application.

> [card] [Use your coding agent](https://docs.evolvingmachines.ai/cli-reference/skills.md)
>
> Install the skill and read the CLI manual.

## Read the result

An evaluation produces a [trial](https://docs.evolvingmachines.ai/core-concepts/trials.md) for each attempt. Read its reward, follow the agent's trace, and open the saved files. Compare jobs to see how a different model or harness changes the result.

Use [task checks](https://docs.evolvingmachines.ai/core-concepts/check.md) to review a task before running it. Use [Edith](https://docs.evolvingmachines.ai/edith/index.md) to ask structured questions about a completed run, or [Analyze](https://docs.evolvingmachines.ai/core-concepts/analyze.md) for a written review with evidence.


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