Tasks

A task is a fire-and-forget agent run. Send a prompt, get back a handle. The agent works in the background — your process doesn't need to stay alive.

Tasks are perfect for long-running jobs: refactoring modules, generating reports, running test suites, updating dependencies.

Launch a Task

const agent = client.agent("build");

const task = await agent.run("Create a Node.js CLI tool that converts CSV to JSON. Include tests.");
console.log(`Task running: ${task.id}`);

Wait for Results

Blocking

Block until the task completes (with an optional timeout):

const result = await task.result({ timeoutMs: 300_000 });

console.log(result.status); // "completed" | "error"
console.log(result.text); // the agent's final output
console.log(result.tokens); // token usage
console.log(result.cost); // cost in USD

Polling

Check status without blocking:

const status = await task.poll();
// "accepted" | "busy" | "idle" | "error"

Webhooks

Get notified when the task completes without polling:

const task = await agent.run("Update all dependencies", {
    webhook: "https://my-app.com/hooks/agent-done",
});

Your webhook receives a POST with:

{
    "sessionId": "...",
    "status": "completed",
    "result": "...",
    "tokens": { "input": 1200, "output": 800, "reasoning": 0 },
    "timestamp": 1711234567890
}

Resume from Another Process

Save the task ID and check on it later — from a different process, a different machine, whenever:

const taskId = task.id;

// Later
const resumed = client.task(taskId);
const result = await resumed.result();

Cancel a Task

await task.cancel();

Full Example

import { createClient } from "swarmlord";

const client = createClient({
    apiKey: process.env.SWARMLORD_API_KEY!,
});

const agent = client.agent("build");

// Launch
console.log("Launching task...");
const task = await agent.run(
    "Create a Node.js project with a CLI tool that converts CSV to JSON. " +
        "Include tests. Run them to make sure they pass.",
    { title: "CSV to JSON CLI" }
);
console.log(`Task running: ${task.id}`);

// Wait
const result = await task.result({ timeoutMs: 300_000 });
console.log(`Status: ${result.status}`);
console.log(`Output:\n${result.text.slice(0, 500)}`);

if (result.tokens) {
    console.log(`Tokens: ${result.tokens.input}in / ${result.tokens.output}out`);
    console.log(`Cost: $${(result.cost ?? 0).toFixed(4)}`);
}

// Cleanup
await client.session(task.id).delete();