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

# Run agents in parallel

> Give each agent its own input and sandbox, then combine the results.

Use Evolve `Swarm` to give each agent its own input files and sandbox. This guide summarizes a batch of support tickets, then combines the results into one report.

Complete the [Agent SDK quickstart](https://docs.evolvingmachines.ai/agent-sdk/index.md) first and keep `EVOLVE_API_KEY` set.

## Process a batch

Pass one file map per worker to `map`. Each key is a filename; each value is its content. Here, each worker receives a different `context/ticket.txt` and writes `output/summary.md`.

Save the JavaScript example as `parallel.mjs`, or the Python example as `parallel.py`.

```javascript TypeScript / JavaScript theme={"dark"}
import { Swarm } from "@evolvingmachines/evolve";

const swarm = new Swarm({
  agent: {
    type: "codex",
    model: "gpt-6-luna",
  },
  concurrency: 2,
  tag: "support-triage",
});

const tickets = [
  "Search returns 503 errors during deployments.",
  "CSV exports omit rows with a date filter.",
  "Password reset links expire before arrival.",
];
const items = tickets.map((ticket) => ({
  "ticket.txt": ticket,
}));

const results = await swarm.map({
  items,
  prompt: [
    "Read context/ticket.txt.",
    "Summarize the problem and next action.",
    "Write the summary to output/summary.md.",
  ].join(" "),
});

for (const result of results.success) {
  console.log(
    result.meta.itemIndex,
    result.files["summary.md"],
  );
}
for (const result of results.error) {
  console.error(result.meta.itemIndex, result.error);
}
```

```python Python theme={"dark"}
import asyncio

from evolve import AgentConfig, Swarm, SwarmConfig


async def main():
    config = SwarmConfig(
        agent=AgentConfig(
            type="codex",
            model="gpt-6-luna",
        ),
        concurrency=2,
        tag="support-triage",
    )
    tickets = [
        "Search returns 503 errors during deployments.",
        "CSV exports omit rows with a date filter.",
        "Password reset links expire before arrival.",
    ]
    items = [{"ticket.txt": ticket} for ticket in tickets]

    async with Swarm(config) as swarm:
        results = await swarm.map(
            items=items,
            prompt=(
                "Read context/ticket.txt. "
                "Summarize the problem and next action. "
                "Write the summary to output/summary.md."
            ),
        )

        for result in results.success:
            print(
                result.meta.item_index,
                result.files.get("summary.md"),
            )
        for result in results.error:
            print(result.meta.item_index, result.error)


asyncio.run(main())
```

Run the saved file. Each worker starts a billable agent run.

```bash TypeScript / JavaScript theme={"dark"}
node parallel.mjs
```

```bash Python theme={"dark"}
python parallel.py
```

`map` returns one result per input, in input order. The example prints each successful worker's summary and reports any failed items separately.

| Result field | Contents |
| - | - |
| `status` | `success` or `error` for a map worker. |
| `files` | Files collected from the worker's `output/` directory. |
| `data` | The file map, or parsed data when you pass `schema`. `null` / `None` on failure. |
| `error` | Error message when the worker fails. |

`concurrency` limits active sandboxes across operations on this Swarm instance. The example allows two at once; the default is four. Remaining work waits for a free slot.

## Combine the results

Pass `results.success` to `reduce` to combine successful outputs with one agent. It receives each worker's files under `context/item_<index>/`, using the original input index.

Add this after the map call. In Python, keep it inside the same `async with` block.

```javascript TypeScript / JavaScript theme={"dark"}
if (results.success.length > 0) {
  const report = await swarm.reduce({
    items: results.success,
    prompt: [
      "Read the summaries in context/item_*/.",
      "Group related issues and " +
        "prioritize the next actions.",
      "Write output/report.md.",
    ].join(" "),
  });

  if (report.status === "success") {
    console.log(report.files["report.md"]);
  } else {
    console.error(report.error);
  }
}
```

```python Python theme={"dark"}
if results.success:
    report = await swarm.reduce(
        items=results.success,
        prompt=(
            "Read the summaries in context/item_*/. "
            "Group related issues and "
            "prioritize the next actions. "
            "Write output/report.md."
        ),
    )

    if report.status == "success":
        print(report.files.get("report.md"))
    else:
        print(report.error)
```

The report contains only successful workers' summaries. Check `results.error` before treating it as a complete account of the batch.

## Choose another operation

| Goal | Use | What you receive |
| - | - | - |
| Keep inputs that pass a check | `filter` with `schema` and `condition` | Original input files, grouped into `success`, `filtered`, and `error`. The agent assesses each item; your condition decides whether it passes. |
| Choose among several attempts | `bestOf` (TypeScript) or `best_of` (Python) | A selected `winner`, the candidates, and the judge's reasoning. Set `n` and `judgeCriteria` / `judge_criteria` in its config. |
| Repeat a sequence on new batches | `Pipeline` | Per-step results and the final `output`. Chain map, filter, and reduce steps, then call `run(items)`. Reduce must be the last step. |

You can also pass `bestOf` / `best_of` to `map` to generate candidates for every input. This adds candidate and judge runs; `concurrency` still caps how many sandboxes run at once.

See [agent configuration](https://docs.evolvingmachines.ai/agent-sdk/configure.md) for models and tools, or [sessions](https://docs.evolvingmachines.ai/agent-sdk/sessions.md) to inspect previous runs.


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