Execute tool (AI agents)
Use executeTool
to apply a tool call from your AI agent to the editor.
Once you've added tool definitions to your AI agent, the AI agent will generate tool calls. Use the executeTool
method to apply the tool calls to the editor.
executeTool
Executes a supported tool by name and input.
Parameters
options
(ExecuteToolOptions
): Configuration for tool executiontoolName
(string
): Tool to execute. Can be one of the available tools.input
(unknown
): A JSON object that matches the input schema of the tool parameters. If no parameters are required for this tool, pass an empty object ({}
).chunkSize?
(number
): The maximum size of a string that can be passed as input to the AI model. Prevents the AI from reading too much content at once so that the context window of the AI model is not exceeded. Default:32000
. This parameter is used by reading tools to control how the document is split into chunks.reviewOptions?
(ReviewOptions
): Control preview/review behaviormode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
showDiff?
(boolean
): Whether to diff the documents before and after the change to display the change as a detailed diff. Default:false
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
Returns (ExecuteToolResult
)
output
(string
): Response message from the tool execution, to be read by the AI agent.hasError
(boolean
): Whether there was an error during executionunknownTool
(boolean
): Whether thetoolName
is not recognized by the AI ToolkitdocChanged
(boolean
): Whether the tool call modifies the document.
Example
// Handle the insertContent tool call
const result = toolkit.executeTool({
toolName: 'insertContent',
input: {
html: '<p>Inserted content</p>',
position: 'documentEnd',
},
})
For a complete hands-on tutorial, see the AI agent chatbot guide.
streamTool
Updates the document in real time while a tool call is streaming.
This method has the same effect as calling the executeTool
method, but it edits the document incrementally while the tool call is streaming, instead of editing the document all at once when the tool call has finished streaming.
Parameters
options
(StreamToolOptions
): Configuration for tool streamingtoolCallId
(unknown
): The id of the tool calltoolName
(string
): Tool to execute. Can be one of the available tools.input
(unknown
): A JSON object that matches the input schema of the tool parameters. If no parameters are required for this tool, pass an empty object ({}
). If the tool has not finished streaming, this parameter should be a partial object with part of the parameters, but still a valid JSON object.hasFinished?
(boolean
): Whether the tool has finished streaming. Default:false
chunkSize?
(number
): The maximum size of a string that can be passed as input to the AI model. Prevents the AI from reading too much content at once so that the context window of the AI model is not exceeded. Default:32000
. This parameter is used by reading tools to control how the document is split into chunks.reviewOptions?
(ReviewOptions
): Control preview/review behaviormode?
('disabled' | 'review' | 'preview'
): Whether to review the changes before or after applying them.'disabled'
means no review,'review'
means review after applying,'preview'
means preview before applying. Default:'disabled'
showDiff?
(boolean
): Whether to diff the documents before and after the change to display the change as a detailed diff. Default:false
displayOptions?
(DisplayOptions<{ suggestion: Suggestion }>
): Customize how suggestions are displayedshowAsDiff?
(boolean
): Whether to show the suggestion as a diff where inserted and original content are displayed side by side. Default:true
diffPosition?
('before' | 'after'
): The position of the diff relative to the suggestion. Default:'before'
attributes?
(Record<string, any>
): Extra HTML attributes to be added to the suggestionrenderDecorations?
(RenderDecorations<{ suggestion: Suggestion }>
): A function to render the suggestion as ProseMirror decorations
metadata?
(Record<string, any>
): Extra metadata for the suggestions that can be used to store additional information about them (e.g. their source or their category). It is not used internally by the extension but it may help developers customize how the suggestions are displayed in the UI.
Returns (StreamToolResult
)
output
(string
): Response message from the tool execution, to be read by the AI agent.hasError
(boolean
): Whether there was an error during executionunknownTool
(boolean
): Whether thetoolName
is not recognized by the AI ToolkitdocChanged
(boolean
): Whether the tool call modifies the document.
Example
The streamTool
method is called repeatedly while the tool call is streaming. When the tool call has finished streaming, the streamTool
method is called again with hasFinished: true
to indicate that the tool call has finished streaming.
// Stream a tool call while it's being generated.
// Call `streamTool` again every time a new streaming part is received.
const result = toolkit.streamTool({
// Tool is still streaming, so tool streaming has not finished yet
hasFinished: false,
toolCallId: 'call_123',
toolName: 'insertContent',
// Content is still streaming, so we pass a partial object.
input: {
position: 'documentEnd',
// The HTML content has not fully been received yet
html: '<p>HTML cont',
},
})
// When the tool call is complete, call it again with hasFinished: true
const finalResult = toolkit.streamTool({
// Tool streaming has finished
hasFinished: true,
toolCallId: 'call_123',
toolName: 'insertContent',
// Streaming is complete, so we can pass the full object
input: {
position: 'documentEnd',
html: '<p>HTML content</p>',
},
})
For a complete hands-on tutorial on tool streaming, see the AI agent chatbot with tool streaming guide.