@arcgis/ai-components 5.1.0-next.99 → 5.2.0-next.1

package/dist/agent-utils/middlewares/humanInTheLoop.d.ts

@@ -0,0 +1,152 @@
+import type { FunctionToolMiddleware, FunctionToolMiddlewareRequest } from "../tools/FunctionTool.js";
+import type { AgentData, AgentExecutionConfig, AgentGraphState } from "../types.js";
+import type { AgentMiddleware, AgentRunRequest } from "./types.js";
+import type { UiInterrupt } from "../../utils/index.js";
+
+/** @since 5.1 */
+export interface HumanInTheLoopInterruptRequest<TCustomState extends AgentData = AgentData> extends AgentRunRequest<TCustomState> {
+  /**
+   * 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.
+   *
+   * @since 5.1
+   */
+  agentId: string;
+}
+
+/** @since 5.1 */
+export type HumanInTheLoopInterrupt = Partial<UiInterrupt>;
+
+/**
+ * Options for configuring the HumanInTheLoopMiddleware.
+ *
+ * @since 5.1
+ */
+export interface HumanInTheLoopMiddlewareOptions<TCustomState extends AgentData = AgentData> {
+  /**
+   * 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.
+   *
+   * @param request - The agent run request that triggered the interrupt, containing details about the agent, node, and execution context.
+   * @returns An object containing the interrupt details, which will be thrown as a NodeInterrupt to pause the agent's execution.
+   * @since 5.1
+   */
+  interrupt?(request: HumanInTheLoopInterruptRequest<TCustomState>): HumanInTheLoopInterrupt | Promise<HumanInTheLoopInterrupt>;
+  /**
+   * An optional key in the agent state where the human response should be stored.
+   *
+   * @since 5.1
+   */
+  outputKey?: keyof AgentGraphState<TCustomState>;
+}
+
+/** @since 5.1 */
+export interface HumanInTheLoopToolMessageRequest<TInput extends AgentData = AgentData> extends FunctionToolMiddlewareRequest<TInput> {
+  /**
+   * The arguments passed to the tool that is requesting human intervention.
+   *
+   * @since 5.1
+   */
+  args: object;
+  /**
+   * The id of the tool call that is requesting human intervention.
+   *
+   * @since 5.1
+   */
+  toolCallId?: string;
+  /**
+   * The name of the tool that is requesting human intervention.
+   *
+   * @since 5.1
+   */
+  toolName: string;
+}
+
+/**
+ * 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.
+ *
+ * @since 5.1
+ */
+export interface HumanInTheLoopToolMiddlewareOptions<TInput extends AgentData = AgentData> {
+  /**
+   * 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.
+   *
+   * @param request - The tool middleware request that triggered the interrupt, containing details about the tool, input arguments, and execution context.
+   * @since 5.1
+   * @return An object containing the interrupt details, which will be thrown as a NodeInterrupt to pause the tool's execution.
+   */
+  interrupt?(request: HumanInTheLoopToolMessageRequest<TInput>): HumanInTheLoopInterrupt | Promise<HumanInTheLoopInterrupt>;
+  /**
+   * An optional key in the tool input where the human response should be stored.
+   *
+   * @since 5.1
+   */
+  outputKey?: keyof TInput;
+}
+
+/**
+ * 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.
+ *
+ * @param options - Configuration options for the middleware, including the interrupt handler and optional output key for storing the human response in
+ * the agent state.
+ * @returns An agent middleware that can be added to an agent's middleware stack.
+ * @since 5.1
+ * @example
+ * ```ts
+ * const agent = new WorkflowAgent({
+ *   workflow: myWorkflow,
+ *   middlewares: [
+ *     createHumanInTheLoopMiddleware({
+ *       interrupt: async ({ agentId }) => ({
+ *         message: `Agent ${agentId} is requesting approval to continue. Do you approve?`,
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export function createHumanInTheLoopMiddleware<TCustomState extends AgentData = AgentData>(options?: HumanInTheLoopMiddlewareOptions<TCustomState>): AgentMiddleware<TCustomState>;
+
+/**
+ * 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.
+ *
+ * @param options - Configuration options for the middleware, including the interrupt handler and optional output key for storing the human response in the tool input.
+ * @returns A function tool middleware that can be added to a tool's middleware stack.
+ * @since 5.1
+ * @example
+ * ```ts
+ * 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?`,
+ *       }),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export function createHumanInTheLoopToolMiddleware<TInput extends AgentData = AgentData, TOutput = unknown>(options?: HumanInTheLoopToolMiddlewareOptions<TInput>): FunctionToolMiddleware<TInput, TOutput>;
+
+/**
+ * This function retrieves the human-in-the-loop (HITL) response payload from the agent execution configuration.
+ *
+ * @param config - The agent execution configuration that may contain a HITL response.
+ * @returns The payload from the HITL response if available; otherwise, undefined.
+ * @since 5.1
+ */
+export function getHumanInTheLoopPayload<TPayload = unknown>(config: AgentExecutionConfig | undefined): TPayload | undefined;

package/dist/agent-utils/middlewares/humanInTheLoop.js

@@ -0,0 +1,94 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { NodeInterrupt as s } from "@langchain/langgraph/web";
+import { createAgentMiddleware as f, createToolMiddleware as I } from "./middleware.js";
+const m = "human-in-the-loop", w = "Agent execution requires approval", p = "Agent execution rejected by the user.", h = "human-in-the-loop-tool", y = "Tool execution requires approval";
+function k(t = {}) {
+  const { outputKey: n } = t;
+  return f(
+    m,
+    {
+      wrapAgent: async (e, r) => {
+        const a = T(e), o = M(a, e), i = u(e.config?.configurable);
+        if (i?.agentId !== a)
+          throw new s(await g({ agentId: a, interruptId: o, options: t, request: e }));
+        if (i.id !== o) {
+          if (b(a, i.id))
+            return await r(e);
+          throw new s(await g({ agentId: a, interruptId: o, options: t, request: e }));
+        }
+        if (i.payload === !1)
+          return { outputMessage: p, status: "failed", summary: p };
+        const l = n ? { ...e.state, [n]: i.payload } : e.state, d = { ...e, state: l };
+        return await r(d);
+      }
+    },
+    { outputKey: n }
+  );
+}
+function v(t = {}) {
+  const { outputKey: n } = t;
+  return I(h, {
+    wrapToolCall: async (e, r) => {
+      const a = e.tool.name, o = A(e.config?.configurable), i = R(o, e.toolCallId ?? a), l = u(e.config?.configurable);
+      if (l?.agentId !== o || l.id !== i)
+        throw new s(await $({ agentId: o, interruptId: i, options: t, request: e }));
+      if (l.payload === !1)
+        return `Tool call "${a}" was rejected by the user.`;
+      const d = n ? { ...e.input, [n]: l.payload } : e.input, c = { ...e, input: d };
+      return await r(c);
+    }
+  });
+}
+async function g(t) {
+  const { agentId: n, interruptId: e, options: r, request: a } = t, o = await r.interrupt?.({ ...a, agentId: n });
+  return {
+    agentId: n,
+    id: e,
+    kind: o?.kind ?? "booleanChoice",
+    message: o?.message ?? w,
+    metadata: o?.metadata
+  };
+}
+function T(t) {
+  return typeof t.config?.configurable?.agentId == "string" ? t.config.configurable.agentId : t.agent.id;
+}
+function M(t, n) {
+  const e = n.config?.configurable?.thread_id, r = typeof e == "string" && e ? `${e}:` : "";
+  return `${t}:${r}${n.nodeName}`;
+}
+function b(t, n) {
+  return n.startsWith(`${t}:tool:`);
+}
+function A(t) {
+  return typeof t?.agentId == "string" ? t.agentId : "llm-agent";
+}
+function R(t, n) {
+  return `${t}:tool:${n}`;
+}
+async function $(t) {
+  const { agentId: n, interruptId: e, options: r, request: a } = t, { input: o, tool: i, toolCallId: l } = a, d = i.name, c = await r.interrupt?.({ ...a, args: o, toolName: d, toolCallId: l });
+  return {
+    agentId: n,
+    id: e,
+    kind: c?.kind ?? "booleanChoice",
+    message: c?.message ?? `${y}
+Tool: ${d}`,
+    metadata: c?.metadata ?? {
+      args: o,
+      toolCallId: l,
+      toolName: d
+    }
+  };
+}
+function H(t) {
+  return u(t?.configurable)?.payload;
+}
+function u(t) {
+  const n = t?.hitlResponse;
+  return n && typeof n == "object" && "id" in n && "agentId" in n ? n : null;
+}
+export {
+  k as createHumanInTheLoopMiddleware,
+  v as createHumanInTheLoopToolMiddleware,
+  H as getHumanInTheLoopPayload
+};

package/dist/agent-utils/middlewares/middleware.d.ts

@@ -0,0 +1,25 @@
+import type { FunctionToolMiddleware } from "../tools/FunctionTool.js";
+import type { AgentData, AgentGraphState, EmptyAgentData } from "../types.js";
+import type { AgentMiddleware, AgentMiddlewareHooks, ToolMiddlewareHooks } from "./types.js";
+
+/**
+ * Creates an agent middleware with the specified hooks and options.
+ *
+ * @param name - The name of the middleware.
+ * @param hooks - The hooks to be used in the middleware.
+ * @param options - Optional configuration for the middleware, such as the output key.
+ * @returns The created agent middleware.
+ * @since 5.1
+ */
+export function createAgentMiddleware<TCustomState extends AgentData = EmptyAgentData>(name: string, hooks: AgentMiddlewareHooks<TCustomState>, options?: { outputKey?: keyof AgentGraphState<TCustomState>; }): AgentMiddleware<TCustomState>;
+
+/**
+ * Creates a tool middleware with the specified hooks and options.
+ *
+ * @param name - The name of the middleware.
+ * @param hooks - The hooks to be used in the middleware.
+ * @param options - Optional configuration for the middleware, such as the output key.
+ * @returns The created function tool middleware.
+ * @since 5.1
+ */
+export function createToolMiddleware<TInput extends AgentData = AgentData, TOutput = unknown>(name: string, hooks: ToolMiddlewareHooks<TInput, TOutput>, options?: { outputKey?: string; }): FunctionToolMiddleware<TInput, TOutput>;

package/dist/agent-utils/middlewares/middleware.js

@@ -0,0 +1,44 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import { createMiddleware as p } from "langchain";
+function g(e, t, r) {
+  return {
+    name: e,
+    handler: async (a, n) => {
+      const c = async (l) => {
+        const d = await t.beforeAgent?.(l), u = d ? {
+          ...l,
+          state: {
+            ...l.state,
+            ...d
+          }
+        } : l, i = await n(u), w = await t.afterAgent?.({ ...u, result: i });
+        return w ? { ...i, ...w } : i;
+      };
+      return t.wrapAgent ? await t.wrapAgent(a, c) : await c(a);
+    },
+    hooks: t,
+    outputKey: r?.outputKey
+  };
+}
+function y(e, t, r) {
+  return { name: e, handler: async (a, n) => t.wrapToolCall ? await t.wrapToolCall(a, n) : await n(a), outputKey: r?.outputKey };
+}
+function C(e) {
+  return e.map((t) => f(t.name, t.hooks ?? {})).filter((t) => !!t);
+}
+function f(e, t) {
+  const { afterModel: r, beforeModel: o, wrapModelCall: a, wrapToolCall: n } = t;
+  if (!(!r && !o && !a && !n))
+    return p({
+      afterModel: r,
+      beforeModel: o,
+      name: e,
+      wrapModelCall: a,
+      wrapToolCall: n
+    });
+}
+export {
+  C as convertToLangChainMiddlewares,
+  g as createAgentMiddleware,
+  y as createToolMiddleware
+};

package/dist/agent-utils/middlewares/trace.d.ts

@@ -0,0 +1,25 @@
+import type { FunctionToolMiddleware } from "../tools/FunctionTool.js";
+import type { AgentMiddleware } from "./types.js";
+import type { AgentData } from "../types.js";
+
+/**
+ * This middleware is responsible for sending trace messages whenever the agent makes a call to the language model or executes a tool.
+ *
+ * It uses the `sendTraceMessage` function from the orchestrator to send messages that include
+ * details about the model calls and tool
+ * executions, which can be useful for debugging and monitoring the agent's behavior.
+ *
+ * @returns An agent middleware that wraps model calls and sends trace messages.
+ * @since 5.1
+ */
+export function createAgentTraceMiddleware(): AgentMiddleware;
+
+/**
+ * This middleware is responsible for sending trace messages whenever a tool is executed by the agent. It wraps tool calls and uses the `sendTraceMessage`
+ * function from the orchestrator to send messages that include details about the tool execution, such as the tool name and its result. This can be useful for
+ * debugging and monitoring the behavior of tools within the agent's execution.
+ *
+ * @returns A function tool middleware that wraps tool calls and sends trace messages.
+ * @since 5.1
+ */
+export function createToolTraceMiddleware<TInput extends AgentData = AgentData, TOutput = unknown>(): FunctionToolMiddleware<TInput, TOutput>;

package/dist/agent-utils/middlewares/trace.js

@@ -0,0 +1,50 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+import "@arcgis/core/identity/IdentityManager.js";
+import "@arcgis/core/portal/Portal.js";
+import "@langchain/langgraph/web";
+import { s as n } from "../../chunks/generateLayerDescriptions.js";
+import { AIMessage as l, ToolMessage as s } from "@langchain/core/messages";
+import "@langchain/openai";
+import "@arcgis/core/core/reactiveUtils.js";
+import "@arcgis/core/layers/FeatureLayer.js";
+import "@arcgis/core/request.js";
+import "@langchain/core/prompts";
+import { createAgentMiddleware as c, createToolMiddleware as m } from "./middleware.js";
+const d = "agent-trace", g = "tool-trace";
+function $() {
+  return c(d, {
+    wrapModelCall: async (t, o) => {
+      const e = await o(t), a = t.runtime, i = p(e);
+      return await Promise.all(
+        i.map(
+          async (r) => await n(
+            {
+              text: `LLM requested tool call "${r.name}" with arguments: ${JSON.stringify(r.args, null, 2)}`
+            },
+            a
+          )
+        )
+      ), e;
+    }
+  });
+}
+function h() {
+  return m(g, {
+    wrapToolCall: async (t, o) => {
+      const e = await o(t), a = t.config;
+      return await n(
+        {
+          text: `Finished executing tool: ${s.isInstance(e) ? e.content.toString() : typeof e == "string" ? e : t.tool.name}`
+        },
+        a
+      ), e;
+    }
+  });
+}
+function p(t) {
+  return !l.isInstance(t) || !Array.isArray(t.tool_calls) ? [] : t.tool_calls.filter((o) => typeof o?.name == "string");
+}
+export {
+  $ as createAgentTraceMiddleware,
+  h as createToolTraceMiddleware
+};

package/dist/agent-utils/middlewares/types.d.ts

@@ -0,0 +1,123 @@
+import type { FunctionToolMiddlewareHandler } from "../tools/FunctionTool.js";
+import type { AgentData, AgentExecutionConfig, AgentGraphState, EmptyAgentData } from "../types.js";
+import type { AgentMiddleware as LangChainAgentMiddleware } from "langchain";
+
+/**
+ * Handles a middleware request and returns the resulting value.
+ *
+ * @param request - The request payload for the current middleware stage.
+ */
+export type MiddlewareHandler<TRequest, TResult> = (request: TRequest) => Promise<TResult> | TResult;
+
+/**
+ * Wraps a middleware request and delegates to the next handler.
+ *
+ * @param request - The request payload for the current middleware stage.
+ * @param handler - The next handler in the middleware chain.
+ */
+export type Middleware<TRequest, TResult> = (request: TRequest, handler: MiddlewareHandler<TRequest, TResult>) => Promise<TResult> | TResult;
+
+export interface AgentMiddlewareAgent {
+  /**
+   * Description of the agent, which can be used to provide context in middleware hooks and interrupts.
+   *
+   * @since 5.1
+   */
+  description?: string;
+  /**
+   * Unique identifier for the agent, used for registration and invocation purposes.
+   *
+   * @since 5.1
+   */
+  id: string;
+  /**
+   * Name of the agent, used for display and identification purposes.
+   *
+   * @since 5.1
+   */
+  name: string;
+}
+
+export interface AgentRunRequest<TCustomState extends AgentData = EmptyAgentData> {
+  /**
+   * The agent that is being executed. This can be used in middleware hooks to access agent metadata and provide context for interrupts or other middleware behavior.
+   *
+   * @since 5.1
+   */
+  agent: AgentMiddlewareAgent;
+  /**
+   * The current execution configuration for the agent run, which may include configurable parameters, metadata, and other contextual information. This can be used in middleware
+   * hooks to make decisions based on the execution context or to store and retrieve information related to the agent run.
+   *
+   * @since 5.1
+   */
+  config?: AgentExecutionConfig;
+  /**
+   * The name of the current node being executed in the agent's workflow. This can be used in middleware hooks to provide context or make decisions based on the specific node.
+   *
+   * @since 5.1
+   */
+  nodeName: string;
+  /**
+   * The current state of the agent's workflow, which may include custom data and intermediate results. This can be used in middleware hooks to access or modify the agent's state during execution.
+   *
+   * @since 5.1
+   */
+  state: Partial<AgentGraphState<TCustomState>>;
+}
+
+export type AgentMiddlewareHandler<TCustomState extends AgentData = EmptyAgentData> = Middleware<AgentRunRequest<TCustomState>, AgentGraphState<TCustomState>>;
+
+export interface AgentMiddleware<TCustomState extends AgentData = EmptyAgentData> {
+  name: string;
+  handler: AgentMiddlewareHandler<TCustomState>;
+  hooks?: AgentMiddlewareHooks<TCustomState>;
+  outputKey?: keyof AgentGraphState<TCustomState>;
+}
+
+export interface AfterAgentRequest<TCustomState extends AgentData = EmptyAgentData> extends AgentRunRequest<TCustomState> {
+  result: AgentGraphState<TCustomState>;
+}
+
+export interface AgentMiddlewareHooks<TCustomState extends AgentData = EmptyAgentData> {
+  /**
+   * An optional hook that is called after the agent has executed, allowing for modification of the result or additional side effects.
+   *
+   * @param request - The request payload for the afterAgent hook, including the original request and the result of the agent's execution.
+   * @returns A partial update to the agent's state or other modifications to be applied to the final result, or a promise that resolves to such an update.
+   * @since 5.1
+   */
+  afterAgent?(request: AfterAgentRequest<TCustomState>): Partial<AgentGraphState<TCustomState>> | Promise<Partial<AgentGraphState<TCustomState>> | void> | void;
+  readonly afterModel?: ModelLifecycleHook;
+  readonly beforeModel?: ModelLifecycleHook;
+  /**
+   * An optional hook that is called before the agent executes, allowing for modification of the request or additional side effects.
+   *
+   * @param request - The request payload for the beforeAgent hook, including the original request.
+   * @returns A partial update to the agent's state or other modifications to be applied to the request, or a promise that resolves to such an update.
+   * @since 5.1
+   */
+  beforeAgent?(request: AgentRunRequest<TCustomState>): Partial<AgentGraphState<TCustomState>> | Promise<Partial<AgentGraphState<TCustomState>> | void> | void;
+  /**
+   * An optional hook that wraps the entire agent execution, allowing for complete control over the execution flow.
+   *
+   * @since 5.1
+   */
+  readonly wrapAgent?: AgentMiddlewareHandler<TCustomState>;
+  readonly wrapModelCall?: LangChainMiddlewareHooks["wrapModelCall"];
+  readonly wrapToolCall?: LangChainMiddlewareHooks["wrapToolCall"];
+}
+
+/** @since 5.1 */
+export interface ToolMiddlewareHooks<TInput extends AgentData = AgentData, TOutput = unknown> {
+  /**
+   * Hook that wraps a tool call, allowing you to intercept and modify the request and response of a tool execution. This can be used for logging, modifying inputs/outputs, or implementing custom behavior around tool calls.
+   *
+   * @since 5.1
+   */
+  readonly wrapToolCall?: FunctionToolMiddlewareHandler<TInput, TOutput>;
+}
+
+export type LangChainMiddlewareHooks = Pick<LangChainAgentMiddleware, "afterModel" | "beforeModel" | "wrapModelCall" | "wrapToolCall">;
+
+export type ModelLifecycleHook = NonNullable<LangChainMiddlewareHooks["beforeModel"]>;

package/dist/agent-utils/middlewares/types.js

@@ -0,0 +1,2 @@
+/* COPYRIGHT Esri - https://js.arcgis.com/5.2/LICENSE.txt */
+

package/dist/agent-utils/tools/FunctionTool.d.ts

@@ -0,0 +1,127 @@
+import type Accessor from "@arcgis/core/core/Accessor.js";
+import type z from "zod";
+import type { StructuredToolInterface } from "@langchain/core/tools";
+import type { Middleware } from "../middlewares/types.js";
+import type { AgentData, AgentExecutionConfig } from "../types.js";
+
+/**
+ * Execute function used by `FunctionTool`.
+ *
+ * @param input - Structured tool input.
+ * @param config - Optional execution configuration.
+ */
+export type FunctionToolExecute<TInput extends object, TOutput> = (input: TInput, config?: AgentExecutionConfig) => Promise<TOutput> | TOutput;
+
+export type FunctionToolResult<TOutput = unknown> = TOutput | string;
+
+export interface FunctionToolMiddlewareRequest<TInput extends AgentData = AgentData> {
+  config?: AgentExecutionConfig;
+  input: TInput;
+  tool: FunctionToolMiddlewareTool;
+  toolCallId?: string;
+}
+
+export type FunctionToolMiddlewareHandler<TInput extends AgentData = AgentData, TOutput = unknown> = Middleware<FunctionToolMiddlewareRequest<TInput>, FunctionToolResult<TOutput>>;
+
+export interface FunctionToolMiddleware<TInput extends AgentData = AgentData, TOutput = unknown> {
+  name: string;
+  handler: FunctionToolMiddlewareHandler<TInput, TOutput>;
+  outputKey?: keyof TInput;
+}
+
+export type ToolResultMode = "continue" | "terminal";
+
+export interface FunctionToolLike {
+  /**
+   * Name of the tool, used for invocation by agents. This should be unique among the tools available to an agent.
+   *
+   * @since 5.1
+   */
+  name?: string;
+  /**
+   * Result mode determines how the agent should treat the output of this tool. If set to "terminal", the agent will return the tool's output directly as its final response. If set to "continue", the agent will continue processing after invoking the tool, allowing for further reasoning or tool calls.
+   *
+   * @since 5.1
+   */
+  resultMode?: ToolResultMode;
+  getTool: () => StructuredToolInterface;
+}
+
+/**
+ * FunctionTool is a tool implementation that allows users to define custom logic through a provided execute function,
+ * along with input/output schemas for validation and optional middleware for extensibility.
+ *
+ * The FunctionTool is passed to LLMAgents as part of their tools array, and can be invoked by the agent during execution
+ * based on the agent's prompt and reasoning process. The resultMode property allows the tool to either return
+ * a final response directly or continue the agent's processing after execution, providing flexibility in how the tool's
+ * output is used within the agent's workflow.
+ *
+ * @since 5.1
+ */
+export class FunctionTool<TInput extends AgentData, TOutput = unknown> extends Accessor {
+  constructor(properties?: ConstructProperties<TInput, TOutput>);
+  /**
+   * A concise, but clear description of the tool's functionality.
+   * This should provide enough information for the agent to understand when and why to use the tool.
+   * You can include examples of a user's input that would trigger the tool, the values to extract, and
+   * sample output to illustrate its purpose.
+   *
+   * @required
+   */
+  accessor description: string;
+  /**
+   * The execute function contains the custom logic that will be executed when the tool is invoked
+   * by an agent. It receives
+   * the input object and an optional execution configuration, and returns either a result directly
+   * or a promise that resolves to the result.
+   *
+   * The result is validated against the output schema, if provided.
+   *
+   * @required
+   * @since 5.1
+   */
+  accessor execute: FunctionToolExecute<TInput, TOutput>;
+  /**
+   * The input schema defines the expected structure of the input object when invoking the tool.
+   * This should be a Zod schema object.
+   * The agent will validate the input against this schema before execution.
+   */
+  accessor inputSchema: z.ZodType<TInput> | undefined;
+  /** Middleware that can wrap this tool's execution. */
+  accessor middlewares: FunctionToolMiddleware<TInput, TOutput>[];
+  /**
+   * The name of the tool, which will be used to invoke it. This should be unique among the tools
+   * available to an agent. It should also be descriptive of the tool's functionality to make it
+   * clear to the agent when to use it.
+   *
+   * @required
+   */
+  accessor name: string;
+  /**
+   * The output schema defines the expected structure of the result returned by the tool.
+   * This should be a Zod schema object.
+   * The agent will validate the output against this schema after execution.
+   */
+  accessor outputSchema: z.ZodType<TOutput> | undefined;
+  /**
+   * The result mode determines how the agent should treat the output of this tool.
+   * If set to `terminal`, the agent will
+   * return the tool's output directly as its final response. If set to `continue`,
+   * the agent will continue processing after
+   * invoking the tool, allowing for further reasoning or tool calls.
+   *
+   * @default "continue"
+   */
+  accessor resultMode: ToolResultMode;
+  /** Builds the LangChain tool adapter used by LLM agents. */
+  getTool(): StructuredToolInterface;
+}
+
+export interface FunctionToolMiddlewareTool {
+  description: string;
+  name: string;
+  resultMode: ToolResultMode;
+}
+
+export type ConstructProperties<TInput extends AgentData, TOutput> = Partial<Pick<FunctionTool<TInput, TOutput>, "inputSchema" | "middlewares" | "outputSchema" | "resultMode">>
+  & Pick<FunctionTool<TInput, TOutput>, "description" | "execute" | "name">;