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.
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.