Tasks and runs

Lifecycle

Runtime version
└── Task                         durable identity and lifecycle
    ├── Sandbox                  isolated, temporary execution environment
    ├── Run 1                    prompt and streamed activity
    ├── Run 2                    follow-up or steering turn
    ├── Saved files and memory   durable state
    └── Conversation             durable evidence across the task

A task resolves one runtime version when it is created and keeps that version for its lifetime. Every task gets exactly one sandbox, so temporary filesystem and process state are not shared across executions.

Tasks come in two shapes:

Within a task, a run is one segment of work. A prompt opens a fresh turn. A steer message redirects a turn already in progress and falls back to a new prompt when no turn is active. Runs are the units of streaming and immediate cancellation; the task is the unit of identity, sandbox ownership, files, and conversation history.

Sandboxes

The sandbox contains the pinned recipe, uploaded and restored files, resolved bindings, owner-scoped memory, and a short-lived credential for talking back to the platform. The API key that created the task and real provider credentials are never exposed inside it.

When the sandbox is destroyed:

• temporary processes and unsaved workspace state disappear;
• saved files and eligible owner-scoped memory remain;
• the conversation remains as immutable evidence; and
• observations, patterns, feedback, and judgements remain available for investigation and improvement.

See State and artifacts for persistence and Security for the isolation boundary.

A minimal task

Create one production task through the stable runtime slug:

introspection tasks create \
  --runtime refund-exception-agent \
  --environment production \
  --subject customer-operations-001 \
  --prompt "Review order 1842 against the refund policy and draft the next response."
 
introspection tasks stream <task-id> --run <run-id> --since 0
introspection tasks get <task-id>
introspection conversations get <conversation-id>

import {
  EventType,
  IntrospectionClient,
} from "@introspection-sdk/introspection-node";
 
const client = new IntrospectionClient();
const runner = await client.runtimes("refund-exception-agent").run({
  identity: { user_id: "customer-operations-001" },
});
const handle = await runner.tasks.start({
  prompt: "Review order 1842 against the refund policy and draft the next response.",
});
 
for await (const event of handle.stream()) {
  if (event.type === EventType.TEXT_MESSAGE_CONTENT) {
    process.stdout.write(event.delta ?? "");
  }
}
 
const task = await runner.tasks.get(handle.run.task_id);
const conversationId = task.metadata?.conversation_id;
if (typeof conversationId !== "string") throw new Error("No conversation");
const conversation = await runner.conversations.exportJson(conversationId);

The SDK credential selects the environment lane; the SDK call does not take an environment option. The member-authenticated CLI names the lane explicitly.

The task creation response names the task and initial run. For an agent task, task.metadata.conversation_id points to the exact conversation produced by that task. Use it instead of selecting an arbitrary recent conversation.

The useful checkpoint is not only status: completed. Confirm metadata.completion_reason = "task_completion", the intended runtime version and recipe commit, and the expected conversation outcome.

Selecting a model for one task

A task can override the model and reasoning tier its agent declares, using two keys on the metadata bag it already sends:

introspection tasks create \
  --runtime refund-exception-agent \
  --environment production \
  --prompt "Review order 1842 against the refund policy." \
  --metadata '{"model": "anthropic/claude-opus-4-5", "thinking_level": "high"}'

const handle = await runner.tasks.start({
  prompt: "Review order 1842 against the refund policy.",
  metadata: { model: "anthropic/claude-opus-4-5", thinking_level: "high" },
});

The two keys are independent. A task may change the model, the reasoning tier, or both, and a key left out keeps the agent’s own value.

The override reaches the agent that runs the task and nothing else. Subagents keep the models their recipe declares, so a recipe that pins a cheaper model to a delegated role keeps that choice. The selection also belongs to the task it was created with; it is not inherited by any other task.

The model binds when the sandbox starts, which makes this a decision taken at creation. Changing the value on a task that is already running has no effect — a different model means a new task.

Diagnosing a task

Fetch the exact task row first and read its status, completion_reason, error, resolved runtime, environment, and conversation ID. A task with no conversation may have failed before its sandbox emitted a trace. Queueing, human interrupts, cancellation, reconnect, and pre-sandbox failures are covered in Task operations.

Production application minimum

An application integrating tasks should:

• derive identity.user_id from its authenticated user session rather than untrusted request input;
• persist the task and run IDs needed to reattach after a disconnect;
• resume a stream from the last event ID instead of creating duplicate work;
• distinguish aborting the active turn from ending the task; and
• close runners and clients when the application is finished with them.

A disconnected stream does not cancel server work. Likewise, cancelling one run does not necessarily destroy the task or sandbox. The detailed status, queue, interrupt, cancellation, reconnect, and diagnosis contracts are in Task operations.

Continue

• Task operations: statuses, queues, human interrupts, cancellation modes, reconnect, and diagnosis.
• JS SDK: create, stream, resume, and control tasks.
• Conversations: inspect the durable record of the work.
• State and artifacts: persist files and memory.