Tasks

Tasks model discrete steps within a run. They are listed at the top of the run's Events tab with their name and status, plus the error message for a task that failed, so you can see at a glance which step broke.

For new code, prefer spans: they record timing, nest, and show as a trace tree on the run page. Tasks remain supported for simple step tracking.

---

When to use tasks

Use tasks when your agent has identifiable phases, such as fetching data, running a model or writing output. Without tasks, a run is a flat stream of events. With tasks, each phase gets its own status.

---

Basic usage

import { AgentOS } from "@agentos-sdk/core";

const aos = new AgentOS(); // reads AGENTOS_API_KEY and AGENTOS_AGENT_ID
const run = await aos.startRun({ input: { file: "report.pdf" } });

const parseTask = await run.startTask("parse-pdf", { file: "report.pdf" });
const pages = await parsePDF("report.pdf");
await parseTask.complete({ output: { pages: pages.length } });

const summariseTask = await run.startTask("summarise", { pages: pages.length });
const summary = await summarise(pages);
await summariseTask.complete({ output: { summary } });

await run.complete({ output: { summary } });

---

Task lifecycle

startTask() → running
    ↓
complete()  → completed
fail()      → failed
skip()      → skipped

run.startTask(name, input?)

Creates a task in running state. Queued events are sent first.

const task = await run.startTask("fetch-data", { url: "https://api.example.com" });

task.complete(options?)

await task.complete({ output: { rows: 142 } });

task.fail(options)

await task.fail({ errorMessage: "Connection refused" });

task.skip()

Mark a task as intentionally skipped (for example, a cache hit made it unnecessary).

await task.skip();

---

Parallel tasks

Tasks are independent: you can start several and complete them in any order.

const [taskA, taskB] = await Promise.all([
  run.startTask("fetch-users"),
  run.startTask("fetch-products"),
]);

const [users, products] = await Promise.all([fetchUsers(), fetchProducts()]);

await taskA.complete({ output: { count: users.length } });
await taskB.complete({ output: { count: products.length } });

---

Python SDK

from agentos import AgentOS

aos = AgentOS()  # reads AGENTOS_API_KEY and AGENTOS_AGENT_ID
run = aos.start_run(input={"file": "report.pdf"})

task = run.start_task("parse-pdf", input={"file": "report.pdf"})
pages = parse_pdf("report.pdf")
task.complete(output={"pages": len(pages)})

run.complete(output={"pages": len(pages)})

A task ends with task.complete(output=None), task.fail(error_message) or task.skip():

task.fail("Connection refused")  # or task.skip()