Batch API Planner

/batch-api — Agent-prepared Batch API workflow

Hard rule for this whole skill: if any qwen batch … command fails, or the task turns out to be unsuitable, report what happened in a few lines and stop (the one exception, a plan-field error from run, is in §4). Never fall back to doing the transform yourself in this session — the user chose the half-price asynchronous path explicitly, and silently doing the work at full realtime price is exactly what they opted out of. Offering it as a choice ("I can do this realtime instead, at full price") is fine; doing it without being asked is not.

The user explicitly chose async batch mode by typing /batch-api. This mode trades latency for price: the provider bills Batch requests at 50% of the realtime list price (with no context-cache benefit), and a job takes tens of minutes to hours to finish (completion window 24h or more). Your job is to turn the user's task into a small plan file that the deterministic executor (qwen batch run) submits. You never write request JSONL by hand and never call the Batch API yourself.

0. Check readiness before anything else

Run every qwen batch … command with the shell tool as "${QWEN_CODE_CLI:-qwen}" batch … — QWEN_CODE_CLI names the CLI running this session, so a plain qwen on PATH (possibly an older install without these subcommands) is only the fallback. First make sure the CLI you reach has them. Help output never calls a model:

"${QWEN_CODE_CLI:-qwen}" batch --help

If the output does not list batch run <plan>, the qwen it reached is an older install without these subcommands — say so (the session's CLI is not on PATH as qwen) and stop. Do not run any other batch command there: an older CLI treats batch check as a prompt and answers it with a billed model call. Then:

"${QWEN_CODE_CLI:-qwen}" batch check

It proves the credentials, endpoint and Batch route work and shows the model, thinking mode and output limit a run would freeze from the user's current settings — without a billed request. settings.batch.model can select a separate modelProviders entry; its endpoint, envKey and generationConfig are used without changing the conversation model. Do not edit authentication or settings to work around a failed check. If it fails (for example Qwen OAuth, which has no Batch route), relay its message and stop: do not read files or draft a plan the executor cannot submit. Pass its note: lines on to the user.

1. Decide suitability honestly — this is your main job

Suitable: many independent, single-turn transforms whose input materials are fully available right now. Examples: translate a set of documents under a fixed style guide, rewrite files to a new format, summarize or extract structured data from each file of a set.

Unsuitable:

• Work that needs iterative feedback — debugging, run-test-fix loops, exploratory refactors. The next step there depends on results that do not exist yet.
• Chained tasks where one item's output is another item's input.
• A handful of items, or a task the user needs answered soon. Batch's wait buys nothing there.

If the task is unsuitable, say so in one short paragraph and stop.

2. Prepare lightly

The whole point is saving money, so do not burn the savings in preparation:

• Discover the target files with glob.
• Read only a small sample (2–3 files) to understand structure and edge cases. Do NOT deeply read every file — the executor reads and embeds the full contents mechanically at submission time.
• Draft the shared rules once: terminology, style, format constraints, and the exact output contract. The model that runs the batch sees only your plan — spell out everything it needs, including "return ONLY the complete transformed document, no commentary".

3. Write the plan file

Write one JSON file to .qwen/batch/plans/<slug>.json (<slug> = short kebab-case task name) with the write_file tool:

{
  "version": 1,
  "name": "<slug>",
  "kind": "document-transform",
  "shared": {
    "system": "optional role/system prompt",
    "instructions": "the shared transform rules, terminology, output contract"
  },
  "items": [
    {
      "id": "intro",
      "source": "docs/zh/intro.md",
      "target": "docs/en/intro.md"
    }
  ]
}

Rules:

• id must match [A-Za-z0-9][A-Za-z0-9_-]{0,59} (1–60 characters) and be unique per item; it becomes part of the provider-side custom_id.
• Paths are relative to the current working directory. Every target must be unique and must not overwrite an existing file — pick fresh output paths inside the project and outside any hidden path such as .git/, .github/ or .qwen/, at any depth (refused). Results that arrive to a changed source or an occupied target are held, not written.
• Optional fields: completionWindow (default 24h, max 14d), maxOutputTokens (set it when outputs can be long — a truncated item can only be retried with a larger limit), expectedOutputTokensPerItem (improves the cost estimate), maxCostUsd (run and retry refuse to submit when the worst case at the request caps exceeds it; it needs unit prices from check, a maxOutputTokens, and thinking off or a thinking_budget — otherwise the run is refused, so only set it when the user asked for a hard budget).
• Do NOT set enableThinking unless the user asked for a thinking mode: the executor freezes the thinking mode, sampling parameters and output limit from the user's current settings, so Batch runs the same way their realtime session does. Changing it silently changes both cost and quality.
• If you are unsure about model, prices, or provider limits, leave them to the executor — do not invent numbers.