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 send prompts to agents in sandboxes from your application, use Evolve, Swarm, or Pipeline in the agent SDK guide.

Read your jobs

Complete the install and API-key setup in the Python guide or TypeScript guide, then run the matching example. It prints one page of your jobs; an empty list means none are visible to this request.

// Save as clients.mts; run: npx tsx clients.mts
import { hosted } from "@evolvingmachines/evolve";

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

# Save as clients.py; run: python clients.py
import asyncio
from evolve import hosted


async def main():
    async with hosted() as evolve:  # Reads EVOLVE_API_KEY.
        page = await evolve.jobs.list()
        print(page.items)


asyncio.run(main())

Python reference snippets that use await or async for belong inside an async function, as in main() above. TypeScript examples use await in an ES module.

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, change account settings, 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

To set an explicit key or default team, replace the hosted() construction above. Replace my-team with your organization’s slug or ID, or omit org to use your personal organization.

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. TypeScript checks for a key when an authenticated client is created, including the first access to hosted().jobs. Python checks when it makes an authenticated request.

One page or every item

These snippets use the evolve client above. Put the Python snippet inside the same async with block.

// 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
Named options	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(). Inside an async function:

from evolve import hosted

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

Closing a client does not cancel an evaluation. To stop a job, call await client.jobs.cancel(job_id) inside the async with block, using the job’s ID.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Read your jobs

Choose a client

Jobs

Trials

Datasets

Filesystems

Analyses

Checks

Look up a method

Configure once

One page or every item

Language differences