Execute Tool Batch - Nanonets Agents Platform

This document covers execute_tool_batch, which runs a list of tool calls the agent has already prepared — typically the output of a payload-builder tool — as a single step. Use it when the same tool must be called many times with different arguments. Without it the agent has to emit one call per item, which costs either a decision round trip per call or an unordered parallel fan-out. A fan-out is unsafe whenever the downstream system locks on something the calls share: creating four sales orders against one reference contract 170 ms apart fails three of them with Sales document ... is currently being processed.

Authentication and enablement

The tool makes no outbound calls of its own — every credential belongs to the tool being called, which is resolved exactly as it would be on a direct step (configured-tool bindings → integration discovery → secrets). It is off by default. Enable it per agent in the tool list. A batch can only execute tools the agent itself may run: the registry the agent was built with is the allowlist.

Inputs

Field	Type	Required	Description
`calls`	array	yes	The calls to run, in order. At most 200. If an earlier step already produced the list, pass a reference to it (`"${VAR_1}.calls"`) instead of repeating every entry — see Passing the list by reference.
`calls[].tool`	string	yes	Tool name, exactly as it appears in the agent’s tool list (a configured display name or a base tool).
`calls[].args`	object	no	Arguments for that tool, exactly as on a direct call.
`calls[].key`	string	no	Stable identity for the call. A keyed call runs at most once per task.
`mode`	string	no	`sequential` (default) or `parallel`.
`max_concurrency`	integer	no	Parallel mode only. Default 4, maximum 16.
`serialize_on`	string	no	Parallel mode only. Dotted path into each call’s args.
`stop_on_error`	boolean	no	Stop starting further calls after the first failure. Default `true`.
`include_results`	boolean	no	Inline each call’s result payload in this tool’s own result. Default `true`.

Passing the list by reference

A batch’s calls list is often built by an earlier step. Rather than copying every entry into the batch call, name the step output that holds it:

{ "calls": "${VAR_1}.calls" }

The reference is resolved before the tool runs and arrives as a real array, so a 200-entry list costs one short argument instead of a full re-emission of the plan. The reference must be the whole value of the field. These are rejected before anything runs, each naming what arrived:

What was passed	Why it is rejected
A reference embedded in a larger string (`"the plan: ${VAR_1}.calls"`)	Only a sole-content reference is inlined as JSON; embedded in a sentence it stays quoted text.
A reference to a step output that does not exist on this task	The unresolved `${VAR_N}` token is reported as a missing step output, not as a syntax error in the list.
The container object rather than the list (`"${VAR_1}"` where that output is `{"calls": [...]}`)	Pass the list itself — add the accessor.
An empty string	There is no list to run.

Ordering

sequential runs one call at a time, in the order given. It is the default because a batch may contain writes and “one at a time” is the only ordering that is safe without knowing anything about the tools involved. parallel runs calls concurrently, at most max_concurrency at once. serialize_on refines parallel mode and is the reason to prefer it over a blanket sequential. It names a path into each call’s args; calls whose value at that path is equal run one at a time relative to each other, while calls with different values run concurrently. Set it to whatever the downstream system locks on:

{
  "mode": "parallel",
  "serialize_on": "reference_sd_document",
  "max_concurrency": 4,
  "calls": [
    { "tool": "create_sales_order", "key": "PO-4600008975-1", "args": { "reference_sd_document": "40040343", "...": "..." } },
    { "tool": "create_sales_order", "key": "PO-4600008975-2", "args": { "reference_sd_document": "40040343", "...": "..." } },
    { "tool": "create_sales_order", "key": "PO-4600009012-1", "args": { "reference_sd_document": "40041002", "...": "..." } }
  ]
}

The first two share a contract and run in order; the third runs alongside them. A call whose serialize_on path resolves to nothing, or to an object or array, is treated as unconstrained.

Keys and resuming

Give every call with a side effect a stable key. A keyed call is executed at most once per task: if the batch is re-run after a partial failure, already-completed keys are reported as skipped with the step id of the original call instead of being repeated. Keys must be unique within a batch. Omit the key to opt out — appropriate for read-only calls where repetition is harmless.

Outputs

structuredContent is a summary plus one entry per call:

{
  "status": "partial",
  "total": 3, "succeeded": 2, "failed": 1, "skipped": 0, "not_run": 0,
  "results": [
    { "index": 0, "tool": "create_sales_order", "key": "PO-...-1", "status": "completed", "step_id": "…", "duration_ms": 8991, "result": { } },
    { "index": 1, "tool": "create_sales_order", "key": "PO-...-2", "status": "failed", "error": "sap api error (status 400): …" },
    { "index": 2, "tool": "create_sales_order", "key": "PO-...-1", "status": "skipped", "step_id": "…" }
  ]
}

status is completed when every call landed, failed when none did, and partial otherwise. Per-call status is completed, failed, skipped (already run under that key), not_run (the batch stopped before reaching it) or awaiting (it ran and paused for review — await_id names the review). A call’s result is inlined only if it is under 4 KB and the batch’s total inlined payload is under 256 KB; over either, result_omitted is true. Nothing is lost — every call’s full result is on its own step, which step_id names.

Side effects

Each call is recorded as its own child step of the batch step, with:

a row in steps (already completed, so it is never re-dispatched or reaped),
its own step_usage row, priced under the called tool’s name rather than folded onto the batch,
a tool_execution trace in agent_logs, and
a feed card nested under the batch’s card.

So a batched call is bookkept exactly like a direct tool step.

What happens if the run is interrupted

A batch can be interrupted mid-flight — a deploy, a pod eviction, a crashed worker. The platform re-runs the batch step, so the batch always finishes; what matters is whether a call that already ran is repeated. The rule: a call that finished is never repeated. A call that was still running may be. When the batch restarts, it looks at what already completed in this task and skips those calls. The only call it cannot reason about is one that was in flight at the moment of the interruption — the request had left, the answer never came back, and there is no way to tell from this side whether it landed. That call runs again. So the number of operations that can be repeated by one interruption is the number of calls that were running at that instant:

	Repeats at most
`sequential`, keys set	1
`parallel` with `max_concurrency: N`, keys set	N
No keys, either mode	everything already done — the batch restarts from the beginning

This is the reason to set key on anything with side effects, and the reason to prefer sequential for them. Without keys the batch has no way to recognise its own earlier work, so an interruption near the end of a forty-call batch repeats all thirty-nine that succeeded.

If the task itself stops or fails, the batch is not resumed at all and the remaining calls never run. Resumption applies to a live task.

Verified behaviour

Measured by killing the worker mid-batch at five different points in an eight-call run. Every run finished with eight operations performed and none repeated, skipping between one and five calls depending on how far it had got. The same test without keys performed eleven operations for the same eight calls.

If repeats are unacceptable

For work where even one repeat is too many — creating an order, issuing a payment, sending a message — the durable answer is for the receiving system to recognise the repeat: a uniqueness rule on a reference you already send, or an idempotency key if its API accepts one. Nothing this tool can do on its own closes the gap, because it cannot learn the outcome of a request it never got an answer to.

Limits and expected errors

Condition	Behaviour
More than 200 calls	Rejected before anything runs — split the work.
`calls` empty, duplicate `key`, unknown `mode`	Rejected before anything runs.
`serialize_on` given with `mode: "sequential"`	Rejected: it would silently do nothing.
A pausing tool (`await_*`, `ask_user`, `task_complete`, `delegate_tasks`, `web_automation`)	That call fails. A tool that pauses or ends the agent has to run at the agent loop; nested in a batch it would register an await nothing resumes. Checked on the resolved base tool, so an alias cannot route around it.
A call that pauses for review — extraction or review tools can stop for human validation depending on the document	That call is reported as `awaiting` with the review’s id, and the batch stops, whatever `stop_on_error` says. The call itself completed; what the batch cannot do is wait for a review, so it does not run the remaining calls past one. Run these from the agent loop when a pause is expected.
`execute_tool_batch` inside a batch	That call fails. A batch of batches multiplies without bound, so neither the 200-call limit nor the concurrency width would hold.
A native-loop tool (`run_code`, `continue`, `task_metadata`, `milestone_*`)	That call fails — these are mechanisms of the agent loop itself, not callable work.
One call fails	Recorded as a failed child step and reported in `results`. With `stop_on_error` (the default) no further calls start; in-flight ones finish.
The batch itself	Does not return `isError` when calls fail. The step succeeded; its value is the per-call breakdown. Failing the step would send the whole batch back through step retry and repeat the calls that did land.
The step is cancelled or the worker is shut down	No further calls start. Calls already made stand; re-issue the batch with the same keys to resume.

​Authentication and enablement

​Inputs

​Passing the list by reference

​Ordering

​Keys and resuming

​Outputs

​Side effects

​What happens if the run is interrupted

​Verified behaviour

​If repeats are unacceptable

​Limits and expected errors

Authentication and enablement

Inputs

Passing the list by reference

Ordering

Keys and resuming

Outputs

Side effects

What happens if the run is interrupted

Verified behaviour

If repeats are unacceptable

Limits and expected errors