> ## 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`.

# Continue and inspect agent runs

> Continue a conversation, save sandbox state, and download the trace of a completed agent session.

Repeated `run()` calls on one agent reuse its sandbox and conversation.
Checkpoints save state beyond the sandbox's lifetime. Session traces record
what happened and remain readable after the sandbox ends.

Start with the [SDK quickstart](https://docs.evolvingmachines.ai/agent-sdk/index.md). Run the Python fragments
inside an async function, as in that example.

## Continue a conversation

Add another call before the quickstart's `finally` block. Wait for the first
run to finish before starting the next.

```typescript TypeScript theme={"dark"}
await agent.run({
  prompt: "Shorten output/notes.md " +
    "to three bullet points.",
});
const updatedOutput = await agent.getOutputFiles();
console.log(updatedOutput.files["notes.md"]);
```

```python Python theme={"dark"}
await agent.run(
    prompt=(
        "Shorten output/notes.md "
        "to three bullet points."
    ),
)
output = await agent.get_output_files()
print(output.files["notes.md"])
```

`getOutputFiles()` / `get_output_files()` reads output files written during
the latest run. Pass `true` / `True` to include nested directories.

To keep the files but start a fresh conversation, pass `resume: false` in
TypeScript or `resume=False` in Python. `kill()` destroys the sandbox; read
or save the output before calling it.

## Save state

Replace the quickstart's agent configuration with the following to enable
storage. This uses your `EVOLVE_API_KEY`.

```typescript TypeScript theme={"dark"}
import { Evolve } from "@evolvingmachines/evolve";

const agent = new Evolve()
  .withAgent({
    type: "codex",
    model: "gpt-6-luna",
  })
  .withStorage();
```

```python Python theme={"dark"}
from evolve import AgentConfig, Evolve, StorageConfig

agent = Evolve(
    config=AgentConfig(
        type="codex",
        model="gpt-6-luna",
    ),
    storage=StorageConfig(),
)
```

Keep the quickstart's `try/finally` cleanup. After a successful foreground
run, the response can contain a checkpoint. Save its ID before destroying
the sandbox:

```typescript TypeScript theme={"dark"}
if (!result.checkpoint) {
  throw new Error("No checkpoint was saved");
}
console.log(result.checkpoint.id);
```

```python Python theme={"dark"}
if result.checkpoint is None:
    raise RuntimeError("No checkpoint was saved")
print(result.checkpoint.id)
```

An automatic checkpoint failure does not fail the agent run, so check for
the checkpoint before relying on it. Background runs do not create automatic
checkpoints. A checkpoint preserves workspace files and supported agent
history, not a running process. Dependency and cache directories such as
`node_modules/`, `.venv/`, and the workspace's `temp/` are excluded;
reinstall dependencies after restoring when needed.

## Restore state

In a new copy of the quickstart, enable storage and keep the same harness
and workspace mode. Set `checkpointId` / `checkpoint_id` to the saved ID.
Replace the first `run()` call with the following; keep the output retrieval
and `finally` cleanup:

```typescript TypeScript theme={"dark"}
const result = await agent.run({
  prompt: "Continue editing output/notes.md.",
  from: checkpointId,
});
```

```python Python theme={"dark"}
result = await agent.run(
    prompt="Continue editing output/notes.md.",
    from_checkpoint=checkpoint_id,
)
```

Restore creates a fresh sandbox. Do not combine it with `withSession()` or
Python's `sandbox_id`, which attach to an existing sandbox.

## Download a past trace

The `sessions()` client reads recorded sessions without starting a sandbox.
This example downloads the first ended session returned by the list:

```typescript TypeScript theme={"dark"}
import { sessions } from "@evolvingmachines/evolve";

const client = sessions();
const page = await client.list({
  state: "ended",
  limit: 1,
});
if (page.items.length > 0) {
  const path = await client.download(page.items[0].id, {
    to: "./traces",
  });
  console.log(path);
}
```

```python Python theme={"dark"}
from evolve import sessions

async with sessions() as client:
    page = await client.list(
        state="ended",
        limit=1,
    )
    if page.items:
        path = await client.download(
            page.items[0].id,
            to="./traces",
        )
        print(path)
```

The printed path points to a local JSONL trace. To list, inspect, or share
these records from your terminal, use [`evolve session`](https://docs.evolvingmachines.ai/cli-reference/session).


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