Tool¶
Overview¶
Note:
Before diving into the detailed interface documentation, make sure you have a general understanding of the tool integration process for FlexAI plugins.
- Message Types - Return different types of messages such as text, links, images, and JSON
- Variables - Create and manipulate variables for workflow integration
- Output Schema - Define custom output variables for workflow references
Data Structure¶
Message Return¶
Info:
FlexAI supports various message types such as
text,links,images,file BLOBs, andJSON. These messages can be returned through specialized interfaces.
By default, a tool's output in a workflow includes three fixed variables: files, text, and json. The methods below help you populate these variables with appropriate content.
Tip:
While you can use methods like
create_image_messageto return an image, tools also support custom output variables, making it more convenient to reference specific data in a workflow.
Message Types¶
```python Image URL def create_image_message(self, image: str) -> ToolInvokeMessage: """ Return an image URL message
FlexAI will automatically download the image from the provided URL
and display it to the user.
Args:
image: URL to an image file
Returns:
ToolInvokeMessage: Message object for the tool response
"""
pass
python Link
def create_link_message(self, link: str) -> ToolInvokeMessage:
"""
Return a clickable link message
Args:
link: URL to be displayed as a clickable link
Returns:
ToolInvokeMessage: Message object for the tool response
"""
pass
```
```python Text def create_text_message(self, text: str) -> ToolInvokeMessage: """ Return a text message
Args:
text: Text content to be displayed
Returns:
ToolInvokeMessage: Message object for the tool response
"""
pass
python File
def create_blob_message(self, blob: bytes, meta: dict = None) -> ToolInvokeMessage:
"""
Return a file blob message
For returning raw file data such as images, audio, video,
or documents (PPT, Word, Excel, etc.)
Args:
blob: Raw file data in bytes
meta: File metadata dictionary. Include 'mime_type' to specify
the file type, otherwise 'octet/stream' will be used
Returns:
ToolInvokeMessage: Message object for the tool response
"""
pass
```
```python JSON def create_json_message(self, json: dict) -> ToolInvokeMessage: """ Return a formatted JSON message
Useful for data transmission between workflow nodes.
In agent mode, most LLMs can read and understand JSON data.
Args:
json: Python dictionary to be serialized as JSON
Returns:
ToolInvokeMessage: Message object for the tool response
"""
pass
``
<details>
<summary>Parameters</summary>
URL to an image that will be downloaded and displayed
URL to be displayed as a clickable link
Text content to be displayed
Raw file data in bytes format
File metadata including:
-mime_type`: The MIME type of the file (e.g., "image/png")
- Other metadata relevant to the file
Python dictionary to be serialized as JSON
Tip:
When working with file blobs, always specify the
mime_typein themetadictionary to ensure proper handling of the file. For example:{"mime_type": "image/png"}.
Variables¶
python Standard Variable
from typing import Any
def create_variable_message(self, variable_name: str, variable_value: Any) -> ToolInvokeMessage:
"""
Create a named variable for workflow integration
For non-streaming output variables. If multiple instances with the
same name are created, the latest one overrides previous values.
Args:
variable_name: Name of the variable to create
variable_value: Value of the variable (any Python data type)
Returns:
ToolInvokeMessage: Message object for the tool response
"""
pass
```python Streaming Variable def create_stream_variable_message( self, variable_name: str, variable_value: str ) -> ToolInvokeMessage: """ Create a streaming variable with typewriter effect
When referenced in an answer node in a chatflow application,
the text will be output with a typewriter effect.
Args:
variable_name: Name of the variable to create
variable_value: String value to stream (only strings supported)
Returns:
ToolInvokeMessage: Message object for the tool response
"""
pass
```
Parameters
Name of the variable to be created or updated
Value to assign to the variable:
- For standard variables: Any Python data type
- For streaming variables: String data only
Warning:
The streaming variable method (
create_stream_variable_message) currently only supports string data. Complex data types cannot be streamed with the typewriter effect.
Custom Output Variables¶
Info:
To reference a tool's output variables in a workflow application, you need to define which variables might be output. This is done using the JSON Schema format in your tool's manifest.
Defining Output Schema¶
yaml Tool Manifest with Output Schema
identity:
author: example_author
name: example_tool
label:
en_US: Example Tool
zh_Hans: 示例工具
ja_JP: ツール例
pt_BR: Ferramenta de exemplo
description:
human:
en_US: A simple tool that returns a name
zh_Hans: 返回名称的简单工具
ja_JP: 名前を返す簡単なツール
pt_BR: Uma ferramenta simples que retorna um nome
llm: A simple tool that returns a name variable
output_schema:
type: object
properties:
name:
type: string
description: "The name returned by the tool"
age:
type: integer
description: "The age returned by the tool"
profile:
type: object
properties:
interests:
type: array
items:
type: string
location:
type: string
Schema Structure
The root object defining your tool's output schema Must be "object" for tool output schemas Dictionary of all possible output variables Definition for each output variable, including its type and descriptionWarning:
Even with an output schema defined, you still need to actually return a variable using
create_variable_message()in your implementation code. Otherwise, the workflow will receiveNonefor that variable.
Example Implementation¶
```python Basic Variable Example def run(self, inputs): # Process inputs and generate a name generated_name = "Alice"
# Return the name as a variable that matches the output_schema
return self.create_variable_message("name", generated_name)
python Complex Structure Example
def run(self, inputs):
# Generate complex structured data
user_data = {
"name": "Bob",
"age": 30,
"profile": {
"interests": ["coding", "reading", "hiking"],
"location": "San Francisco"
}
}
# Return individual variables
self.create_variable_message("name", user_data["name"])
self.create_variable_message("age", user_data["age"])
self.create_variable_message("profile", user_data["profile"])
# Also return a text message for display
return self.create_text_message(f"User {user_data['name']} processed successfully")
```
Tip:
For complex workflows, you can define multiple output variables and return them all. This gives workflow designers more flexibility when using your tool.
Examples¶
Complete Tool Implementation¶
```python Weather Forecast Tool
from typing import Any
class WeatherForecastTool: def run(self, inputs: dict) -> Any: # Get location from inputs location = inputs.get("location", "London")
try:
# Call weather API (example only)
weather_data = self._get_weather_data(location)
# Create variables for workflow use
self.create_variable_message("temperature", weather_data["temperature"])
self.create_variable_message("conditions", weather_data["conditions"])
self.create_variable_message("forecast", weather_data["forecast"])
# Create a JSON message for data transmission
self.create_json_message(weather_data)
# Create an image message for the weather map
self.create_image_message(weather_data["map_url"])
# Return a formatted text response
return self.create_text_message(
f"Weather in {location}: {weather_data['temperature']}°C, {weather_data['conditions']}. "
f"Forecast: {weather_data['forecast']}"
)
except Exception as e:
# Handle errors gracefully
return self.create_text_message(f"Error retrieving weather data: {str(e)}")
def _get_weather_data(self, location: str) -> dict:
# Mock implementation - in a real tool, this would call a weather API
return {
"location": location,
"temperature": 22,
"conditions": "Partly Cloudy",
"forecast": "Sunny with occasional showers tomorrow",
"map_url": "https://example.com/weather-map.png"
}
```
Tip:
When designing tools, consider both the direct output (what the user sees) and the variable output (what other workflow nodes can use). This separation provides flexibility in how your tool is used.
{/ Contributing Section DO NOT edit this section! It will be automatically generated by the script. /}