defineAgentTask

import { defineAgentTask } from "@elie-laloum/outpost";

Purpose and behavior

Declare a task that runs sandbox.dispatch() in a sandbox you opened and keep open; request builds the dispatch options at each attempt. The output is the dispatch result with its resume() and fork() methods, so a checkpointed run must wrap the task in a defineTask() that returns JSON. Usage joins the workflow budget; cache is rejected.

Complete example and detailed rules.

Parameters and properties

optionsRequired
Omit<TaskOptions<DispatchResult<T>>, "cache" | "perform"> & AgentTaskOptions<T>
Task scheduling settings, existing sandbox and dispatch-request factory.
options.retryOptional
Retry | undefined
Retry policy for failed attempts; without it the task runs once. A retried attempt repeats its side effects.
options.gateOptional
WorkflowGate | undefined
Persisted approval or pause definition; execution requires a checkpoint and a matching trusted decision.
options.keyRequired
string
Unique key in the workflow, matching [A-Za-z0-9][A-Za-z0-9._-]*. Records, events and checkpoints identify the task by it.
options.afterOptional
readonly Task<unknown>[] | undefined
Tasks that must be done before this one starts, default none; only these can be read with context.value().
options.interactionOptional
TaskInteraction | undefined
Opt-in durable human-input contract; requires checkpointed scheduling and cannot be combined with a gate.
options.conditionOptional
((context: TaskContext) => boolean | Promise<boolean>) | undefined
Evaluated with attempt 0 before the task runs, including when a later start() resumes it; false ends the task as skipped, which skips its dependents.
options.timeoutMsOptional
number | undefined
Deadline in milliseconds for each attempt, a positive integer up to 2147483647. Expiry aborts context.signal and fails the attempt, which retry may repeat.
options.sandboxRequired
Sandbox
Existing caller-owned sandbox reused by the task; the task does not close it.
options.requestRequired
(context: TaskContext) => DispatchOptions<T>
Build dispatch options from task dependencies for the existing sandbox.
options.quotaResumeOptional
QuotaResumePolicy | undefined
After a quota pause, continue the captured conversation with a resume instruction (continue, default) or send the original request again (restart). The original request is sent when the agent cannot resume or is a fallback agent, or when the request sets continuation or several passes.

Returns

Task<DispatchResult<T>>

Signature

export declare function defineAgentTask<T>(
  options: Omit<TaskOptions<DispatchResult<T>>, "perform" | "cache"> &
    AgentTaskOptions<T>,
): Task<DispatchResult<T>>;

Purpose and behavior

Parameters and properties

Returns

Signature

Related contracts