Run agents from code

Run Codex or another coding agent in a cloud sandbox from your application. Give it a prompt, collect the files it creates, and continue the conversation when you need another turn. For scored runs against a dataset, use the evaluation SDK.

Install

npm install @evolvingmachines/evolve

pip install evolvingmachines-evolve

Use Node.js 18 or later. Python also requires Python 3.10 or later and Node.js, because the direct-agent SDK uses a Node bridge.

Set your API key

Create a key on the dashboard and export it in the terminal where you will run the example:

export EVOLVE_API_KEY="your-api-key"

With only this key, Evolve supplies model access and an E2B sandbox. If your environment contains sandbox provider credentials, they take precedence. See sandbox configuration.

Run one agent

This example starts a billable run and asks Codex to write a release note. The finally block destroys the sandbox after the output is read.

TypeScript / JavaScript
Python

Save as run.mjs. The example uses the TypeScript SDK from JavaScript, so it runs directly with Node.

run.mjs

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

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

try {
  const result = await agent.run({
    prompt: "Write a release note for CSV export " +
      "to output/notes.md.",
  });
  if (result.exitCode !== 0) {
    throw new Error(result.stderr || "Agent run failed");
  }
  const output = await agent.getOutputFiles();
  console.log(output.files["notes.md"]);
} finally {
  await agent.kill();
}

node run.mjs

Save as run.py.

run.py

import asyncio
from evolve import AgentConfig, Evolve

async def main():
    agent = Evolve(config=AgentConfig(
        type="codex",
        model="gpt-6-luna",
    ))
    try:
        result = await agent.run(
            prompt="Write a release note for CSV export "
                   "to output/notes.md.",
        )
        if result.exit_code != 0:
            raise RuntimeError(
                result.stderr or "Agent run failed"
            )
        output = await agent.get_output_files()
        print(output.files["notes.md"])
    finally:
        await agent.kill()

asyncio.run(main())

python run.py

The program prints the generated Markdown. The wording varies by run. output.files maps file names to their contents; paths are relative to the sandbox’s output/ directory.

Continue building

Configure an agent: choose a model and provide files, skills, and tools.
Continue and inspect runs: keep context, save state, and download traces.
Run work in parallel: process multiple inputs with Swarm.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Run agents from code

Install

Set your API key

Run one agent

Continue building