agentscope.tool¶

agentscope中的工具模块。

class Toolkit[source]¶

基础类: StateModule

支持函数级和组级工具管理的类。

使用以下方法管理工具函数：

register_tool_function
remove_tool_function

对于团队级别的管理：

create_tool_group
update_tool_groups
remove_tool_groups

MCP 相关方法：

register_mcp_server
remove_mcp_servers

要运行工具函数或从已激活的工具中获取数据：

call_tool_function
get_json_schemas
get_tool_group_notes

__init__()[source]¶

初始化工具包。

Return type:: 无

create_tool_group(group_name, description, active=False, notes=None)[source]¶

创建一个工具组来组织工具函数

Parameters:

group_name (str) – 工具组的名称。
description (str) – 工具组的描述。
active (bool, 默认为 False) – 如果组处于活动状态，意味着该组中的工具功能包含在JSON模式中。
notes (str | None, 可选) – 用于提醒智能体如何正确使用工具函数的备注信息，可被整合进系统提示中。

Return type:

无

update_tool_groups(group_names, active)[source]¶

更新指定工具组的激活状态。

Parameters:

group_names (list[str]) – 待更新的工具组名称列表。
active (bool) – 指示是否应激活或停用工具组。

Return type:

无

remove_tool_groups(group_names)[source]¶

根据组名称从工具包中移除工具函数。

Parameters:: group_names (str) – 要从工具包中移除的群组名称。
Return type:: 无

register_tool_function(tool_func, group_name='basic', preset_kwargs=None, func_description=None, json_schema=None, include_long_description=True, include_var_positional=False, include_var_keyword=False, postprocess_func=None)[source]¶

注册一个工具函数到工具包。

Parameters:

tool_func (ToolFunction) – 工具函数，可以是异步或同步的，流式或非流式的，但响应必须是一个 ToolResponse 对象。
group_name (str | Literal[“basic”], 默认为 “basic”) – 工具函数的所属组。"basic"组中的工具始终包含在JSON模式中，而其他组的工具仅在所属组激活时包含。
preset_kwargs ( dict[str, JSONSerializableObject] | None , 可选 ) – 由用户预设的参数, 这些参数不会被包含在 JSON 模式中, 也不会对智能体公开。
func_description (str | None, optional) – 函数描述。如果未提供，则会从docstring中自动提取描述。
json_schema (dict | None, 可选) – 为工具函数手动提供的 JSON 模式，应为 {"type": "function", "function": {"name": "function_name", "description": "xx", "parameters": {...}}}
include_long_description (bool, 默认为 True) – 当从文档字符串中提取函数描述时, 是否包含长描述。
include_var_positional (bool, 默认为 False) – 是否在函数模式中包含可变位置参数 (*args)。
include_var_keyword (bool, 默认为 False) – 是否在函数模式中包含可变关键字参数 (**kwargs)。
postprocess_func (Callable[[ToolUseBlock, ToolResponse], ToolResponse | None] | None, 可选) – 一个后处理函数，在工具函数执行后被调用，接收工具调用块和工具响应作为参数。如果它返回None，工具结果将按原样返回。如果它返回一个ToolResponse，返回的块将被用作最终工具结果。

Return type:

无

remove_tool_function(tool_name)[source]¶

通过名称从工具包中移除工具函数。

Parameters:: tool_name (str) – 要移除的工具函数名称。
Return type:: 无

get_json_schemas()[source]¶

从属于活跃组的工具函数中获取JSON模式。

注意

预设关键字参数会从 JSON 模式中移除，如果已设置，则会应用扩展模型。

示例

Example of tool function JSON schemas¶

[
    {
        "type": "function",
        "function": {
            "name": "google_search",
            "description": "Search on Google.",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The search query."
                    }
                },
                "required": ["query"]
            }
        }
    },
    ...
]

Returns:: 一组函数的JSON模式列表。
Return type:: 列表[字词典]

set_extended_model(func_name, model)[source]¶

设置工具函数的扩展模型，以便原始JSON模式得到扩展。

Parameters:

func_name (str) – 工具函数的名称。
model (Union[Type[BaseModel], None]) – 待设置的扩展模型。

Return type:

无

async remove_mcp_clients(client_names)[source]¶

通过名称从 MCP 客户端移除工具函数。

Parameters:: client_names (list[str]) – MCP客户端的名称，用于初始化客户端实例。
Return type:: 无

async call_tool_function(tool_call)[source]¶

通过ToolUseBlock执行工具函数并以统一的流式模式返回工具响应块，即一个异步生成器，生成ToolResponse对象。

注意

工具响应块将会被积累。

Parameters:: tool_call (ToolUseBlock) – 一个工具调用区块。
Yields:: ToolResponse – 工具响应片段，以累积方式呈现。
Return type:: AsyncGenerator[ToolResponse, 无]

async register_mcp_client(mcp_client, group_name='basic', enable_funcs=None, disable_funcs=None, preset_kwargs_mapping=None, postprocess_func=None)[source]¶

从一个MCP客户端注册工具函数。

Parameters:

mcp_client (MCPClientBase) – 用于连接MCP服务器的MCP客户端实例。
group_name (str, 默认为 “basic”) – 工具函数将添加到的组名。
enable_funcs (list[str] | None, optional) - 要添加到工具包中的函数。如果为 None，则将添加 MCP 服务器中的所有工具函数。
disable_funcs (list[str] | None, 可选) – 将被过滤掉的函数列表。如果为 None，则表示不过滤任何工具函数。
preset_kwargs_mapping (dict[str, dict[str, Any]] | None) – (Optional[dict[str, dict[str, Any]]], 默认为 None): 预设的关键字参数映射，其键为工具函数名称，值为预设的关键字参数。
postprocess_func (Callable[[ToolUseBlock, ToolResponse], ToolResponse | None] | None, optional) – 一种后处理函数，将在工具函数执行后被调用，接受工具调用块和工具响应作为参数。如果它返回 None，工具结果将原样返回。如果它返回一个 ToolResponse，返回的块将被用作最终工具结果。

Return type:

无

state_dict()[source]¶

获取工具集的状态字典。

Returns:: 一个字典，包含活跃的工具组名称。
Return type:: 字典[字符串, 任意类型]

load_state_dict(state_dict, strict=True)[source]¶

将状态字典加载到工具包中。

Parameters:

state_dict (dict) – 要加载的状态字典，其中应包含 "active_groups" 键，其值必须是一个组名称列表。
strict (bool, 默认为 True) – 如果为 True，当模块中的任何键在state_dict中未找到时会抛出错误。如果为 False，则跳过缺失的键。

Return type:

无

get_activated_notes()[source]¶

从活动工具组中获取备注信息，这些信息可用于构建智能体的系统提示。

Returns:: 活跃工具组的合并笔记。
Return type:: 字符串

reset_equipped_tools(**kwargs)[source]¶

选择合适的工具来装备自己，以便能够完成任务。此函数的每个参数代表一组相关工具，而值表示是否激活该组。此外，此函数的工具响应将包含使用它们的注意事项，您必须注意并遵循。您也可以重使用此函数来检查工具组的注意事项。

注意，此函数将重置工具，因此原有工具将被首先移除。

Parameters:: kwargs (任意类型)
Return type:: 工具响应

clear()[source]¶

清除工具包，移除所有工具函数和分组。

Return type:: 无

class ToolResponse[source]¶

基础：object

工具调用的结果块。

content: List[TextBlock | ImageBlock | AudioBlock]¶: 工具函数的执行输出。

metadata: dict | None = None¶: 在智能体中可访问的元数据，这样我们就不需要解析工具结果块。

stream: bool = False¶: 工具输出是否开启流式输出。

__init__(content, metadata=None, stream=False, is_last=True, is_interrupted=False, id=<factory>)¶

Parameters:

内容 (列表[TextBlock | ImageBlock | AudioBlock])
metadata (dict | None)
stream (布尔值)
is_last (bool) - 是否为最后一个
is_interrupted (bool) - 是否被中断
id (字符串)

Return type:

无

is_last: bool = True¶: 是否为流式工具执行中的最后响应。

is_interrupted: bool = False¶: 工具执行是否被中断。

id: str¶: 工具反馈的身份。

async execute_python_code(code, timeout=300, **kwargs)[source]¶

在临时文件中执行给定的python代码并捕获返回代码、标准输出和错误。请注意您必须print输出才能获得结果，且临时文件将在执行后立即被移除。

Parameters:

code (str) – 需要被执行的 Python 代码。
timeout (float, 默认为 300) – 代码允许运行的最长时间（以秒为单位）。
kwargs (任何)

Returns:

包含执行代码的返回码、标准输出和标准错误信息的响应。

Return type:

ToolResponse

async execute_shell_command(command, timeout=300, **kwargs)[source]¶

执行给定指令并在、与标签内返回状态码、标准输出和错误信息。

Parameters:

command (str) – 要执行的shell命令。
timeout (float, 默认值为 300) – 命令运行允许的最大时间（单位：秒）。
kwargs (任何)

Returns:

工具响应包含执行命令的返回码、标准输出和标准错误。

Return type:

ToolResponse

async view_text_file(file_path, ranges=None)[source]¶

使用行号查看指定范围内的文件内容。如果未提供ranges，将返回整个文件。

Parameters:

file_path (str) – 目标文件路径。
ranges (list[int] | None) – 要查看的行号范围（例如显示第1至100行：[1, 100]），包含起止行。如未提供，将返回整个文件。若要查看最后100行，请使用[-100, -1]。

Returns:

工具响应包含文件内容或错误信息。

Return type:

ToolResponse

async write_text_file(file_path, content, ranges=None)[source]¶

在文本文件中创建/替换/覆盖内容。当提供了ranges时，将在指定范围内进行内容替换。否则，将覆盖整个文件（如果存在）。

Parameters:

file_path (str) – 目标文件路径。
content (str) – 要写入的内容。
ranges (list[int] | None, defaults to None) – 需要被替换的行范围。如果为 None，则将覆盖整个文件。

Returns:

工具响应包含写入操作的结果。

Return type:

ToolResponse

async insert_text_file(file_path, content, line_number)[source]¶

在文本文件的指定行号处插入内容。

Parameters:

file_path (str) – 目标文件路径。
content (str) – 需要被插入的内容。
line_number (int) – 从第1行开始计数的插入内容的位置行号。若超出文件行数，则会将内容追加至文件末尾。

Returns:

包含插入操作结果的工具响应。

Return type:

ToolResponse

dashscope_text_to_image(prompt, api_key, n=1, size='1024*1024', model='wanx-v1', use_base64=False)[source]¶

根据给定的提示生成图像，并返回图像URL或base64数据。

Parameters:

prompt (str) – 用于生成图像的文本提示词。
api_key (str) – 用于dashscope api的密钥。
n (int, 默认为 1) – 要生成的图像数量。
size (Literal["1024*1024", "720*1280", "1280*720"], defaults to "1024*1024") - 图像的尺寸。
model (str, 默认值 '"wanx-v1"') – 要使用的模型，例如 "wanx-v1"、"qwen-image"、"wan2.2-t2i-flash" 等。
use_base64 (bool, defaults to ‘False’) – 是否对图像使用 base64 数据。

Returns:

一个包含生成内容（ImageBlock/TextBlock/AudioBlock）的ToolResponse，或者在操作失败时包含错误信息。

Return type:

ToolResponse

dashscope_text_to_audio(text, api_key, model='sambert-zhichu-v1', sample_rate=48000)[source]¶

将给定文本转换为音频。

Parameters:

text (str) – 需要转换为音频的文本。
api_key (str) – dashscope API的密钥。
model (str, defaults to ‘sambert-zhichu-v1’) – 要使用的模型。完整模型列表可在官方文档中找到。
sample_rate (int, 默认为48000) - 音频的采样率。

Returns:

一个包含生成内容（ImageBlock/TextBlock/AudioBlock）或在操作失败时包含错误信息的ToolResponse。

Return type:

ToolResponse

dashscope_image_to_text(image_urls, api_key, prompt='Describe the image', model='qwen-vl-plus')[source]¶

根据给定的图片生成文本。

Parameters:

image_urls (str | Sequence[str]) – 单个或多个图片的网址。
api_key (str) – 用于dashscope api的密钥。
prompt (str, 默认为 ‘Describe the image’) - 文本提示词。
model (str, defaults to ‘qwen-vl-plus’) – 在DashScope多模态API中使用的模型。

Returns:

一个ToolResponse，包含生成的内容（ImageBlock/TextBlock/AudioBlock）或在操作失败时包含错误信息。

Return type:

ToolResponse

openai_text_to_image(prompt, api_key, n=1, model='dall-e-2', size='256x256', quality='auto', style='vivid', response_format='url')[source]¶

根据给定提示生成图像，并返回图像URL或base64数据。

Parameters:

prompt (str) – 用于生成图像的文本提示。
api_key (str) – OpenAI API 的 API 密钥。
n (int, 默认为 1) – 要生成的图像数量。
model (Literal["dall-e-2", "dall-e-3"], defaults to "dall-e-2") – 用于图像生成的模型。
size (Literal[“256x256”, “512x512”, “1024x1024”, “1792x1024”, “1024x1792”], 默认为 “256x256”) – 生成图像的尺寸。对于gpt-image-1必须是以下之一：1024x1024, 1536x1024 (横向), 1024x1536 ( 纵向), 或auto (默认值)；对于dall-e-2必须是256x256, 512x512, 或1024x1024之一；对于dall-e-3必须是1024x1024, 1792x1024, 或1024x1792之一。
quality (Literal[“auto”, “standard”, “hd”, “high”, “medium”, “low”], 默认值为 “auto”) –
待生成图像的质量。
- auto (默认值) 将自动选择给定模型的最佳质量。
- high, medium 和 low 适用于 gpt-image-1。
- hd 和 standard 适用于 dall-e-3。
- standard 是 dall-e-2 的唯一选项。
style (Literal["vivid", "natural"], 默认值 "vivid") –
生成图像的风格。此参数仅支持 dall-e-3。必须是 vivid 或 natural 中的一种。
- Vivid 使模型倾向于生成超现实和戏剧化的图像。
- Natural 使模型生成更自然，看起来不那么超现实的图像。
response_format (Literal[“url”, “b64_json”], 默认为 “url”) –
用于指定 dall-e-2 和 dall-e-3 生成图像的返回格式。
- 必须是“url”或“b64_json”之一。
- URL 仅在图像生成后的 60 分钟内有效。
- 此参数不适用于 gpt-image-1，该模型始终返回 base64 编码的图像。

Returns:

一个包含生成内容（图像块/文本块/音频块）的 ToolResponse，或在操作失败时包含错误信息。

Return type:

ToolResponse

openai_text_to_audio(text, api_key, model='tts-1', voice='alloy', speed=1.0, res_format='mp3')[source]¶

使用指定模型和语音将文本转换为音频文件。

Parameters:

text (str) – 要转换为音频的文本。
api_key (str) – OpenAI API 的 API 密钥。
model (Literal[“tts-1”, “tts-1-hd”], 默认值为 “tts-1”) – 用于文本到语音转换的模型。
voice (Literal[“alloy”, “echo”, “fable”, “onyx”, “nova”, “shimmer”], defaults to “alloy”) – 用于音频输出的声音。
speed (float, 默认值为 1.0) - 音频播放的速度。值为1.0时表示正常速度。
res_format (Literal[“mp3”, “wav”, “opus”, “aac”, “flac”, “wav”, “pcm”], 默认为 “mp3”) – 音频文件的格式。

Returns:

一个ToolResponse，包含生成的内容（ImageBlock/TextBlock/AudioBlock）或在操作失败时包含错误信息。

Return type:

ToolResponse

openai_edit_image(image_url, prompt, api_key, model='dall-e-2', mask_url=None, n=1, size='256x256', response_format='url')[source]¶

根据提供的掩码和提示编辑图像，并返回编辑后的图像URL或base64数据。

Parameters:

image_url (str) – 需要编辑的图像的文件路径或URL。
prompt (str) – 描述对图像所需编辑的文本提示。
api_key (str) – OpenAI API 的 API 密钥。
model (Literal["dall-e-2", "gpt-image-1"], 默认为 "dall-e-2") – 用于图像生成的模型。
mask_url (str | None, 默认为 None) – 用于指定编辑区域的遮罩图像文件路径或URL。
n (int, 默认为 1) – 需要生成的编辑后图像数量。
size（Literal[“256x256”, “512x512”, “1024x1024”]，默认值为“256x256”）– 编辑后图片的尺寸。
response_format (Literal[“url”, “b64_json”], defaults to “url”) –
生成图像的返回格式。
- 必须是 "url" 或 "b64_json" 之一。
- 生成的URL仅在60分钟内有效。
- gpt-image-1不支持此参数，该模型将始终返回base64编码的图像。

Returns:

一个包含生成内容（ImageBlock/TextBlock/AudioBlock）的ToolResponse，或者在操作失败时包含错误信息。

Return type:

ToolResponse

openai_create_image_variation(image_url, api_key, n=1, model='dall-e-2', size='256x256', response_format='url')[source]¶

创建图像的变体并返回图像的URL或base64数据。

Parameters:

image_url (str) – 从中生成变体的图像文件路径或URL。
api_key (str) – OpenAI API 的 API 密钥。
n (int, 默认为 1) – 生成图像变体的数量。
model (`Literal["dall-e-2"]`, 默认值为 dall-e-2) – 用于图像变化的模型。
size (Literal[“256x256”, “512x512”, “1024x1024”], 默认为 “256x256”) – 生成的图像变体的尺寸。
response_format (Literal[“url”, “b64_json”], defaults to “url”) –
生成图像的返回格式。
- 必须是 url 或 b64_json 之一。
- URL仅在图像生成后的60分钟内有效。

Returns:

一个包含生成内容（ImageBlock/TextBlock/AudioBlock）或在操作失败时包含错误信息的ToolResponse。

Return type:

ToolResponse

openai_image_to_text(image_urls, api_key, prompt='Describe the image', model='gpt-4o')[source]¶

使用指定模型为给定图像生成描述性文本，并返回生成的文本。

Parameters:

image_urls (str | list[str]) – 指向需要被描述图片的URL或URL列表。
api_key (str) – OpenAI API 的 API 密钥。
prompt (str, defaults to “Describe the image”) – 用于指导智能体如何描述图像的提示语。
model (str, 默认为 “gpt-4o”) – 生成文本描述所要使用的模型。

Returns:

一个包含生成内容（ImageBlock/TextBlock/AudioBlock）或在操作失败时包含错误信息的ToolResponse。

Return type:

ToolResponse

openai_audio_to_text(audio_file_url, api_key, language='en', temperature=0.2)[source]¶

使用OpenAI的转录服务将音频文件转换为文本。

Parameters:

audio_file_url (str) – 需要转录的音频文件的文件路径或URL。
api_key (str) – OpenAI API 的 API 密钥。
语言 (str, 默认值 “en”) – 输入音频的语言，采用 ISO-639-1格式（例如，“en”、“zh”、“fr”）。提高准确性和降低延迟。
temperature (float, 默认为 0.2) – 转录的温度参数，影响输出的随机性。

Returns:

一个包含生成内容（ImageBlock/TextBlock/AudioBlock）或在操作失败时包含错误信息的ToolResponse。

Return type:

ToolResponse