Fu-Jie_openwebui-extensions/plugins/pipes/github-copilot-sdk/TOOLS_USAGE.md

🛠️ Custom Tools Usage / 自定义工具使用指南

Overview / 概览

This pipe supports OpenWebUI Native Tools (Functions) and Custom Python Tools. 本 Pipe 支持 OpenWebUI 原生工具 (Functions) 和 自定义 Python 工具。

---

🚀 OpenWebUI Native Tools / OpenWebUI 原生工具 (v0.3.0)

New in v0.3.0: You can use any tool defined in OpenWebUI directly with Copilot. v0.3.0 新增: 您可以直接在 Copilot 中使用 OpenWebUI 中定义的任何工具。

How to use / 如何使用:

1. Go to Workspace -> Tools.
2. Create a tool (e.g. get_weather).
3. In Copilot Chat settings (Valves), ensure ENABLE_OPENWEBUI_TOOLS is True (default).
4. Ask Copilot: "Search for the latest news" or "Check weather".

Note / 注意:

• Tool names are automatically sanitized to match Copilot SDK requirements (e.g. my.tool -> my_tool).
• 工具名称会自动净化以符合 Copilot SDK 要求（例如 my.tool 变为 my_tool）。

---

📦 Python Custom Tools / Python 自定义工具

This pipe includes 1 example custom tool that demonstrates how to use GitHub Copilot SDK's tool calling feature directly in Python code. 本 Pipe 包含 1 个示例自定义工具，展示如何使用 GitHub Copilot SDK 的工具调用功能。

1. generate_random_number / 生成随机数

Description: Generate a random integer 描述： 生成随机整数

Parameters / 参数:

• min (optional): Minimum value (default: 1)
• max (optional): Maximum value (default: 100)
• min (可选): 最小值 (默认: 1)
• max (可选): 最大值 (默认: 100)

Example / 示例:

User: "Give me a random number between 1 and 10"
Copilot: [calls generate_random_number with min=1, max=10] "Generated random number: 7"

用户: "给我一个 1 到 10 之间的随机数"
Copilot: [调用 generate_random_number，参数 min=1, max=10] "生成的随机数: 7"

---

⚙️ Configuration / 配置

Enable Tools / 启用工具

In Valves configuration: 在 Valves 配置中：

ENABLE_TOOLS: true
AVAILABLE_TOOLS: all

Select Specific Tools / 选择特定工具

Instead of enabling all tools, specify which ones to use: 不启用所有工具，而是指定要使用的工具：

ENABLE_TOOLS: true
AVAILABLE_TOOLS: generate_random_number

---

🔧 How Tool Calling Works / 工具调用的工作原理

1. User asks a question / 用户提问
        ↓
2. Copilot decides if it needs a tool / Copilot 决定是否需要工具
        ↓
3. If yes, Copilot calls the appropriate tool / 如果需要，调用相应工具
        ↓
4. Tool executes and returns result / 工具执行并返回结果
        ↓
5. Copilot uses the result to answer / Copilot 使用结果回答

Visual Feedback / 可视化反馈

When tools are called, you'll see: 当工具被调用时，你会看到：

🔧 **Calling tool**: `generate_random_number`
✅ **Tool `generate_random_number` completed**

Generated random number: 7

---

📚 Creating Your Own Tools / 创建自定义工具

Want to add your own Python tools? Follow this pattern (module-level tools): 想要添加自己的 Python 工具？遵循这个模式（模块级工具）：

from pydantic import BaseModel, Field
from copilot import define_tool

class MyToolParams(BaseModel):
    param_name: str = Field(description="Parameter description")


@define_tool(description="Clear description of what the tool does and when to use it")
async def my_tool(params: MyToolParams) -> str:
    # Do something
    result = do_something(params.param_name)
    return f"Result: {result}"

Then register it in _initialize_custom_tools(): 然后将它添加到 _initialize_custom_tools():

def _initialize_custom_tools(self):
    if not self.valves.ENABLE_TOOLS:
        return []

    all_tools = {
        "generate_random_number": generate_random_number,
        "my_tool": my_tool,  # ✅ Add here
    }

    if self.valves.AVAILABLE_TOOLS == "all":
        return list(all_tools.values())

    enabled = [t.strip() for t in self.valves.AVAILABLE_TOOLS.split(",")]
    return [all_tools[name] for name in enabled if name in all_tools]

---

⚠️ Important Notes / 重要说明

Security / 安全性

• Tools run in the same process as the pipe

• Be careful with tools that execute code or access files

• Always validate input parameters

• 工具在与 Pipe 相同的进程中运行

• 谨慎处理执行代码或访问文件的工具

• 始终验证输入参数

Performance / 性能

• Tool execution is synchronous during streaming

• Long-running tools may cause delays

• Consider adding timeouts for external API calls

• 工具执行在流式传输期间是同步的

• 长时间运行的工具可能导致延迟

• 考虑为外部 API 调用添加超时

Debugging / 调试

• Enable DEBUG: true to see tool events in the browser console

• Check tool calls in 🔧 Calling tool messages

• Tool errors are displayed in the response

• 启用 DEBUG: true 在浏览器控制台查看工具事件

• 在 🔧 Calling tool 消息中检查工具调用

• 工具错误会显示在响应中

---

Version: 0.3.0 Last Updated: 2026-02-05