# 如何定义工具Tool组件
根据agentUniverse领域组件的设计特性，同其他组件一样，创建一个工具Tool定义由2部分组成:
* tool_xx.yaml
* tool_xx.py

其中`tool_xx.yaml`包含了Tool组件的名称、描述、出入参等重要属性信息；`tool_xx.py`包含了工具的具体定义。理解这一原理后，让我们具体看看该如何创建这两部分内容。

## 创建Tool配置 - tool_xx.yaml
我们将详细介绍配置中的各组成部分。

### 设置Tool的基本属性
* `name`:  工具名称，您可以按照自己的期望设置任何名字
* `description`:  工具描述, 按照您的实际需求填写
* `input_keys`: 类型`list`，输入参数列表

### 设置Tool组件元信息
**`metadata` - 组件元信息**
* `type` : 组件类型，'TOOL'
* `module`: 工具实体包路径
* `class`: 工具实体类名

### 一个Tool定义配置的实际样例
```yaml
name: 'google_search_tool'
description: 'demo google search tool'
input_keys: ['input']
metadata:
  type: 'TOOL'
  module: 'xxx.tool.google_search_tool'
  class: 'GoogleSearchTool'
```

上述是一个实际的Tool配置的样例。

除了上述介绍的标准配置项，您还可以在我们的样例工程中的`sample_standard_app.intelligence.agentic.tool`路径下，找到更多Tool的yaml配置文件样例。

除此之外agentuniverse不限制用户对Tool的yaml配置内容进行扩展，您可以根据自己的要求创建任何自定义配置key,但请注意不要与上述默认的配置关键字重名。

## 创建Tool领域行为定义 - tool_xx.py

### 创建Tool类对象
创建对应的Tool类对象并继承agentUniverse框架Tool基础类 `Tool`;

### 编写工具类对象execute方法
在`execute`方法中编写工具的实际逻辑片段。

```text
@abstractmethod
def execute(self, **kwargs):
    raise NotImplementedError
```

#### 一个实际的tool对象定义样例
```python
from langchain_community.utilities.google_serper import GoogleSerperAPIWrapper
from agentuniverse.agent.action.tool.tool import Tool

class GoogleSearchTool(Tool):
    """The demo google search tool.

    Implement the execute method of demo google search tool, using the `GoogleSerperAPIWrapper` to implement a simple Google search.

    Note:
        You need to sign up for a free account at https://serper.dev and get the serper api key (2500 free queries).
    """

    def execute(self, input: str):
        # get top3 results from Google search.
        search = GoogleSerperAPIWrapper(serper_api_key='', k=3, type="search")
        return search.run(query=input)
```
在这个样例中我们接入了google的search工具, 该工具会检索返回与搜索内容最相近的的3条内容。

## 关注您定义的Tool所在的包路径
通过上面的Tool配置与定义，您已经掌握了工具创建的所有步骤；接下去我们将使用这些Tool，在使用前请关注创建的Tool是否在正确的包扫描路径内。

在agentUniverse项目的config.toml中需要配置Tool配置对应的package, 请再次确认您创建的文件所在的包路径是否在`CORE_PACKAGE`中`tool`路径或其子路径下。

以示例工程中的配置为例，如下：
```yaml
[CORE_PACKAGE]
# Scan and register tool components for all paths under this list, with priority over the default.
tool = ['sample_standard_app.intelligence.agentic.tool']
```

# 如何使用工具Tool组件
## 在Agent中配置使用
您可以根据[智能体创建与使用](../智能体/智能体创建与使用.md)中的内容在agent的action下的tool中设置您创建的任意工具。

工具定义示例可参考：[python_runner](../../../../../../examples/sample_apps/toolkit_demo_app/intelligence/agentic/tool/python_runner.yaml)

工具调用可参考示例：[demo_agent_with_basic_tool.yaml](../../../../../../examples/sample_apps/toolkit_demo_app/intelligence/agentic/agent/agent_instance/demo_agent_with_basic_tool.yaml)

## 使用Tool管理器
通过Tool管理器中的`.get_instance_obj(xx_tool_name)` 方法可以获取对应名称的Tool实例, 使用`run`方法进行调用。

```python
from agentuniverse.agent.action.tool.tool_manager import ToolManager

tool = ToolManager().get_instance_obj('your_tool_name')
tool_input = {'your_input_key': 'input_values'}
tool.run(**tool_input)
```

# 了解更多已有工具Tool
框架提供的更多Tool示例在`sample_standard_app.intelligence.agentic.tool`包路径下，您可以进一步查看对应的工具。

# 总结
至此您已经掌握了工具Tool的定义与使用，赶快去尝试创建与使用工具吧。
