Batch Jobs

​

Overview

A batch job runs a single agent across many inputs at once. The inputs come from a datasource: the agent processes every data element in it independently, and each result is written to an output datasource. The common case is applying one agent to a large set of documents: extracting fields from every invoice in a folder, or classifying a backlog of support tickets. Running an agent over that many inputs by hand means building the surrounding machinery: a loop over the inputs, a limit on how many run at once, retries for failures, collection of the results, and storage for later use. A batch job provides that machinery, leaving the agent and the datasource as the only things to specify. The agent runs in batch exactly as it was configured for a single input. The configuration you developed and tuned on one document runs unchanged across the entire set.

​

Running the same agent

When a batch definition is created, Meibel resolves the named agent and pins a snapshot of its full configuration into the definition: its system prompt, model, tools, artifact schemas, and confidence scoring modules. Every execution of that definition runs against that snapshot. This is useful because of how agents are developed. An agent is tuned on individual inputs, its output checked and its configuration adjusted until it performs well. A batch job runs that same configuration, so the agent behaves in batch as it did during development. A single agent definition serves both interactive runs and batches. Pinning also makes a run reproducible. A definition retains its snapshot even after the underlying agent changes, so a past execution reflects the agent as it was configured at the time. When a batch should use a newer version of the agent, updating the definition re-pins the snapshot and records a new version of the definition.

​

The batch definition

A batch job has two parts. A batch definition is the reusable configuration: a catalog object with an ID, a name, and a version history. An execution is one run of a definition against its inputs. A single definition can have many executions, and each execution links back to the definition it ran, so any result can be traced to the configuration that produced it. A definition records:

• The agent to run on each input, pinned at creation as described above.
• The input datasource whose data elements become the run’s inputs.
• Filters to narrow that set, by name pattern, by content type (for example, only PDFs), or by an explicit list of element IDs. Without filters, every data element is processed.
• The output datasource where results are written. If it is unset, each execution creates a new one.
• A user message, an optional instruction sent to the agent alongside each input, the same way a message accompanies a document in an interactive run.
• Concurrency and a retry limit: how many inputs run at once, and how many times a failing input is retried before the failure is treated as final. These default to 10 and 2.

Editing a definition does not overwrite it. The edit creates a new version linked to the previous one, and earlier versions stay readable. A definition cannot be deleted while an execution still references it, so the configuration behind a past result remains available.

​

How an execution runs

An execution proceeds in three stages: it reads the inputs, runs the agent on them in parallel, and writes the results. Reading the inputs. The execution lists the data elements in the input datasource, applies the definition’s filters, and confirms that both datasources belong to the same project before any work starts. Running in parallel. The platform processes the inputs concurrently, up to the limit set on the definition, each one a separate run of the pinned agent with its data element attached as the document to work on. The runs are independent, so a failure on one input does not affect the others. Writing the results. When a run finishes, the platform writes its artifacts to the output datasource, tagged with the source document. An input is counted as succeeded only after its artifacts are written, so a run that produces no artifacts is recorded as a failure. The platform then ingests the output datasource, so the results become data elements like any other. They can be searched, fed to another agent, or used as the input to a further batch job.

​

Progress and failure handling

A batch job runs asynchronously. Rather than returning a result inline, an execution reports its progress while it runs: the total number of inputs, how many are in progress, how many have succeeded, how many are waiting for a retry, and how many have failed after their retries are exhausted. A running total of retry attempts is also reported. Failures are handled at two levels. Within an execution, the platform retries a failing input automatically, up to the definition’s retry limit. This absorbs transient failures, such as a model being briefly unavailable or a tool call timing out, where a later attempt is likely to succeed. An input still failing after its retries are exhausted is recorded as a failure for that execution. After an execution finishes, its failed items can be rerun. This starts a new execution against the same definition, restricted to the inputs that failed, and leaves the successful inputs unchanged. It applies when the failures were transient and have since passed, or when the configuration has been corrected. A running execution can also be canceled. Inputs that have already finished keep their results, and inputs that have not started do not begin.

​

Related concepts

Batch jobs build on other parts of the platform: