# Agent Tools - 工具系统

## 职责

工具系统提供 Agent 可调用的各种能力：

1. **工具注册** (`registry.py`)
   - 工具装饰器 `@tool`
   - 全局工具注册表
   - 工具发现和调用

2. **Schema 生成** (`schema.py`)
   - 将 Python 函数转换为 OpenAI function calling schema
   - 支持类型注解和文档字符串

3. **工具模型** (`models.py`)
   - `ToolResult` - 工具执行结果
   - `ToolContext` - 工具执行上下文

4. **内置工具** (`builtin/`)
   - `read_file` - 读取文件
   - `edit_file` - 编辑文件
   - `write_file` - 写入文件
   - `glob_files` - 文件搜索
   - `grep_content` - 内容搜索
   - `bash_command` - 执行 Shell 命令
   - `skill` - 加载技能文档

5. **高级工具** (`advanced/`)
   - LSP - Language Server Protocol 集成
   - WebFetch - 网页抓取

6. **适配器** (`adapters/`)
   - Browser-use - 浏览器自动化

## 工具开发

创建自定义工具：

```python
from agent.tools import tool, ToolResult

@tool(description="Calculate sum of two numbers")
async def add(a: int, b: int, uid: str = "") -> ToolResult:
    """
    Add two numbers

    Args:
        a: First number
        b: Second number
        uid: User ID (auto-injected)

    Returns:
        ToolResult with sum
    """
    return ToolResult(
        success=True,
        data={"sum": a + b}
    )
```

## 文件说明

- `registry.py` - 工具注册表和装饰器
- `schema.py` - OpenAI schema 生成
- `models.py` - ToolResult 等数据模型
- `sensitive.py` - 敏感数据处理
- `url_matcher.py` - URL 模式匹配
- `builtin/` - 核心工具
- `advanced/` - 高级工具
- `adapters/` - 外部集成

## 目录结构

```
tools/
├── __init__.py          # 工具装饰器和注册表
├── registry.py          # 核心注册逻辑
├── schema.py            # Schema 生成
├── models.py            # 数据模型
├── builtin/             # 核心工具（必需）
│   ├── read.py
│   ├── edit.py
│   ├── write.py
│   ├── glob.py
│   ├── grep.py
│   ├── bash.py
│   └── skill.py
├── advanced/            # 高级工具（可选）
│   ├── lsp.py
│   └── webfetch.py
└── adapters/            # 外部集成（可选）
    └── browser_use/
```