docs: add tools API, tools-selector config type, and OpenAPI tools endpoints

- Plugin SDK APIs: list_tools, get_tool_detail, call_tool (zh/en/ja)
- Config type: tools-selector for multi-select tool picker (zh/en/ja)
- OpenAPI: GET /api/v1/tools, GET /api/v1/tools/{tool_name} (zh/en/ja)
This commit is contained in:
RockChinQ
2026-04-03 17:25:16 +08:00
parent f8ec71299e
commit 47ae62c8bf
9 changed files with 1945 additions and 335 deletions
+81
View File
@@ -249,6 +249,87 @@ parsers = await self.plugin.list_parsers(mime_type="application/pdf")
# Each item includes plugin_id, plugin_author, plugin_name, name, description, supported_mime_types
```
### List All Available Tools
List all available tools in the current LangBot instance (including plugin tools and MCP tools).
```python
async def list_tools(self) -> list[dict[str, Any]]:
"""List all available tools
Returns:
A list of tool dicts, each containing:
- name: Tool name
- label: Display label (i18n)
- description: Tool description (i18n)
- icon: Tool icon
- spec: Tool specification (includes llm_prompt and parameters)
"""
# Example
tools = await self.plugin.list_tools()
for tool in tools:
print(f"Tool: {tool['name']}")
```
### Get Tool Detail
Get detailed information about a specific tool.
```python
async def get_tool_detail(self, tool_name: str) -> dict[str, Any]:
"""Get detailed information about a specific tool
Args:
tool_name: Tool name (metadata.name, e.g. "get_weather_alerts")
Returns:
Tool detail dict containing name, label, description, spec (with parameters and llm_prompt)
"""
# Example
detail = await self.plugin.get_tool_detail("get_weather_alerts")
print(detail['spec']['parameters'])
```
### Call Tool
Call a specific tool.
```python
async def call_tool(
self,
tool_name: str,
parameters: dict[str, Any],
session: dict[str, Any],
query_id: int,
) -> dict[str, Any]:
"""Call a specific tool
Args:
tool_name: Tool name (metadata.name)
parameters: Tool parameters
session: Session info
query_id: Query ID
Returns:
Tool response dict
"""
# Example
result = await self.plugin.call_tool(
tool_name="get_weather_alerts",
parameters={"state": "CA"},
session={},
query_id=0,
)
print(result)
```
<Tip>
Tool names use `metadata.name` (e.g. `echo_tool`, `get_weather_alerts`), without author or plugin name prefix.
</Tip>
### Set Plugin Persistent Data
Persistently store plugin data. Data stored through this interface can only be accessed by this plugin. Values need to be converted to bytes manually.
+28 -1
View File
@@ -50,7 +50,7 @@ For example:
spec:
config:
- name: github_token # Required; configuration item name, used for retrieval in the plugin
type: string # Required; configuration item type, supports string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector, etc.
type: string # Required; configuration item type, supports string, integer, float, boolean, select, prompt-editor, llm-model-selector, bot-selector, tools-selector, etc.
label: # Required; configuration item display name, supports multilingual. Language codes follow RFC 4646 standard.
en_US: Github Token
zh_Hans: Github Token
@@ -274,6 +274,33 @@ bot_uuid = self.get_config()['bot']
print(bot_uuid) # Output: '550e8400-e29b-41d4-a716-446655440000'
```
### type: tools-selector
Tool selector. Displays a multi-select tool selector where you can choose registered tools (plugin tools and MCP tools), with the final result represented as an array of tool names.
```yaml
- name: selected_tools
type: tools-selector
...
```
Using the selected tool names in the plugin:
```python
# Get selected tool names from config
selected_tools = self.get_config()['selected_tools']
print(selected_tools) # Output: ['get_weather_alerts', 'web_search']
# Call selected tools
for tool_name in selected_tools:
result = await self.plugin.call_tool(
tool_name=tool_name,
parameters={"query": "hello"},
session={},
query_id=0,
)
```
## What's Next
This tutorial will guide you through step-by-step completion of plugin functionality.