Tasks

client.tasks manages asynchronous Agent instructions and their executions. A Task is a definition; each Task run owns lifecycle state and receives a fresh Session when execution starts.

Overview

Schedules are once, interval, or five-field cron; null means on-demand. An optional Agent Version Pin is set at Task creation and can be changed or cleared. Task, Task-run, and transcript limits default to 50 and accept 1–200. Lists use opaque cursors; transcripts support backward cursor or forward after, never both.

Methods

`create()`

create(body: CreateTaskBody): Promise<CreateTaskResponse> — POST /v1/tasks. Requires agentId, name, and prompt. Omitted fields default to agentVersion: null, schedule: null, enabled: true, submit: false, userId: "", and metadata: {}. submit: true returns an initial runId.

`list()`

list(options?: { agentId?: string; cursor?: string; limit?: number; userId?: string }): Promise<TasksListResponse> — GET /v1/tasks. Returns non-deleted Tasks and compact latest-run state; limit defaults to 50 and accepts 1–200.

`get()`

get(taskId: string): Promise<TaskResponse> — GET /v1/tasks/:taskId.

`update()`

update(taskId: string, body: UpdateTaskBody): Promise<TaskResponse> — PATCH /v1/tasks/:taskId. At least one mutable field; schedule: null makes the Task on-demand and agentVersion: null follows latest.

`delete()`

delete(taskId: string): Promise<void> — DELETE /v1/tasks/:taskId.

`createRun()`

createRun(taskId: string, body?: { idempotencyKey?: string }): Promise<CreateTaskRunResponse> — POST .../runs. Omission sends {}. A key makes retries return the same deterministic run ID; at most one run per Task is active.

`listRuns()`

listRuns(taskId: string, options?: { cursor?: string; limit?: number }): Promise<TaskRunsListResponse> — GET .../runs. limit defaults to 50 and accepts 1–200.

`getRun()`

getRun(taskId: string, runId: string): Promise<TaskRunResponse> — GET .../runs/:runId.

`runMessages()`

runMessages(taskId: string, runId: string, options?: { after?: string; cursor?: string; limit?: number }): Promise<TaskRunMessagesResponse> — GET .../messages. A queued run without a Session returns an empty page and null cursors. limit defaults to 50 and accepts 1–200.

`cancelRun()`

cancelRun(taskId: string, runId: string): Promise<void> — POST .../cancel. Cancellation is cooperative and non-enumerating; poll getRun() for the resulting state.

Types

Task-run status is queued, running, blocked, succeeded, failed, or canceled; blocked is terminal quota denial. Task and run records include immutable Attribution and timestamps. See objects and schemas and pagination.

Errors

Invalid schedules, partial transcript cursors, and duplicate active runs surface through API errors. AGENT_DISABLED rejects creation with immediate submission and new runs for a disabled Agent. AGENT_VERSION_NOT_FOUND rejects an unavailable Version Pin. ADMIN_AGENT_MANAGED rejects assigning the Admin Agent to a Task. Cancellation intentionally does not reveal whether a target exists. See errors.

Example

import { BlazingAgents } from "@blazing-agents/sdk";
const client = new BlazingAgents({ apiKey: process.env.BLAZING_AGENTS_API_KEY! });
const agentId = "ag_0123456789abcdef";

const { task } = await client.tasks.create({
  agentId,
  name: "Release summary",
  prompt: "Summarize the release queue.",
});
await client.tasks.list({ agentId: task.agentId, limit: 25 });
await client.tasks.get(task.id);
await client.tasks.update(task.id, { metadata: { source: "docs" } });
const { runId } = await client.tasks.createRun(task.id, { idempotencyKey: "release-42" });
await client.tasks.listRuns(task.id, { limit: 25 });

let run = await client.tasks.getRun(task.id, runId);
let transcript = await client.tasks.runMessages(task.id, runId, { limit: 50 });
while (
  (run.status === "queued" || run.status === "running") &&
  transcript.latestCursor === null
) {
  await new Promise((resolve) => setTimeout(resolve, 500));
  transcript = await client.tasks.runMessages(task.id, runId, { limit: 50 });
  run = await client.tasks.getRun(task.id, runId);
}

const after = transcript.latestCursor;
if (after !== null) {
  transcript = await client.tasks.runMessages(task.id, runId, { after, limit: 50 });
}

await client.tasks.cancelRun(task.id, runId);
while (run.status === "queued" || run.status === "running") {
  await new Promise((resolve) => setTimeout(resolve, 500));
  run = await client.tasks.getRun(task.id, runId);
}

console.log(run.status, transcript.latestCursor);
await client.tasks.delete(task.id);

On this page