Run agents in parallel

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

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

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.

node parallel.mjs

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.

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

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 for models and tools, or sessions to inspect previous runs.

HTTP API

Python and TypeScript

Run agents

Shared behavior

SDK workflows

SDK resources

SDK methods

Run agents in parallel

Process a batch

Combine the results

Choose another operation