InvokeOptions

Defined in: src/types/agent.ts:95

Options for a single agent invocation.

Properties

structuredOutputSchema?

structuredOutputSchema?: ZodSchema;

Defined in: src/types/agent.ts:99

Zod schema for structured output validation, overriding the constructor-provided schema for this invocation only.

---

invocationState?

invocationState?: InvocationState;

Defined in: src/types/agent.ts:108

Per-invocation state. Passed to lifecycle hook events and tools, and returned on AgentResult.invocationState. Mutable — hooks and tools may read and write. See InvocationState for details.

Defaults to an empty object when omitted.

---

cancelSignal?

cancelSignal?: AbortSignal;

Defined in: src/types/agent.ts:138

External AbortSignal for cancelling the agent invocation.

Use this when cancellation is driven by something outside the agent — for example, a client disconnect, a framework-managed request lifecycle, or a declarative timeout. The agent composes this signal with its own internal controller, so both agent.cancel() and this signal can trigger cancellation independently.

When the signal fires, the agent stops at the next cancellation checkpoint and returns an AgentResult with stopReason: 'cancelled'. See LocalAgent.cancelSignal for how tools can participate in cancellation.

Example

// Timeout-based cancellation
const result = await agent.invoke('Hello', {
  cancelSignal: AbortSignal.timeout(5000),
})

// Framework-driven cancellation (e.g., client disconnect)
app.post('/chat', async (req, res) => {
  const result = await agent.invoke(req.body.message, {
    cancelSignal: req.signal,
  })
  res.json(result)
})

---

invocationContext?

invocationContext?: InvocationContext;

Defined in: src/types/agent.ts:141

Runs this call as a nested call in the request a hook event’s or ToolContext.invocationContext handle belongs to, sharing its limits and usage even after that request returned; limits set alongside it only add stricter limits.

---

limits?

limits?: InvokeLimits;

Defined in: src/types/agent.ts:173

Limits for the whole request this invoke() / stream() call starts. They apply to this agent’s loop and to every nested call: agents passed as tools, and any Graph or Swarm you pass the request’s invocationContext to. A Graph or Swarm can also start a limited request itself through MultiAgentInvokeOptions.limits. An agent run by a hand-written tool joins only when the tool forwards ToolContext.invocationContext as InvokeOptions.invocationContext; otherwise it runs standalone under its own limits. A nested call can also set its own limits: it stops at whichever limit is reached first, its own or the request’s.

Auxiliary calls (summarization, routing, memory extraction, steering, HITL, goal judging, web-fetch, and decision models asked with the request’s invocationContext) add their tokens to the request’s usage, but no limits apply to them. The same holds for an agent that an extension point (a conversation manager, context or routing strategy, or memory extractor) runs with the invocationContext it receives, unless the extension point also passes limits. Usage starts from zero on each top-level call; pass AgentResult.invocationContext to a later call to continue on the same limits and usage.

Limits are checked before each turn, so tools requested by the previous turn finish first and agent.messages stays reinvokable. Each limit, when set, must be a positive finite number; omit a field (or limits itself) for no limit on that dimension.

Priority when several are reached at once (highest first): turns, totalTokens, outputTokens, with stopReason 'limitTurns', 'limitTotalTokens', or 'limitOutputTokens'.