SDK clients

Use the same managed evaluation service from TypeScript or Python. Evolve runs the jobs; your program submits work and reads the results.

To run agents directly with the Evolve builder, Swarm, or Pipeline, use the separate agent SDK manual.

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

const evolve = hosted(); // Reads EVOLVE_API_KEY.
const page = await evolve.jobs.list();

from evolve import hosted

evolve = hosted()  # Reads EVOLVE_API_KEY.
page = await evolve.jobs.list()

Python examples in this reference belong inside an async function. The Python guide includes a complete runnable program.

Choose a client

Jobs

Start, follow, compare, retry, and download evaluations.

Trials

Inspect one attempt: reward, trace, and stored files.

Datasets

Browse tasks, publish versions, and inspect builds.

Filesystems

Read live sandbox files and saved captures.

Analyses

Read the analyzer’s results and saved runs.

Checks

Check task quality before running a benchmark.

Also available: agents, uploaded skills, secrets, identity and teams, and platform capabilities.

Look up a method

Use the client guides above for a workflow. Open a method reference for its inputs, returned fields, and Python and TypeScript examples.

Client	Method reference
Jobs	Start, watch, compare, retry, and import
Trials	Read attempts, traces, and artifacts
Filesystems	Read files, search, and follow live changes
Analyses	Read analysis runs and outputs
Checks	Create and inspect task quality checks
Datasets	Browse, publish, and manage versions
Agents	Register and manage harnesses
Skills	Upload and manage run context
Secrets	Store credentials and read metadata
Identity and teams	Read identity and manage membership
Capabilities	Read supported options and limits

For failures, start with error handling or find the exact name in the error-code reference.

Configure once

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

const evolve = hosted({
  apiKey: process.env.EVOLVE_API_KEY,
  org: "my-team",
});

import os
from evolve import HostedClientConfig, hosted

evolve = hosted(HostedClientConfig(
    api_key=os.environ["EVOLVE_API_KEY"],
    org="my-team",
))

Setting	TypeScript	Python	Default
API key	`apiKey`	`api_key`	`EVOLVE_API_KEY`
API origin	`baseUrl`	`base_url`	`EVOLVE_DASHBOARD_URL`, then the Evolve dashboard
Owning team	`org`	`org`	Your personal organization

The org default applies when you create jobs, publish datasets, register agents, or upload skills. A call’s own org wins. It does not filter list requests. Prefer a single client when useful: jobs(config), trials(config), and the other factories accept the same configuration. Import auth and managedSecrets / managed_secrets separately; they are not properties of hosted().

meta() needs no key. Other clients authenticate with your API key. TypeScript checks for a key when the client is created; Python checks when it makes an authenticated request.

One page or every item

// One page.
const page = await evolve.jobs.list({ limit: 20 });
console.log(page.items, page.nextCursor, page.hasMore);

// All pages, one job at a time.
for await (const job of evolve.jobs.list()) {
  console.log(job.id, job.status);
}

# One page.
page = await evolve.jobs.list(limit=20)
print(page.items, page.next_cursor, page.has_more)

# All pages, one job at a time.
async for job in evolve.jobs.list():
    print(job.id, job.status)

This pattern applies to list handles, including jobs.trials() and jobs.tasks(). A trace page, stored-file page, grep result, or dataset’s nested task page is a single page; follow its cursor yourself or use the dedicated iterator where available.

Language differences

Detail	TypeScript	Python
Calls	Input/options objects	Keyword arguments
Most domain fields	`model_name`, `cost_usd`	Same spelling
Returned entities	Objects	Dataclasses; stats, analyses, and checks are dictionaries
Download to memory	`Buffer`	`bytes`
Download to directory	`{ to: "./results" }`	`to="./results"`
Raw download stream	`{ stream: true }`	Not exposed
Wait cancellation	`AbortSignal` on watch methods	`timeout_s` on job/import/check watches

See types for field access and errors for request failures.

Python client lifetime

Hosted clients support async with and await client.close():

from evolve import hosted

async with hosted() as client:
    page = await client.jobs.list(limit=20)

The individual hosted clients currently have no resources to release in close(). Closing a client does not cancel an evaluation. Use jobs().cancel(job_id) to stop a job.

Get started

Run and inspect

Manage resources

Method reference

Choose a client

Jobs

Trials

Datasets

Filesystems

Analyses

Checks

Look up a method

Configure once

One page or every item

Language differences

​Choose a client

Jobs

Trials

Datasets

Filesystems

Analyses

Checks

​Look up a method

​Configure once

​One page or every item

​Language differences

Choose a client

Look up a method

Configure once

One page or every item

Language differences