Class AssistantTool<TArguments, TResult>
A tool whose arguments and result are records: the arguments of a call are read as a TArguments, and the tool answers with a
TResult, as data and as text.
public abstract class AssistantTool<TArguments, TResult> : IAssistantTool where TArguments : class where TResult : class
Type Parameters
TArgumentsThe arguments of a call.
TResultWhat a call answers.
- Inheritance
-
AssistantTool<TArguments, TResult>
- Implements
- Inherited Members
Remarks
The input schema is the JSON Schema of TArguments and the output schema that of TResult
(JsonSchemaExporter), so a schema always says what the tool reads and writes. A required member is a required argument.
Each argument is described in the language of the client's user interface (ArgumentDescriptionOf(string, CultureInfo)).
The arguments are read the way Options reads a message, in any case, and an argument that is not a member of
TArguments refuses the call: a misspelled argument is told, never ignored.
Properties
Annotations
What a call does to the workspace.
protected abstract ToolAnnotations Annotations { get; }
Property Value
Name
The name a call gives (Name): letters, digits, _ and -, at most 64 characters, the same in every language.
public abstract string Name { get; }
Property Value
Methods
ArgumentDescriptionOf(string, CultureInfo)
What an argument is, for an assistant to read; null, by default, for an argument its name says enough of.
protected virtual string? ArgumentDescriptionOf(string argument, CultureInfo culture)
Parameters
argumentstringThe argument's name, as the schema writes it (
includeDeclaration).cultureCultureInfoThe language of the client's user interface.
Returns
- string
The description.
CallAsync(JsonObject, CancellationToken)
Calls the tool.
public Task<ToolCallResult> CallAsync(JsonObject arguments, CancellationToken token)
Parameters
argumentsJsonObjectThe arguments of the call, as the tool's input schema describes them; an empty object for none.
tokenCancellationTokenCancels the call:
$/cancelRequestof the request that made it.
Returns
- Task<ToolCallResult>
What the tool answers.
Remarks
The text is rendered in the language of the current user interface (CurrentUICulture), which a server takes from its
client's initialize.
Exceptions
- AssistantToolRefusedException
The tool refuses the call: the arguments are not valid, or what they name cannot be done.
- OperationCanceledException
tokenwas cancelled.
Describe(CultureInfo)
What the tool is, in a language: its description, the schema of its arguments and of its result, and its annotations.
public ToolDescriptor Describe(CultureInfo culture)
Parameters
cultureCultureInfoThe language of the client's user interface.
Returns
Remarks
A descriptor is made once in each language, and the same instance is answered after that.
DescriptionOf(CultureInfo)
What the tool does and when to call it, for an assistant to read.
protected abstract string DescriptionOf(CultureInfo culture)
Parameters
cultureCultureInfoThe language of the client's user interface.
Returns
- string
The description.
Render(TResult, CultureInfo)
What a call answers, as text for an assistant to read: short, one line for each item, positions written path:line:column.
protected abstract string Render(TResult result, CultureInfo culture)
Parameters
resultTResultWhat the call answers.
cultureCultureInfoThe language of the client's user interface.
Returns
- string
The text.
RunAsync(TArguments, CancellationToken)
Does what a call asks.
protected abstract Task<TResult> RunAsync(TArguments arguments, CancellationToken token)
Parameters
argumentsTArgumentsThe arguments of the call.
tokenCancellationTokenCancels the call.
Returns
- Task<TResult>
What the call answers.
Exceptions
- AssistantToolRefusedException
The tool refuses the call.
TitleOf(CultureInfo)
A short name of the tool for a person to read; null, by default, for none.
protected virtual string? TitleOf(CultureInfo culture)
Parameters
cultureCultureInfoThe language of the client's user interface.
Returns
- string
The title.