Provider-native batches

Batches run a versioned Agntz LLM manifest over a reusable dataset using the provider's asynchronous batch API. They are designed for offline enrichment, classification, extraction, and regression runs where you want to change the model, rerun the same inputs, and compare outputs.

versioned batch manifest + pinned dataset version
                         ↓
       OpenAI / Anthropic / Gemini / Mistral batch API
                         ↓
       normalized item results + side-by-side comparison

Batch execution creates batch records only. It does not create ordinary agent runs, sessions, or traces.

Define a batch

A batch definition is an extended standard kind: llm manifest. The raw YAML is the versioned source of truth.

id: customer-summaries
name: Customer summaries
description: Summarize each customer record for an operations review.
kind: llm

model:
  provider: openai
  name: gpt-5.4-mini
  temperature: 0.2
  maxTokens: 800

instruction: |
  You are a careful operations analyst.
  Summarize the record, identify risks, and recommend the next action.

prompt: |
  Customer record:
  {{input}}

outputSchema:
  type: object
  properties:
    summary: { type: string }
    risks:
      type: array
      items: { type: string }
    nextAction: { type: string }
  required: [summary, risks, nextAction]
  additionalProperties: false

defaultDataset:
  id: customer-records
  version: production

The provider-native subset accepts id, name, description, model, instruction, prompt, examples, inputSchema, outputSchema, and defaultDataset. It deliberately rejects tools, skills, resources, spawnable agents, replies, state, pipelines, runtime retries, and provider option escape hatches. Each dataset item becomes one independent model request.

Supported providers are openai, anthropic, google, and mistral. Agntz validates the native request/file limit used by each adapter instead of adding a smaller platform-wide item cap. Model fields unsupported by the selected provider are rejected instead of being silently ignored.

Import a reusable dataset

Datasets are versioned independently from batch definitions. Imports are staged and chunked, so clients can upload large CSV or JSONL sources without building one large API request.

CSV defaults to id and input columns. Remaining columns become item metadata. JSONL accepts one { "id": "...", "input": ... } object per line.

const dataset = await client.datasets.import({
  source: { path: "./customers.csv" },
  format: "csv",
  datasetId: "customer-records",
  name: "Customer records",
});

You can also pass normalized item arrays to either client. Dataset versions and aliases can be pinned in a run just like batch versions.

Create and run from a client

const batch = await client.batches.create(batchYaml);

const run = await client.batches.run({
  batchId: batch.id,
  datasetId: dataset.id,
  idempotencyKey: "customer-summaries-2026-07-29",
});

const fresh = await client.batches.getRun(run.id);
const page = await client.batches.items(run.id, { limit: 500 });
const jsonl = await client.batches.resultsJsonl(run.id);

A run can use a stored dataset or inline items, but not both. On submission, Agntz resolves aliases and snapshots exact batch and dataset versions. Updating either record later does not change an existing run.

Swap a model and compare

Update only model.provider or model.name, save the manifest as a new version, then submit another run against the same dataset version.

const comparison = await client.batches.compare(firstRun.id, secondRun.id, {
  limit: 500,
});

for (const row of comparison.rows) {
  console.log(row.itemId, row.left?.output, row.right?.output);
}

The comparison response says whether both runs used the same dataset version. The hosted app exposes the same workflow at /batches: edit YAML, swap the model, rerun, inspect item results, export normalized JSONL, and compare two runs side by side.

Lifecycle and failures

Run states are validating, submitting, queued, running, cancelling, completed, failed, expired, and cancelled. Item states are pending, succeeded, failed, expired, and cancelled.

A provider job that finishes with a mixture of successful and failed requests is a completed batch. Its counts and item results preserve the failures. failed is reserved for a job-level failure.

The worker leases due runs from durable storage and reconciles provider state idempotently. Results remain available until the batch run is explicitly deleted. Active runs must be cancelled before deletion. Use client.batches.deleteRun(runId) in TypeScript or client.batches.delete_run(run_id) in Python after a terminal state.

Completion callback

Pass both callbackUrl and webhookSecretName to receive one signed batch.complete event after a terminal state is durable.

await client.batches.run({
  batchId: "customer-summaries",
  datasetId: "customer-records",
  callbackUrl: "https://app.example.com/webhooks/agntz",
  webhookSecretName: "production-webhook",
});

Delivery uses the same HMAC headers and retry outbox as ordinary run callbacks. The terminal delivery ID is stable, so a worker restart cannot enqueue a second logical completion event.

Raw HTTP

The primary routes are:

See the HTTP API reference for the rest of the worker surface and Hosted client for client construction and error handling.