humanInTheLoop | References | ArcGIS Maps SDK for JavaScript

ESM

import { createHumanInTheLoopMiddleware, createHumanInTheLoopToolMiddleware, getHumanInTheLoopPayload } from "@arcgis/ai-components/agent-utils/middlewares/humanInTheLoop.js";

Type definitions

HumanInTheLoopInterruptRequest

Type definition

Type parameters: <TCustomState extends AgentData = AgentData>

Since: ArcGIS Maps SDK for JavaScript 5.1

Supertypes: AgentRunRequest<TCustomState>

agentId

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 5.1

The ID of the agent requesting human intervention. This can be used to correlate the interrupt with a specific agent, especially in cases where multiple agents may be running concurrently and using the same middleware.

HumanInTheLoopInterrupt

Type definition

Since: ArcGIS Maps SDK for JavaScript 5.1

Supertypes: Partial<UiInterrupt>

HumanInTheLoopMiddlewareOptions

Type definition

Type parameters: <TCustomState extends AgentData = AgentData>

Since: ArcGIS Maps SDK for JavaScript 5.1

Options for configuring the HumanInTheLoopMiddleware.

interrupt

Method

Signature: interrupt (request: HumanInTheLoopInterruptRequest<TCustomState>): HumanInTheLoopInterrupt | Promise<HumanInTheLoopInterrupt>

Since: ArcGIS Maps SDK for JavaScript 5.1

An optional function that generates a custom interrupt object based on the agent run request. This allows for dynamic messages and metadata to be included in the interrupt, providing context to the user when prompting for input or approval.

If not provided, a default interrupt with a generic approval message will be used.

Parameters

Parameter	Type	Description	Required
request	HumanInTheLoopInterruptRequest	The agent run request that triggered the interrupt, containing details about the agent, node, and execution context.

Returns: HumanInTheLoopInterrupt | Promise<HumanInTheLoopInterrupt>
An object containing the interrupt details, which will be thrown as a NodeInterrupt to pause the agent's execution.

outputKey

Property

Type: keyof AgentGraphState | undefined

Since: ArcGIS Maps SDK for JavaScript 5.1

An optional key in the agent state where the human response should be stored.

HumanInTheLoopToolMessageRequest

Type definition

Type parameters: <TInput extends AgentData = AgentData>

Since: ArcGIS Maps SDK for JavaScript 5.1

Supertypes: FunctionToolMiddlewareRequest<TInput>

args

Property

Type: object

Since: ArcGIS Maps SDK for JavaScript 5.1

The arguments passed to the tool that is requesting human intervention.

toolCallId

Property

Type: string | undefined

Since: ArcGIS Maps SDK for JavaScript 5.1

The id of the tool call that is requesting human intervention.

toolName

Property

Type: string

Since: ArcGIS Maps SDK for JavaScript 5.1

The name of the tool that is requesting human intervention.

HumanInTheLoopToolMiddlewareOptions

Type definition

Type parameters: <TInput extends AgentData = AgentData>

Since: ArcGIS Maps SDK for JavaScript 5.1

This middleware is designed to allow for human intervention during agent execution by throwing an interrupt that can be handled by the orchestrator to pause the agent and prompt the user for input or approval.

interrupt

Method

Signature: interrupt (request: HumanInTheLoopToolMessageRequest<TInput>): HumanInTheLoopInterrupt | Promise<HumanInTheLoopInterrupt>

Since: ArcGIS Maps SDK for JavaScript 5.1

An optional function that generates a custom interrupt object based on the tool middleware request. This allows for dynamic messages and metadata to be included in the interrupt, providing context to the user when prompting for input or approval at the tool execution level.

Parameters

Parameter	Type	Description	Required
request	HumanInTheLoopToolMessageRequest	The tool middleware request that triggered the interrupt, containing details about the tool, input arguments, and execution context.

Returns: HumanInTheLoopInterrupt | Promise<HumanInTheLoopInterrupt>

outputKey

Property

Type: keyof TInput | undefined

Since: ArcGIS Maps SDK for JavaScript 5.1

An optional key in the tool input where the human response should be stored.

Functions

createHumanInTheLoopMiddleware

Function

Type parameters: <TCustomState extends AgentData = AgentData>

Since: ArcGIS Maps SDK for JavaScript 5.1

This middleware allows for human intervention during agent execution by throwing an interrupt to pause the agent and prompt the user for input or approval prior to proceeding. It can be used to implement a human-in-the-loop workflow, where certain decisions or actions require human approval before proceeding.

The interrupt includes customizable messages and metadata to provide context to the user.

Signature: createHumanInTheLoopMiddleware <TCustomState extends AgentData = AgentData>(options?: HumanInTheLoopMiddlewareOptions<TCustomState>): AgentMiddleware<TCustomState>

Parameters

Parameter	Type	Description	Required
options	HumanInTheLoopMiddlewareOptions	Configuration options for the middleware, including the interrupt handler and optional output key for storing the human response in the agent state.

Returns: AgentMiddleware
An agent middleware that can be added to an agent's middleware stack.

Example

const agent = new WorkflowAgent({
  workflow: myWorkflow,
  middlewares: [
    createHumanInTheLoopMiddleware({
      interrupt: async ({ agentId }) => ({
        message: `Agent ${agentId} is requesting approval to continue. Do you approve?`,
      }),
    }),
  ],
});

createHumanInTheLoopToolMiddleware

Function

Type parameters: <TInput extends AgentData = AgentData, TOutput = unknown>

Since: ArcGIS Maps SDK for JavaScript 5.1

This middleware is designed to wrap tool calls within an agent, allowing for human intervention at the tool execution level. When a tool wrapped with this middleware is invoked, it will throw an interrupt similar to the agent-level middleware, prompting the user for input or approval before the tool executes.

Signature: createHumanInTheLoopToolMiddleware <TInput extends AgentData = AgentData, TOutput = unknown>(options?: HumanInTheLoopToolMiddlewareOptions<TInput>): FunctionToolMiddleware<TInput, TOutput>

Parameters

Parameter	Type	Description	Required
options	HumanInTheLoopToolMiddlewareOptions	Configuration options for the middleware, including the interrupt handler and optional output key for storing the human response in the tool input.

Returns: FunctionToolMiddleware<TInput, TOutput>
A function tool middleware that can be added to a tool's middleware stack.

Example

const myTool = new FunctionTool({
  name: "sensitiveOperation",
  execute: async (input) => {
    // perform sensitive operation
  },
  middlewares: [
    createHumanInTheLoopToolMiddleware({
      interrupt: async ({ toolName, args }) => ({
        message: `Tool ${toolName} is requesting approval to execute with arguments: ${JSON.stringify(args)}. Do you approve?`,
      }),
    }),
  ],
});

getHumanInTheLoopPayload

Function

Type parameters: <TPayload = unknown>

Since: ArcGIS Maps SDK for JavaScript 5.1

This function retrieves the human-in-the-loop (HITL) response payload from the agent execution configuration.

Signature: getHumanInTheLoopPayload <TPayload = unknown>(config: AgentExecutionConfig | undefined): TPayload | undefined

Parameters

Parameter	Type	Description	Required
config	AgentExecutionConfig \| undefined	The agent execution configuration that may contain a HITL response.

Returns: TPayload | undefined
The payload from the HITL response if available; otherwise, undefined.