aisdk.LLMTool

Tool for AI agent

Syntax

tool = aisdk.LLMTool(f)

tool = aisdk.LLMTool(___,Name=Value)

tool = aisdk.LLMTool(client)

Description

tool = aisdk.LLMTool(f) creates a LocalLLMTool object from the function handle f. The software automatically tries to extract the name, description, and input and output argument information from the function.

tool = aisdk.LLMTool(___,Name=Value) specifies additional options using one or more name-value arguments. For example, to allow an agent to execute the tool without needing human approval, set ApprovalRequest to "never".

tool = aisdk.LLMTool(client) creates an MCPTool object or an array of MCPTool objects from the tools provided by an MCP server by using the MCP client client.

Examples

Create Tool From Built-In Function

To create an AI tool from a built-in MATLAB® function, use the aisdk.LLMTool function with the function handle of the built-in function as input.

tool = aisdk.LLMTool(@splitTextChunks)

tool =

  LocalLLMTool with properties:

                Name: "splitTextChunks"
         Description: "Split documents recursively into text chunks"
      InputArguments: [1×3 aisdk.LLMToolArgument]
     OutputArguments: [1×1 aisdk.LLMToolArgument]
           Workspace: "none"
     ApprovalRequest: never
        DisplayTitle: "splitTextChunks"
         Annotations: [1×1 struct]

The software automatically extracts information about the arguments, function name, and function description.

If the arguments contain varargin or varargout, then specify a syntax by specifying the InputArguments or OutputArguments name-value arguments, respectively.

Create Tool From Custom Function

To create an AI tool from a custom function, use the aisdk.LLMTool function with the function handle of the custom function as input.

First, create a custom function called myFunction and save it to a file called myFunction.m. To enable the aisdk.LLMTool function to automatically extract information about the function description, add a comment at the top of the function file that contains the definition. To enable the aisdk.LLMTool function to automatically extract information about the input arguments, use an arguments block. For more information about arguments blocks, see arguments Block Syntax.

function out = myFunction(x,y,nvp)
%Add two numbers with a twist
    arguments
        x double
        y double
        nvp.AlwaysReturn42(1,1) logical = true
    end

    if nvp.AlwaysReturn42
        out = 42;
    else
        out = x + y;
    end
end

Create an AI tool from the myFunction function by using the aisdk.LLMTool function.

tool = aisdk.LLMTool(@myFunction)

tool =

  LocalLLMTool with properties:

     InputArguments: [1×3 aisdk.LLMToolArgument]
    OutputArguments: [1×1 aisdk.LLMToolArgument]
    ApprovalRequest: "never"
               Name: "myFunction"
       DisplayTitle: "myFunction"
        Description: "Add two numbers with a twist"
        Annotations: [1×1 struct]

Create Tool From MCP Server

To create one or more AI tools from the tools provided by an MCP server, first connect to the MCP server by using the mcpHTTPClient function. Then, use the client as the input to the aisdk.LLMTool function.

Connect to an MCP server with server endpoint endpoint by using the mcpHTTPClient function.

client = mcpHTTPClient(endpoint);

Create an AI tool from the MCP server by using the aisdk.LLMTool function.

tool = aisdk.LLMTool(client);

If the MCP server provides more than one tool, then tool is an array of MCPTool objects.

Configure Tool to Use Agent Workspace

This example shows how to configure an LLM tool to use data from the agent workspace as input or output data.

The eig function calculates the eigenvectors and eigenvalues of matrices. Vectors and matrices can contain large amounts of numerical data. Instead of sending all this data to an LLM, which costs tokens, keep the data in the agent workspace and configure your tools to work on that workspace.

Create a function called eigTool.

The first input argument of the function must be a structure array representing the input agent workspace. Call the argument agentWorkspace.
The last output argument of the function must be a structure array representing the updated agent workspace after the tool call.
To allow the agent to understand the outcome of the tool call, add another output argument, observation, that contains a natural language description of the outcome of the tool call.

function [observation,agentWorkspace] = eigTool(agentWorkspace)
% Compute the eigenvalues of a matrix
agentWorkspace.eigenvalues = eig(agentWorkspace.matrix);
observation = "Eigenvalues were computed and added to the agent workspace.";
end

Create an LLM tool from the eigTool function by using the aisdk.LLMTool function. Set the Workspace name-value argument to "agent".

tool = aisdk.LLMTool(@eigTool,Workspace="agent");

Create an agent from an LLM client client and system prompt systemPrompt. Set the Tools name-value argument to tool.

agent = aisdk.AIAgent(client,SystemPrompt=systemPrompt,Tools=tool);

The eigTool function expects the agent workspace to have a variable called matrix. To allow an agent to use the tool tool, add the matrix to the agent workspace.

agent.Workspace.matrix = randn(10);

Input Arguments

`f` — Function

function handle

Function, specified as a function handle.

Example: @myFunction

Data Types: function_handle

`client` — MCP client

mcpHTTPClient object

MCP client, specified as an mcpHTTPClient object.

Data Types: mcpHTTPClient

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: aisdk.LLMTool(f,ApprovalRequest="never") allows an agent to execute the tool without needing human approval.

`Name` — Tool name

string scalar | character vector

Tool name, specified as a string scalar or character vector.

By default, the tool name is the name of the function specified by f.

If the function name contains a dot, for example because it is defined in a namespace, then the resulting tool name replaces the dot with an underscore. For example, the function "mynamesp.myFunction" has the tool name "mynamesp_myFunction".

If f is an anonymous function, then you must specify Name.

Data Types: char | string

`Description` — Tool description

string scalar | character vector

Tool description, specified as a string scalar or character vector.

By default, the software tries to use the text contained in the comment directly after the function definition line:

function myFunction(x)
% This is the default function description
...
end

Provide details about the tool meaning and usage to the model to improve the quality of the generated output.

Data Types: char | string

`DisplayTitle` — Display title

string scalar | character vector

Display title, specified as a string scalar or character vector.

The agent does not see the display title. Use the display title to create human-readable displays, and for postprocessing and analysis.

Example: "Sine Function"

Data Types: char | string

`InputArguments` — Input arguments

aisdk.LLMToolArgument array | structure array

Input arguments, specified as an aisdk.LLMToolArgument array or a structure array.

Specify the input arguments in one of two ways:

Use an aisdk.LLMToolArgument object.
Provide an example set of input arguments by using a structure array. For example, if your function has two inputs, a numeric scalar x and a string scalar str, then you can specify InputArguments as struct(x=3.14,str="test").

If your function contains an argument block, then by default, the software uses that information to derive the input arguments. If the arguments contain varargin, then specify a syntax by specifying the InputArguments name-value argument.

Data Types: aisdk.LLMToolArgument | struct

`OutputArguments` — Output arguments

aisdk.LLMToolArgument array | structure array

Output arguments, specified as an aisdk.LLMToolArgument array or a structure array.

Specify the output arguments in one of two ways:

Use an aisdk.LLMToolArgument object.
Provide an example set of output arguments by using a structure array. For example, if your function has two outputs, a numeric scalar x and a string scalar str, then you can specify OutputArguments as struct(x=3.14,str="test").T

By default, the software tries to extract information about the output arguments from the function definition. If the arguments contain varargout, then specify a syntax by specifying the OutputArguments name-value argument.

Data Types: aisdk.LLMToolArgument | struct

`Annotations` — Tool annotations

structure

Tool annotations, specified as a structure.

Specify tool annotations to configure the tool behavior in a custom or external application or API.

For example, display a warning message to the end user when the agent calls a tool that is able to overwrite or delete data. First, add an annotation to the tool: tool.Annotations.destructiveHint = true. Then, in your application, verify whether the Annotations property of a called tool has a field destructiveHint with value false. If it does not, then display a warning.

Data Types: struct

`ApprovalRequest` — Option to request human approval

"never" (default) | "always" | "once"

Option to request human approval, specified as "never", "always", or "once".

Use this property to specify if the human user must approve the tool before the agent evaluates it.

"never" — Tool does not require approval.
"always" — Always ask for approval before executing the tool.
"once" — Ask for approval the first time the agent calls the tool. The user can choose to allow tool execution without additional approval requests for the remainder of the agent session.

Data Types: string

`Workspace` — Tool workspace

"none" (default) | "agent"

Tool workspace, specified as "none" or "agent".

Specifying data in the agent workspace lets tools work on data that the software does not send to the LLM. For example:

Large amounts of data.
Data types that cannot be converted to JSON data types, such as complex numbers, arrays, or specialized objects, including custom objects.

To configure a tool to operate on the agent workspace, set the Workspace property of the tool to "agent". The underlying function must be configured as follows:

The first input argument must be a structure representing the input agent workspace.
The last output argument must be a structure representing the updated agent workspace after tool execution.
Do not add either of the workspace arguments to the tool as an aisdk.LLMToolArgument object.
The agent does not directly interact with the agent workspace. To let the agent generate a response or decide on next steps, add one or more additional output arguments. For example:
- Add an output argument that describes the outcome of the tool call to the agent in natural language.
- Add an output argument that contains the parts of the result that are relevant to the agent. For example, if you have a tool that calculates the eigenvalues of a large matrix in the workspace, then you can return the top three largest eigenvalues as a separate output argument.

Ensure that any workspace field names that the underlying function uses are defined in the Workspace property of the agent before the agent calls the tool.

For more information, see Configure Tool to Use Agent Workspace.

Data Types: string | char

Output Arguments

`tool` — LLM tool

LocalLLMTool | MCPTool

LLM tool, returned as a LocalLLMTool object, an MCPTool object, or as an array of tools.

Algorithms

Argument Type Detection

If you provide an example set of input or output arguments by using a structure, then the software converts the example structures into aisdk.LLMToolArgument objects. The JSON data type of the aisdk.LLMToolArgument object depends on the field values of the example structure:

Input Data Type	JSON Data Type	Example
real-valued scalar integer	`"integer"`	`struct(x=3)`
real-valued scalar	`"number"`	`struct(x=3.14)`
logical scalar	`"boolean"`	`struct(tf=true)`
string scalar or character vector	`"string"`	`struct(str="hello")`,`struct(str='hi')`

To use other data types, including non-scalar inputs, complex numbers, and specialized objects including custom objects, add the data to the agent workspace and configure the tool to work with the agent workspace. For more information, see Configure Tool to Use Agent Workspace.

Navigation Menu

Uh oh!

aisdk.LLMTool

Syntax

Description

Examples

Create Tool From Built-In Function

Create Tool From Custom Function

Create Tool From MCP Server

Configure Tool to Use Agent Workspace

Input Arguments

`f` — Function

`client` — MCP client

Name-Value Arguments

`Name` — Tool name

`Description` — Tool description

`DisplayTitle` — Display title

`InputArguments` — Input arguments

`OutputArguments` — Output arguments

`Annotations` — Tool annotations

`ApprovalRequest` — Option to request human approval

`Workspace` — Tool workspace

Output Arguments

`tool` — LLM tool

Algorithms

Argument Type Detection

See Also

Uh oh!

FilesExpand file tree

aisdk.LLMTool.md

Latest commit

History

aisdk.LLMTool.md

File metadata and controls

aisdk.LLMTool

Syntax

Description

Examples

Create Tool From Built-In Function

Create Tool From Custom Function

Create Tool From MCP Server

Configure Tool to Use Agent Workspace

Input Arguments

f — Function

client — MCP client

Name-Value Arguments

Name — Tool name

Description — Tool description

DisplayTitle — Display title

InputArguments — Input arguments

OutputArguments — Output arguments

Annotations — Tool annotations

ApprovalRequest — Option to request human approval

Workspace — Tool workspace

Output Arguments

tool — LLM tool

Algorithms

Argument Type Detection

See Also

`f` — Function

`client` — MCP client

`Name` — Tool name

`Description` — Tool description

`DisplayTitle` — Display title

`InputArguments` — Input arguments

`OutputArguments` — Output arguments

`Annotations` — Tool annotations

`ApprovalRequest` — Option to request human approval

`Workspace` — Tool workspace

`tool` — LLM tool