文档
组件
Agentic
工具与 ToolManager

工具与 ToolManager

Tools 模块提供了抽象工具接口和中央工具分发器（ToolManager），用于 Agentic 多轮 rollout。工具遵循 OpenAI function-calling schema，与 LLM 工具调用能力无缝集成。

Tool 基类

from abc import ABC, abstractmethod
from twinkle.data_format import Tool as ToolInfo

class Tool(ABC):

    @abstractmethod
    def __call__(self, tool_name: str, arguments: Dict[str, Any]) -> str:
        """执行工具并返回字符串结果。"""
        raise NotImplementedError

    @abstractmethod
    def tool_info(self) -> ToolInfo:
        """返回 OpenAI 兼容的工具 schema。"""
        raise NotImplementedError

实现自定义工具

from twinkle_agentic.tools.base import Tool

class SearchTool(Tool):

    def __call__(self, tool_name: str, arguments: dict) -> str:
        query = arguments.get('query', '')
        # 执行搜索逻辑
        return f'搜索结果：{query}'

    def tool_info(self):
        return {
            'type': 'function',
            'function': {
                'name': 'search',
                'description': '搜索网络信息。',
                'parameters': {
                    'type': 'object',
                    'properties': {
                        'query': {
                            'type': 'string',
                            'description': '搜索查询。',
                        },
                    },
                    'required': ['query'],
                },
            },
        }

ToolManager

ToolManager 是工具的注册中心和分发器。它解析 LLM 结构化输出中的工具调用，并路由到正确的工具实现。

from twinkle_agentic.tools.tool_manager import ToolManager

# 通过 Tool 实例列表初始化
manager = ToolManager([search_tool, calculator_tool])

# 或通过字典初始化
manager = ToolManager({'search': search_tool, 'calc': calculator_tool})

# 或动态注册
manager = ToolManager()
manager.register(search_tool)
manager.register(calculator_tool)

核心方法

方法说明
register(tool)注册工具（名称从 tool_info() 提取）。
unregister(name)按名称移除工具。
names()列出所有已注册的工具名称。
copy()创建管理器的浅拷贝。
tool_infos()返回所有工具 schema 列表（用于 API 请求）。
__call__(tool_call)分发工具调用并返回结果字符串。

分发工具调用

ToolManager 接受 OpenAI 格式的工具调用字典：

tool_call = {
    'id': 'call_1',
    'type': 'function',
    'function': {
        'name': 'search',
        'arguments': '{"query": "Python 教程"}',
    },
}

result = manager(tool_call)
# result: '搜索结果：Python 教程'

错误处理： 如果工具名未知、参数是无效 JSON 或工具抛出异常，ToolManager 返回描述性错误字符串而不是抛出异常——这保证了 rollout 循环的持续运行。

与 Rollout 集成

from twinkle_agentic.rollout.multi_turn import MultiTurnRollout

rollout = MultiTurnRollout(
    sampler=sampler,
    template=template,
    tool_manager=manager,  # 传入工具管理器
    max_turns=6,
)

Rollout 引擎对模型生成的每个工具调用执行 manager(tool_call)，并将结果作为 {'role': 'tool', 'content': result} 消息追加。

docs