open-webui/Fu-Jie_openwebui-extensions

Fork 0

Files

fujie 795ac34cd9 chore: archive development research artifacts and debug scripts

2026-02-07 12:49:42 +08:00

4.8 KiB

Raw Blame History

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

Overview / 概览

This pipe includes 1 example custom tool that demonstrates how to use GitHub Copilot SDK's tool calling feature.

本 Pipe 包含 1 个示例自定义工具，展示如何使用 GitHub Copilot SDK 的工具调用功能。

🚀 Quick Start / 快速开始

1. Enable Tools / 启用工具

In Valves configuration: 在 Valves 配置中：

ENABLE_TOOLS: true
AVAILABLE_TOOLS: all

2. Test with Conversations / 测试对话

Try these examples: 尝试这些示例：

English:

"Give me a random number between 1 and 100"

中文：

"给我一个 1 到 100 之间的随机数"

📦 Included Tools / 内置工具

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"

⚙️ Advanced Configuration / 高级配置

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 tools? Follow this pattern (module-level tools):
想要添加自己的工具？遵循这个模式（模块级工具）：

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 消息中检查工具调用
工具错误会显示在响应中

📖 References / 参考资料

Copilot SDK Documentation
COPILOT_TOOLS_QUICKSTART.md - Detailed implementation guide
JSON Schema - For parameter definitions

Version: 0.2.3
Last Updated: 2026-01-27

4.8 KiB Raw Blame History Unescape Escape