Async Tool Handle

Problem

A tool that waits for its slow work to finish before returning will breach the transport deadline, and the agent receives a timeout instead of a result. From the model's side the call simply failed, so it retries, fires the slow job again, or abandons the task. Meanwhile the agent loop is frozen on a single call and cannot make progress on anything else. Holding a synchronous connection open for the whole duration is fragile and wastes the turn.

Solution

Model the slow operation as two tools instead of one. The start tool validates the request, hands the work to a background worker or queue, and returns a job handle immediately, well inside the transport deadline. The background worker runs the job to completion and writes its status and result into a store keyed by the handle. A separate poll tool takes the handle and returns one of running, done with the result, or failed with an error. The agent calls the start tool, keeps working on other steps, and calls the poll tool when it needs the answer, treating a running reply as a signal to wait or do something else. Because the handle is durable, the result survives even if the agent run pauses or restarts between starting the job and collecting it.

When to use

• A tool wraps work that can take longer than the transport's tool-call deadline.
• The agent can usefully do other steps while the slow job runs, or the run may pause and resume before the result is needed.
• The slow work can run in a background worker and write its outcome to a store keyed by a handle.