Strands Agents (TypeScript): Hooks, Interventions and Interrupts
Extending the TypeScript Strands agent loop: typed hook events and their writable fields, plugins, intervention handlers, human-in-the-loop interrupts, retry strategies and middleware.
Checked against @strands-agents/sdk 1.24.0 (2026-11-19). Examples compile under tsc --strict and were run against an offline Bedrock stub.
The layers are the same as in Python: hooks observe and adjust the loop, plugins bundle hooks and tools, intervention handlers make policy decisions, and interrupts pause for a human. The main API difference is that hooks are registered with agent.addHook(EventClass, callback) rather than passed to the constructor.
Hook events
Section titled “Hook events”| Event | Fires | Writable |
|---|---|---|
InitializedEvent | After the agent initialises | |
BeforeInvocationEvent | Start of each invoke() / stream() | cancel |
AfterInvocationEvent | End of each call | resume (start another call with this input) |
MessageAddedEvent | A message was appended | |
BeforeModelCallEvent | Before each model call | cancel |
AfterModelCallEvent | After each model call (stopData or error, attemptCount) | retry |
BeforeToolsEvent | Before a batch of tool calls | cancel |
BeforeToolCallEvent | Before each tool call | toolUse, selectedTool, cancel |
AfterToolCallEvent | After each tool call (result, error) | result, retry |
AfterToolsEvent | After the batch | endTurn |
Each event has agent and invocationState. The fields that are not writable are readonly in the type definitions, so the compiler stops you. After* callbacks run in reverse registration order.
import { Agent, AfterInvocationEvent, AfterToolCallEvent, BeforeToolCallEvent, tool } from '@strands-agents/sdk'import { z } from 'zod'
const deleteBucket = tool({ name: 'delete_bucket', description: 'Delete an S3 bucket', inputSchema: z.object({ bucket: z.string() }), callback: ({ bucket }) => `deleted ${bucket}`,})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [deleteBucket], printer: false })
// Block destructive tools for read-only callers; the model receives the message as an error resultagent.addHook(BeforeToolCallEvent, (event) => { if (event.invocationState.readOnly === true && event.toolUse.name.startsWith('delete_')) { event.cancel = `Tool ${event.toolUse.name} is not allowed for read-only users.` }})
// Audit logagent.addHook(AfterToolCallEvent, (event) => { console.log(JSON.stringify({ tool: event.toolUse.name, status: event.result.status, failed: event.error !== undefined }))})
const removeCounter = agent.addHook(AfterInvocationEvent, (event) => { console.log(`messages in history: ${event.agent.messages.length}`)})
await agent.invoke('Delete the bucket called scratch-data.', { invocationState: { readOnly: true } })removeCounter() // addHook returns a function that removes the hookaddHook(Event, callback, { order }) sets priority (lower runs first). Callbacks may be async.
Retrying a tool call
Section titled “Retrying a tool call”import { Agent, AfterToolCallEvent, tool } from '@strands-agents/sdk'import { z } from 'zod'
let attempts = 0const flakyLookup = tool({ name: 'flaky_lookup', description: 'Look up a key in a flaky service.', inputSchema: z.object({ key: z.string() }), callback: ({ key }) => { attempts += 1 if (attempts < 3) throw new Error('service unavailable') return `value for ${key}` },})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [flakyLookup], printer: false })
agent.addHook(AfterToolCallEvent, (event) => { const retries = (event.invocationState.toolRetries as number | undefined) ?? 0 if (event.error && retries < 3) { event.invocationState.toolRetries = retries + 1 event.retry = true }})
await agent.invoke("Look up 'alpha'")console.log(`tool ran ${attempts} times`)Plugins
Section titled “Plugins”A plugin is any object with a name and an initAgent(agent) method that registers hooks; an optional getTools() adds tools:
import { Agent, BeforeModelCallEvent, tool } from '@strands-agents/sdk'import type { LocalAgent, Plugin } from '@strands-agents/sdk'import { z } from 'zod'
class ModelCallCounter implements Plugin { readonly name = 'model-call-counter' count = 0
initAgent(agent: LocalAgent): void { agent.addHook(BeforeModelCallEvent, () => { this.count += 1 }) }
getTools() { return [ tool({ name: 'model_call_count', description: 'How many model calls this agent has made.', inputSchema: z.object({}), callback: () => this.count, }), ] }}
const counter = new ModelCallCounter()const agent = new Agent({ model: 'us.anthropic.claude-haiku-5-5', plugins: [counter], printer: false })await agent.invoke('Hi')console.log(`model calls: ${counter.count}`, agent.tools.map((t) => t.name))Ready-made plugins live under @strands-agents/sdk/vended-plugins/*: skills (Agent Skills from SKILL.md folders), context-injector, goal and context-offloader. The last three are shown below; they behave like their Python counterparts.
Context injection
Section titled “Context injection”ContextInjector adds text to the model input for one call without storing it in agent.messages or the session, which suits values that go stale, such as the current time. renderContent returns the text, or undefined to skip. The default trigger, 'userTurn', injects only for a fresh user message; 'everyTurn' injects before every model call, and a function gives finer control:
import { Agent } from '@strands-agents/sdk'import { ContextInjector } from '@strands-agents/sdk/vended-plugins/context-injector'
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', plugins: [new ContextInjector({ renderContent: async () => `<now>${new Date().toISOString()}</now>` })], printer: false,})
await agent.invoke('What time is it?')console.log(JSON.stringify(agent.messages[0]?.content)) // only the user's text: the injected block is not keptThe text reaches the model verbatim, so escape any field a user influences.
Goal loops
Section titled “Goal loops”GoalLoop re-runs the agent until its answer meets a goal. After each invocation it checks the answer; if the check fails, it sends the feedback back as a new user message and continues, until the goal is met, maxAttempts is reached, timeout (milliseconds) elapses or one of the call’s limits is hit. The goal is a sentence judged by a model, or a function returning true, false or { passed, feedback }:
import { Agent } from '@strands-agents/sdk'import type { Message } from '@strands-agents/sdk'import { GoalLoop } from '@strands-agents/sdk/vended-plugins/goal'
const atMostFiftyWords = (response: Message) => { const text = response.content.map((block) => (block.type === 'textBlock' ? block.text : '')).join(' ') const words = text.split(/\s+/).filter(Boolean).length return words <= 50 ? true : { passed: false, feedback: `Too long (${words} words). Cut it to 50 words or fewer.` }}
const goal = new GoalLoop({ goal: atMostFiftyWords, maxAttempts: 3, timeout: 60_000 })const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', plugins: [goal], printer: false })
console.log((await agent.invoke('Explain how a rainbow forms.')).toString())console.log(goal.lastResult(agent)) // { passed, stopReason: 'satisfied' | 'maxAttempts' | 'timeout' | 'limit', attempts }maxAttempts and timeout both default to unlimited, so set at least one. A second GoalLoop on the same agent throws, because both would use AfterInvocationEvent.resume.
Offloading large tool results
Section titled “Offloading large tool results”ContextOffloader intercepts tool results above maxResultTokens (2,500 by default), saves the full content to a storage backend and leaves the model a preview of previewTokens (1,000 by default). With includeRetrievalTool (on by default) the model also gets a retrieve_offloaded_content tool that fetches a pattern match or a line range. Stored content is deleted after evictAfterCycles agent-loop cycles (20 by default; null disables it). The module exports InMemoryStorage, FileStorage and S3Storage for the content:
import { Agent, tool } from '@strands-agents/sdk'import { ContextOffloader, InMemoryStorage } from '@strands-agents/sdk/vended-plugins/context-offloader'import { z } from 'zod'
const bigReport = tool({ name: 'big_report', description: 'Return the full nightly report.', inputSchema: z.object({}), callback: () => 'line of report data\n'.repeat(4000),})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [bigReport], plugins: [new ContextOffloader({ storage: new InMemoryStorage(), maxResultTokens: 500, previewTokens: 100 })], printer: false,})
await agent.initialize() // plugins add their tools when the agent initialisesconsole.log(agent.tools.map((t) => t.name)) // [ 'big_report', 'retrieve_offloaded_content' ]await agent.invoke("Summarise tonight's report.")Interventions
Section titled “Interventions”Subclass InterventionHandler, set name, and override beforeInvocation, beforeModelCall, afterModelCall, beforeToolCall or afterToolCall. Return an action from InterventionActions: proceed(), deny(reason), guide(feedback), confirm(prompt) (before tool calls only) or transform(fn):
import { Agent, BeforeToolCallEvent, InterventionActions, InterventionHandler, tool } from '@strands-agents/sdk'import { z } from 'zod'
const { confirm, deny, proceed } = InterventionActions
const deleteBucket = tool({ name: 'delete_bucket', description: 'Delete an S3 bucket', inputSchema: z.object({ bucket: z.string() }), callback: ({ bucket }) => `deleted ${bucket}`,})
class Approvals extends InterventionHandler { readonly name = 'approvals'
override beforeToolCall(event: BeforeToolCallEvent) { if (!event.toolUse.name.startsWith('delete_')) return proceed() if (event.invocationState.readOnly === true) return deny('read-only caller') return confirm(`Allow ${event.toolUse.name} with ${JSON.stringify(event.toolUse.input)}?`) }}
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [deleteBucket], interventions: [new Approvals()], printer: false,})
let result = await agent.invoke('Delete the bucket called scratch-data')if (result.stopReason === 'interrupt' && result.interrupts?.[0]) { const pending = result.interrupts[0] console.log(pending.name, '-', pending.reason) result = await agent.invoke([{ interruptResponse: { interruptId: pending.id, response: 'yes' } }])}console.log(result.toString())Handlers run in order and a deny stops evaluation, so put cheap checks first. onError ('throw' by default, 'deny', 'proceed') decides what a failing handler does. @strands-agents/sdk/vended-interventions/hitl, /cedar and /steering provide ready-made handlers.
Interrupts
Section titled “Interrupts”An interrupt pauses the agent with stopReason === 'interrupt' and result.interrupts (each with id, name, reason). Resume by invoking the agent with interruptResponse blocks; the paused tool or hook runs again and interrupt() returns the response.
From a tool
Section titled “From a tool”import { Agent, tool } from '@strands-agents/sdk'import type { ToolContext } from '@strands-agents/sdk'import { z } from 'zod'
const refund = tool({ name: 'refund', description: 'Refund an order.', inputSchema: z.object({ orderId: z.string(), amount: z.number().describe('Amount in GBP') }), callback: ({ orderId, amount }, context?: ToolContext) => { if (!context) throw new Error('tool context required') if (amount > 100) { const decision = context.interrupt<string>({ name: 'refund-approval', reason: { orderId, amount } }) if (decision !== 'approve') return `Refund of £${amount} for ${orderId} was not approved` } return `Refunded £${amount} for ${orderId}` },})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [refund], printer: false })let result = await agent.invoke('Refund £250 on ORD-7')
while (result.stopReason === 'interrupt') { const responses = (result.interrupts ?? []).map((pending) => ({ interruptResponse: { interruptId: pending.id, response: 'approve' }, // from a UI, ticket or queue })) result = await agent.invoke(responses)}console.log(result.toString())Code before interrupt() runs again on resume, so keep side effects after it. With a SessionManager, the pending interrupt is saved with the agent, so a new agent with the same session ID can be resumed in a later request.
From a hook
Section titled “From a hook”BeforeToolCallEvent and BeforeToolsEvent implement the same interrupt():
import { Agent, BeforeToolCallEvent, tool } from '@strands-agents/sdk'import { z } from 'zod'
const sendEmail = tool({ name: 'send_email', description: 'Send an email.', inputSchema: z.object({ to: z.string(), body: z.string() }), callback: ({ to }) => `sent to ${to}`,})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [sendEmail], printer: false })
agent.addHook(BeforeToolCallEvent, (event) => { if (event.toolUse.name !== 'send_email') return const answer = event.interrupt<string>({ name: 'approve-email', reason: event.toolUse.input }) if (answer !== 'yes') event.cancel = 'Email not approved'})
const first = await agent.invoke('Email ops@example.com that the deploy finished')const id = first.interrupts?.[0]?.idif (id) { const resumed = await agent.invoke([{ interruptResponse: { interruptId: id, response: 'yes' } }]) console.log(resumed.stopReason, resumed.toString())}Retry strategies
Section titled “Retry strategies”The default retryStrategy is a DefaultModelRetryStrategy: 6 attempts with exponential backoff from 4 seconds to 240 seconds, for ModelThrottledError only. Shorten it for interactive use:
import { Agent, DefaultModelRetryStrategy, ExponentialBackoff } from '@strands-agents/sdk'
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', retryStrategy: new DefaultModelRetryStrategy({ maxAttempts: 3, backoff: new ExponentialBackoff({ baseMs: 500, maxMs: 4_000, jitter: 'full' }), }), printer: false,})retryStrategy: null disables retries. ConstantBackoff and LinearBackoff are the other backoff shapes; subclass ModelRetryStrategy (and override isRetryable) to retry other errors. A strategy instance belongs to one agent.
Middleware
Section titled “Middleware”Middleware wraps a stage: InvokeModelStage (a model call) or ExecuteToolStage (a tool call). A wrap handler is an async generator that delegates to next with yield* and can act before and after; .Input and .Output sub-stages transform the context or the result:
import { Agent, ExecuteToolStage, InvokeModelStage, tool } from '@strands-agents/sdk'import { z } from 'zod'
const lookup = tool({ name: 'lookup', description: 'Look up a term.', inputSchema: z.object({ term: z.string() }), callback: ({ term }) => `${term}: defined`,})
const agent = new Agent({ model: 'us.anthropic.claude-sonnet-5-5', tools: [lookup], printer: false })const timings: number[] = []
agent.addMiddleware(InvokeModelStage, async function* (context, next) { const started = performance.now() const result = yield* next(context) timings.push(performance.now() - started) return result})
agent.addMiddleware(ExecuteToolStage.Input, (context) => { console.log('running tool', context.toolUse.name) return context})
await agent.invoke("Define 'idempotent'")console.log(`${timings.length} model call(s)`)addMiddleware returns a function that removes the handler.
Revision history
Section titled “Revision history”| Date | Version | Changes |
|---|---|---|
| 2026-10-24 | 1.24.0 | Audit against the installed packages. Added examples for ContextInjector, GoalLoop and ContextOffloader. |
| 2026-10-24 | 1.22.0 | New page, from the hooks section of the TypeScript Strands page in the Amazon Bedrock guide. Adds the event table with writable fields, tool retries, plugins with tools, intervention handlers, interrupts from tools and hooks, retry strategy defaults and middleware. |