Blog · · 9 min read
Cancel in-flight AI agent tool call work without orphaning side effects or breaking session context

A user clicks Stop while your product agent is writing a CRM note or charging a card. Aborting only the browser fetch can leave a half-written row or an unreceipted charge. Letting every tool finish creates orphan work after the user has left. To cancel in-flight AI agent tool call work safely, treat Stop as a product-owned contract: hard-abort the model stream, classify which tools may stop immediately, propagate cooperative cancel into handlers, patch interrupted tool results so the next turn stays valid, and keep an out-of-band cancel path that survives reload.
Direct answer: the cancel lifecycle
Ship one lifecycle instead of a single AbortController on fetch:
- Capture a cancel intent. Stop click, SSE disconnect, and out-of-band cancel endpoint each produce a typed intent bound to
run_idand a monotonic cancel generation. - Hard-abort the model stream. Pass
AbortSignalinto the provider stream so tokens stop immediately (Google ADK cancel docs; MDN AbortController). - Classify every tool. Read-only tools honor the signal mid-flight. Write tools ignore the signal until a safe checkpoint, then refuse the next model turn (AgentNotebook hard vs cooperative cancel).
- Propagate into handlers. Plumb
AbortSignalor a cancellation token into every tool invocation sosession.abort()is not acknowledgement-only (Copilot SDK #1433). - Patch context. Every interrupted
tool_usegets an explicit interruptedtool_resultbefore the next model call. - Sweep claimed runs. Compensate or finalize tool runs left in
claimedafter cancel, then emit a durable cancel receipt the UI and audit log share.
Why Stop is harder than aborting a fetch
A product chat turn spans more than one HTTP request. It fans into a planning stream, one or more tool calls, and another model turn. AgentNotebook's tutorial shows the concrete failure: killing the HTTP request while a tool is mid-write can leave a partial row, a duplicate charge, or a sent email with no record (AgentNotebook).
Frameworks still leave the same seams open:
- GitHub Copilot SDK consumers reported that
session.abort()cancels further scheduling but does not propagate into a currently executing tool handler, forcing OS-level process-tree kills until AbortSignal lands inToolInvocation(copilot-sdk#1433). - Hermes-agent shows that
Future.cancel()returns false for already-running concurrent tools, so interrupt and steer wait until workers finish unless tools poll a cooperative token (hermes-agent#28809). - AgentScope's interrupt design adds Stop API and SSE-disconnect auto-interrupt, and a follow-on bug shows truncated interrupted tool JSON breaking later turns when context is not patched (agentscope#1806).
Google ADK documents the mechanism layer: pass AbortSignal to runner.runAsync(), propagate into Gemini requests and MCP tools, and expose toolContext.abortSignal inside custom tools (ADK). Product hosts still need the lifecycle around that primitive: intent typing, write-tool policy, reload survival, and conversation validity.
Classify tools before you wire AbortSignal
Classify tools as immediately cancellable versus checkpoint-only; never pass AbortSignal into a payment or email write mid-flight.
| Class | Examples | On Stop | Signal policy |
|---|---|---|---|
| Immediate | search, read ticket, fetch docs | Abort I/O now | Pass signal into fetch / SDK calls |
| Checkpoint | CRM update, ticket transition | Finish current unit, then refuse next turn | Do not pass signal into the write provider |
| Compensatable | cache warm, draft-only staging rows | Abort allowed if a compensate handler exists | Pass signal, register compensate on claimed |
AgentNotebook's rule is the product default: hard-abort the model stream, cooperatively cancel the tools. Interrupting Claude mid-token wastes output. Interrupting chargeCard mid-call can cost a customer real money (AgentNotebook).
Put the class in tool metadata the runtime owns, not in prompt text:
ToolDescriptor {
name
cancellability: immediate | checkpoint | compensatable
compensate?: (claimed_run) -> void
side_effect_class: none | soft | external_irreversible
}
Refuse to register an external_irreversible tool as immediate. If a vendor SDK only exposes fire-and-forget writes, mark the tool checkpoint and gate Stop as "finish current write, then stop."
Capture cancel intents the UI and server share
Treat browser disconnect and Stop as different cancel intents unless you deliberately unify them with an out-of-band flag.
Three triggers reach production chats:
- Explicit Stop. User clicks the square button. Intent is cancel with user attribution.
- Transport disconnect. Tab close, network drop, or SSE generator exit. Intent may be cancel-or-continue depending on product policy. AgentScope explicitly calls for SSE-disconnect auto-interrupt so orphan tasks do not keep spending tokens when no client is listening (agentscope#1806).
- Out-of-band cancel. After reload, the original
AbortControlleris gone. A second request must set a per-conversation cancel flag the loop checks at checkpoints (AgentNotebook).
Do not pretend these are identical unless you choose that policy:
CancelIntent {
run_id
generation
source: stop_button | sse_disconnect | out_of_band | timeout
actor_user_id?
created_at
}
For support agents that must finish a ticket write the user already approved, disconnect can mean "continue checkpoint tools, stop further planning." For consumer chats where orphan spend is worse than incomplete writes, disconnect should publish the same cancel flag as Stop. Write the policy down and test both paths.
Propagate AbortSignal through the whole stack
MDN defines AbortController as the shared primitive for aborting fetch, response body consumption, and streams (MDN). ADK shows how a product runner should use it: create a controller, pass abortSignal into the run, and check toolContext.abortSignal.aborted before expensive tool steps (ADK).
Minimum plumbing for an existing product host:
Browser Stop
-> controller.abort()
-> fetch(..., { signal })
Server request.signal
-> modelStream({ signal }) # hard abort
-> for tool in planned_tools:
if tool.cancellability == immediate:
run(tool, { signal })
else:
run(tool, { signal: null }) # finish write
if cancelled(run_id): break # cooperative checkpoint
Out-of-band POST /runs/{id}/cancel
-> set cancel_flags[run_id]
-> same checkpoint path
Copilot SDK's open request is the negative test for your own stack: if abort() only acknowledges and handlers keep running, you do not have cancellation yet (copilot-sdk#1433). Hermes shows the concurrent case: cancelling futures that have already started is a no-op, so every long-running tool needs yield-point checks (hermes-agent#28809).
Patch interrupted tool results before the next turn
Patch every interrupted tool_use with an explicit interrupted tool_result before the next model turn, or truncated JSON will break the session.
Providers and frameworks expect paired tool calls. AgentScope's interrupt design normalizes cancellation at the model and tool layers into is_interrupted results and requires unmatched tool_call blocks to be patched so later turns do not raise (agentscope#1806). A follow-on failure mode is truncated streaming tool JSON persisted as if it were complete.
Use a fixed patch shape your product owns:
ToolResult {
tool_call_id
status: interrupted
partial_payload? # only if validated
reason: user_stop | disconnect | out_of_band | handler_abort
side_effects: none | committed | unknown
cancel_generation
}
Rules:
- Never leave a
tool_usewithout a matching result before calling the model again. - Never store truncated JSON as a successful result. If the stream died mid-object, set
status: interruptedandside_effects: unknownuntil reconciliation. - Shield persistence of the patched message from the cancel task itself, so the cancel path cannot delete the evidence the next turn needs (agentscope#1806).
Claim, finalize, and compensate
Safe cancel needs the same claim pattern durable agents already use for retries:
tool_runs:
id
run_id
tool_name
idempotency_key
status: claimed | finalized | interrupted | compensated
args_hash
result_hash?
Flow:
- Insert
claimedbefore the side effect. - Execute the tool under the class rules above.
- Mark
finalizedwith a result hash, orinterruptedwith a cancel generation. - On cancel, select rows still
claimedand runcompensateor markunknownfor human review (AgentNotebook claimed-run sweep).
Irreversible external writes that finished before cancel must stay finalized and appear in the cancel receipt. The UI should say "stopped after sending the email," not "nothing happened."
Handle failure and recovery
| Failure | Product response |
|---|---|
| Stop during read tool | Abort I/O, patch interrupted result, end turn |
| Stop during checkpoint write | Let write finish, finalize receipt, refuse next planning turn |
| Disconnect without Stop | Apply disconnect policy; default for orphan-sensitive products is cancel flag |
| Reload mid-run | Rehydrate from durable events; Stop hits out-of-band cancel endpoint |
| Handler ignores signal | Fail CI: every immediate tool must demonstrate early exit under abort |
| Concurrent tools ignore interrupt | Inject shared cancellation token; do not rely on Future.cancel() (hermes-agent#28809) |
| Truncated tool JSON persisted | Reject at patch layer; store interrupted marker only |
| Cancel during persistence | asyncio.shield / equivalent around message and session upserts |
ADK's cancellation semantics are useful here: committed events already yielded stay persisted; in-progress unyielded events are discarded; the generator completes without treating cancel as an exception storm (ADK). Mirror that in your product event log so reconnect and cancel do not fight each other. Resumable streams are a separate contract. Keep the cancel command distinct from disconnect so a dropped socket is not mistaken for an intentional Stop.
Verify the solution
Run these checks before calling Stop done:
- Immediate tool abort. Start a slow read tool, click Stop, assert handler exits within your SLO and no further model turn starts.
- Checkpoint write integrity. Start a CRM write tool, click Stop mid-flight, assert the write either finalizes with a receipt or never began; never assert both "cancelled" and "no row" when a row exists.
- Reload cancel. Start a run, reload the tab, click Stop on the rehydrated UI, assert the background loop observes the out-of-band flag.
- Context validity. Interrupt during tool streaming, then send a new user message; assert the model call succeeds and history contains interrupted markers for every tool_use.
- Concurrent tools. Fire three long tools, interrupt, assert cooperative token stops workers that opted in rather than waiting for full completion (hermes-agent#28809).
- Receipt audit. After cancel, query
CancelReceiptfor run_id, source, generation, finalized tool ids, interrupted tool ids, and compensated ids.
CancelReceipt {
run_id
cancel_generation
source
model_aborted: bool
tools_finalized[]
tools_interrupted[]
tools_compensated[]
context_patched: bool
}
Common mistakes
- Aborting fetch and assuming the server stopped. The server must observe
request.signalor an out-of-band flag and check it between turns (AgentNotebook). - Passing signal into every tool. Payments and outbound email should finish their current unit under checkpoint policy.
- Treating
session.abort()acknowledgement as handler cancel. Probe one long tool under abort; if it completes, your stack still matches the Copilot SDK failure mode (copilot-sdk#1433). - Logging AbortError as a server alert. Stop is a normal end state for interactive agents.
- Persisting partial streamed tool JSON as success. That is how later turns break.
- Equating disconnect with user Stop without a policy. Orphan spend and incomplete approved writes need different defaults.
What to do next
Pick one live product agent path that already has a Stop button. Add tool cancellability metadata, plumb AbortSignal into the model stream and immediate tools, add the out-of-band cancel flag, and ship the six verification checks above. When that path emits a complete CancelReceipt under Stop, disconnect, and reload, reuse the same contract for every other tool-using surface.
If you are building knowledge-grounded product agents and want the chat runtime, tool policy, and evaluation loop in one place, evaluate Make Your Agent against this cancel checklist rather than treating Stop as a UI-only control.