Continue and inspect agent runs

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

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

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.

import { Evolve } from "@evolvingmachines/evolve";

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

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:

if (!result.checkpoint) {
  throw new Error("No checkpoint was saved");
}
console.log(result.checkpoint.id);

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:

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

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:

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);
}

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.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Continue and inspect agent runs

Continue a conversation

Save state

Restore state

Download a past trace