> ## Documentation Index
> Fetch the complete documentation index at: https://hastekit.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Background tools

> Start long-running work and deliver its result to the conversation later.

A background tool returns an acknowledgement immediately while its work continues. Completion is delivered to the original thread, either into an active run or through a new run. This differs from [deferred tools](/docs/hastekit-sdk/agents/tools/deferred-tools), which defer schema discovery rather than execution.

## Choose a tool API

`hastekit.NewBackgroundTool` accepts `func(context.Context, In, hastekit.ProgressReporter) (Out, error)` and the same naming/description options as a function tool. The runtime runs that work separately and encodes its result for the conversation.

For an external job with separate start and wait operations, implement `agents.BackgroundTool`: `Execute` starts it, and `AwaitTask` waits for completion. Put the external task identity and continuation data in the serialized task payload; do not depend on a closure created during the initial call.

## Lifetime and state

Local agents use an in-process supervisor, so background work does not survive process loss. Temporal and Restate provide their own background runners. A custom durable runtime without a runner must not silently accept work it cannot complete.

Report progress through the supplied reporter, and pass the context to blocking work. Completion and progress have their own broker stream and thread identity. Keep the original namespace and session boundaries when delivering results.

Make the external job submission and completion handling idempotent if the durable execution can retry. Stopping a wait or short-circuiting it in middleware does not necessarily cancel a job already submitted to another service.

## Tasks waiting for human input

`BackgroundResult.Waiting` means the task is still pending. Nothing is delivered to the model, and the runner calls `AwaitTask` again with a delay starting at one second and capped at thirty seconds. Local, Temporal, and Restate runners support this state.

Async agent tools set `ToolCallResponse.TaskAgent` to identify the child agent and thread. When that child pauses, AG-UI exposes its interrupts in the parent's background task entry. Answer on the child's thread; the task completes after that conversation finishes. See [sub-agents](/docs/hastekit-sdk/agents/multi-agents/sub-agents).

`BackgroundTaskRef` preserves the originating namespace, session, run context, skills, MCP selection, and client tool definitions for a continuation. Progress uses the task's own stream; completion is delivered to the parent thread as new input rather than a second result for the already-answered tool call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.