Saga

A saga plans first, then executes the plan durably. It is designed for multi-step work such as research, migrations, and audits, where completed work should remain available if another step needs to be retried or revised.

Options#

A saga accepts everything a Single Agent does except maxTurns and permissionMode (it plans rather than iterates, so a turn cap has no meaning) plus three of its own:

A research saga#

import { createAgent } from '@coresourceai/sdk';

const researcher = createAgent({
  type: 'saga',
  systemPrompt: `You are a rigorous deep-research agent. Decompose the question,
search broadly, prioritise primary sources, cross-check important claims, and
resolve conflicting evidence. Cite every material claim and state uncertainty
explicitly.`,
  model: 'deepseek/deepseek-v4-flash',
  effort: 'xhigh',
  maxSteps: 40,
  parallelism: 4,
  outputs: ['report.md']
});

const run = await researcher.start('Validate the invoice-management benchmarks.');
const result = await run.result();

const report = result.artifacts.find((artifact) => artifact.name === 'report.md');
if (report) {
  console.log(await report.text());
}

await researcher.close();

Parallel execution#

parallelism is the maximum number of planned steps that may execute concurrently. With parallelism: 4, the scheduler may run up to four independent steps at once; actual concurrency depends on the plan and available work.

Use a saga when one agent definition can own the complete plan. It gives you one run id and one result to observe.

Reach for orchestration only when the stages need genuinely different configurations: different models, different tools, different trust boundaries.

Start, do not run#

run() waits for completion, which for a saga can be hours. Use start() and persist the run id.

import { createAgent } from '@coresourceai/sdk';

const saga = createAgent({ type: 'saga', outputs: ['migration-plan.md'] });

const run = await saga.start('Plan the reporting-database migration.');
console.log(`started ${run.id} - safe to exit; the run is durable`);

await saga.close();

The run belongs to the platform, not to your process. Another process can use the run id with the HTTP endpoints. See runs and streaming.