Blog · · 9 min read

Cancel in-flight AI agent tool call work without orphaning side effects or breaking session context

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:

  1. Capture a cancel intent. Stop click, SSE disconnect, and out-of-band cancel endpoint each produce a typed intent bound to run_id and a monotonic cancel generation.
  2. Hard-abort the model stream. Pass AbortSignal into the provider stream so tokens stop immediately (Google ADK cancel docs; MDN AbortController).
  3. 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).
  4. Propagate into handlers. Plumb AbortSignal or a cancellation token into every tool invocation so session.abort() is not acknowledgement-only (Copilot SDK #1433).
  5. Patch context. Every interrupted tool_use gets an explicit interrupted tool_result before the next model call.
  6. Sweep claimed runs. Compensate or finalize tool runs left in claimed after 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 in ToolInvocation (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.

ClassExamplesOn StopSignal policy
Immediatesearch, read ticket, fetch docsAbort I/O nowPass signal into fetch / SDK calls
CheckpointCRM update, ticket transitionFinish current unit, then refuse next turnDo not pass signal into the write provider
Compensatablecache warm, draft-only staging rowsAbort allowed if a compensate handler existsPass 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:

  1. Explicit Stop. User clicks the square button. Intent is cancel with user attribution.
  2. 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).
  3. Out-of-band cancel. After reload, the original AbortController is 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_use without a matching result before calling the model again.
  • Never store truncated JSON as a successful result. If the stream died mid-object, set status: interrupted and side_effects: unknown until 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:

  1. Insert claimed before the side effect.
  2. Execute the tool under the class rules above.
  3. Mark finalized with a result hash, or interrupted with a cancel generation.
  4. On cancel, select rows still claimed and run compensate or mark unknown for 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

FailureProduct response
Stop during read toolAbort I/O, patch interrupted result, end turn
Stop during checkpoint writeLet write finish, finalize receipt, refuse next planning turn
Disconnect without StopApply disconnect policy; default for orphan-sensitive products is cancel flag
Reload mid-runRehydrate from durable events; Stop hits out-of-band cancel endpoint
Handler ignores signalFail CI: every immediate tool must demonstrate early exit under abort
Concurrent tools ignore interruptInject shared cancellation token; do not rely on Future.cancel() (hermes-agent#28809)
Truncated tool JSON persistedReject at patch layer; store interrupted marker only
Cancel during persistenceasyncio.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:

  1. Immediate tool abort. Start a slow read tool, click Stop, assert handler exits within your SLO and no further model turn starts.
  2. 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.
  3. Reload cancel. Start a run, reload the tab, click Stop on the rehydrated UI, assert the background loop observes the out-of-band flag.
  4. 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.
  5. Concurrent tools. Fire three long tools, interrupt, assert cooperative token stops workers that opted in rather than waiting for full completion (hermes-agent#28809).
  6. Receipt audit. After cancel, query CancelReceipt for 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

  1. Aborting fetch and assuming the server stopped. The server must observe request.signal or an out-of-band flag and check it between turns (AgentNotebook).
  2. Passing signal into every tool. Payments and outbound email should finish their current unit under checkpoint policy.
  3. 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).
  4. Logging AbortError as a server alert. Stop is a normal end state for interactive agents.
  5. Persisting partial streamed tool JSON as success. That is how later turns break.
  6. 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.

Be first in line.

Join the waitlist and we'll email you the moment it's ready. No sales call.

Try the demo →
or talk to us