Interface IAgentTool<T>

Interface representing a tool used by an agent, extending the base ITool interface. Defines the tool's execution and validation logic, with optional lifecycle callbacks.

interface IAgentTool<T = Record<string, ToolValue>> {
    callbacks?: Partial<IAgentToolCallbacks<Record<string, ToolValue>>>;
    docNote?: string;
    function:
        | {
            description: string;
            name: string;
            parameters: {
                properties: {
                    [key: string]: {
                        description: string;
                        enum?: string[];
                        type: string;
                    };
                };
                required: string[];
                type: string;
            };
        }
        | (
            clientId: string,
            agentName: string,
        ) =>
            | {
                description: string;
                name: string;
                parameters: {
                    properties: {
                        [key: string]: {
                            description: string;
                            enum?: string[];
                            type: string;
                        };
                    };
                    required: string[];
                    type: string;
                };
            }
            | Promise<
                {
                    description: string;
                    name: string;
                    parameters: {
                        properties: {
                            [key: string]: {
                                description: string;
                                enum?: string[];
                                type: string;
                            };
                        };
                        required: string[];
                        type: string;
                    };
                },
            >;
    toolName: string;
    type: string;
    validate?: (
        dto: {
            agentName: string;
            clientId: string;
            params: T;
            toolCalls: IToolCall[];
        },
    ) => boolean
    | Promise<boolean>;
    call(
        dto: {
            abortSignal: TAbortSignal;
            agentName: string;
            callReason: string;
            clientId: string;
            isLast: boolean;
            params: T;
            toolCalls: IToolCall[];
            toolId: string;
        },
    ): Promise<void>;
}

Type Parameters

  • T = Record<string, ToolValue>

    The type of the parameters for the tool, defaults to a record of ToolValue.

Properties

callbacks? docNote? function toolName type validate?

Methods

call

Properties

Optionalcallbacks

callbacks?: Partial<IAgentToolCallbacks<Record<string, ToolValue>>>

Optional lifecycle callbacks for the tool, allowing customization of execution flow.

OptionaldocNote

docNote?: string

Optional description for documentation purposes, aiding in tool usage understanding.

function

function:
    | {
        description: string;
        name: string;
        parameters: {
            properties: {
                [key: string]: { description: string; enum?: string[]; type: string };
            };
            required: string[];
            type: string;
        };
    }
    | (
        clientId: string,
        agentName: string,
    ) =>
        | {
            description: string;
            name: string;
            parameters: {
                properties: {
                    [key: string]: {
                        description: string;
                        enum?: string[];
                        type: string;
                    };
                };
                required: string[];
                type: string;
            };
        }
        | Promise<
            {
                description: string;
                name: string;
                parameters: {
                    properties: {
                        [key: string]: {
                            description: string;
                            enum?: string[];
                            type: string;
                        };
                    };
                    required: string[];
                    type: string;
                };
            },
        >

Optional dynamic factory to resolve tool metadata

Type declaration

  • {
        description: string;
        name: string;
        parameters: {
            properties: {
                [key: string]: { description: string; enum?: string[]; type: string };
            };
            required: string[];
            type: string;
        };
    }
    • description: string

      A human-readable description of the function’s purpose. Informs the model or users about the tool’s functionality (e.g., "Performs a search query"), used in tool selection or documentation. Not directly executed but critical for model understanding in ClientAgent workflows.

    • name: string

      The name of the function, uniquely identifying the tool. Must match IToolCall.function.name for execution (e.g., "search" in ClientAgent.tools), serving as the key for tool lookup and invocation. Example: "calculate" for a math tool.

    • parameters: {
          properties: {
              [key: string]: { description: string; enum?: string[]; type: string };
          };
          required: string[];
          type: string;
      }

      The schema defining the parameters required by the function. Specifies the structure, types, and constraints of arguments (e.g., IToolCall.function.arguments), validated in ClientAgent (e.g., targetFn.validate). Provides the model with a blueprint for generating valid tool calls.

      • properties: { [key: string]: { description: string; enum?: string[]; type: string } }

        A key-value map defining the properties of the parameters. Details each argument’s type, description, and optional constraints, guiding the model and agent in constructing and validating tool calls (e.g., in ClientAgent.EXECUTE_FN).

      • required: string[]

        An array of parameter names that are mandatory for the function. Lists keys that must be present in IToolCall.function.arguments, enforced during validation (e.g., ClientAgent.targetFn.validate). Example: ["query"] for a search tool requiring a query string.

      • type: string

        The type of the parameters object, typically "object". Indicates that parameters are a key-value structure, as expected by IToolCall.function.arguments in ClientAgent. Example: "object" for a standard JSON-like parameter set.

  • (
        clientId: string,
        agentName: string,
    ) =>
        | {
            description: string;
            name: string;
            parameters: {
                properties: {
                    [key: string]: { description: string; enum?: string[]; type: string };
                };
                required: string[];
                type: string;
            };
        }
        | Promise<
            {
                description: string;
                name: string;
                parameters: {
                    properties: {
                        [key: string]: {
                            description: string;
                            enum?: string[];
                            type: string;
                        };
                    };
                    required: string[];
                    type: string;
                };
            },
        >

toolName

toolName: string

The unique name of the tool, used for identification within the agent swarm.

type

type: string

Tool type defenition. For now, should be function

Optionalvalidate

validate?: (
    dto: {
        agentName: string;
        clientId: string;
        params: T;
        toolCalls: IToolCall[];
    },
) => boolean
| Promise<boolean>

Validates the tool parameters before execution. Can return synchronously or asynchronously based on validation complexity.

Type declaration

    • (
          dto: {
              agentName: string;
              clientId: string;
              params: T;
              toolCalls: IToolCall[];
          },
      ): boolean
      | Promise<boolean>

    • Parameters

      • dto: { agentName: string; clientId: string; params: T; toolCalls: IToolCall[] }

        The data transfer object containing validation details.

        • agentName: string

          The name of the agent using the tool.

        • clientId: string

          The ID of the client invoking the tool.

        • params: T

          The parameters to validate.

        • toolCalls: IToolCall[]

          The list of tool calls in the current execution context.

      Returns boolean | Promise<boolean>

      True if parameters are valid, false otherwise.

Methods

call

  • call(
        dto: {
            abortSignal: TAbortSignal;
            agentName: string;
            callReason: string;
            clientId: string;
            isLast: boolean;
            params: T;
            toolCalls: IToolCall[];
            toolId: string;
        },
    ): Promise<void>

    Executes the tool with the specified parameters and context.

    Parameters

    • dto: {
          abortSignal: TAbortSignal;
          agentName: string;
          callReason: string;
          clientId: string;
          isLast: boolean;
          params: T;
          toolCalls: IToolCall[];
          toolId: string;
      }

      The data transfer object containing execution details.

      • abortSignal: TAbortSignal
      • agentName: string

        The name of the agent using the tool.

      • callReason: string
      • clientId: string

        The ID of the client invoking the tool.

      • isLast: boolean

        Indicates if this is the last tool call in a sequence.

      • params: T

        The parameters for the tool execution.

      • toolCalls: IToolCall[]

        The list of tool calls in the current execution context.

      • toolId: string

        The unique tool_call_id for tracking in OpenAI-style history.

    Returns Promise<void>

    A promise that resolves when the tool execution is complete.

    Throws

    If the tool execution fails or parameters are invalid.

Settings

Member Visibility

On This Page

Properties
Methods