BatchJob Async Job Skill

Use this skill when the user wants to run or manage batch jobs through the BatchJob service.

Required Environment

• BATCHJOB_BASE_URL
• BATCHJOB_BEARER_TOKEN

All HTTP requests must include:

-H "Authorization: Bearer ${BATCHJOB_BEARER_TOKEN}"
-H "Content-Type: application/json"

API Endpoints

• POST /v1/batch/files:upload
• POST /v1/batch/jobs:precheck
• POST /v1/batch/jobs
• GET /v1/batch/jobs/{job_id}
• GET /v1/batch/jobs?page=1&page_size=10&status=...
• POST /v1/batch/jobs/{job_id}:cancel

Automation Policy (Default)

• Always run in full-auto mode.
• Do not ask user for file_id first.
• Resolve file source from current message/context, then upload automatically when needed.
• Ask follow-up questions only when no readable file source can be obtained.
• Accepted input file formats for upload: jsonl, csv, xlsx, xls (BatchJob normalizes to internal JSONL).
• For jsonl, each line must be either:
  • canonical Vertex format (contents + optional generationConfig)
  • simple prompt format (prompt + optional aspect_ratio / image_urls, where image_urls must be publicly reachable URLs)
• If user gives only model mode after a file message, treat it as confirmation and continue automatically.

Guardrails (Must Follow)

• Do not auto-retry by creating a second job unless user explicitly asks.
• Do not auto-rewrite dataset format after a terminal failure unless user explicitly asks.
• Before upload, auto-normalization is allowed only once for known safe mappings (e.g. simple prompt JSONL -> Vertex JSONL).
• Upload failure is terminal for this run: do not continue to precheck/submit when upload fails.
• Never submit when row_count <= 0.
• Do not fetch or parse output_summary_url automatically; only do it when user asks for detailed failure reason.
• After reaching terminal status (completed, failed, partially_failed), stop execution and return summary immediately.

JSONL Compatibility Rule (Important)

BatchJob internal execution expects each JSONL line to be a VertexGeminiImageRequest shape.

• Canonical line format:
  • contents[0].parts[0].text contains prompt text
  • generationConfig.imageConfig.aspectRatio is optional
  • generationConfig.responseModalities should include IMAGE and TEXT
• Non-canonical simple JSONL like {"prompt":"...","aspect_ratio":"1:1"} is acceptable; server will normalize it to Vertex format.
• If JSONL has neither contents nor prompt, stop and ask user to provide valid data.
• Explicitly unsupported (must reject before submit):
  • OpenAI Batch style lines containing method + url + body (for example /v1/chat/completions payload).
  • This schema will fail with Vertex error: at least one contents field is required.

Dataset Output Rule (Important)

When user asks you to generate a template/demo file for BatchJob image tasks: