Building Agents
Tasks
Durable child or delegated agent runs.
A task is a child or delegated agent run. Tasks let an agent split work into named, durable sub-runs that can be inspected, cancelled, and (on the Temporal target) replayed independently.
Spawn a task
const result = await session.task('Refactor the authentication middleware', {
id: 'refactor-auth',
result: schema.object({
filesChanged: schema.array(schema.string()),
summary: schema.string(),
}),
});Options:
| Option | Purpose |
|---|---|
id | Stable id (good for resuming, dedup, and CLI inspection). |
result | Schema for typed output validation. |
model | Override the model for this task. |
commands | Scope shell commands available inside the task. |
Inspect or cancel from the CLI
fh tasks <session-id>
fh task <session-id> refactor-auth
fh cancel-task <session-id> refactor-auth --actor preetham --reason "Replaced by manual fix"Durable tasks on the Temporal target
When the session runs on the Temporal worker target, each task becomes a child workflow. That gives you:
- crash-safe execution,
- retries for model and tool calls,
- replayable history,
- durable cancellation signals.
Checkpoints inside a task
Tasks can mark their own progress with checkpoints:
await session.checkpoint.create({ label: 'before-fix' });
// ... risky work ...
await session.checkpoint.create({ label: 'after-fix' });If the sandbox supports snapshots, the checkpoint records a snapshot ref so you can restore filesystem state along with the conversation state.