Инструменты агента

Инструменты — функции, которые агент может вызывать в процессе выполнения задачи (tool use в Claude API).

Как работает tool use

1. Claude получает задачу и список доступных инструментов
2. Claude решает вызвать инструмент → возвращает блок tool_use
3. runner.py обрабатывает вызов → выполняет функцию → передаёт результат обратно Claude
4. Claude использует результат и продолжает рассуждение

Структура инструмента

# tools/my_tool.py

MY_TOOL = {
    "name": "search_company",
    "description": "Ищет информацию о компании по ИНН",
    "input_schema": {
        "type": "object",
        "properties": {
            "inn": {
                "type": "string",
                "description": "ИНН компании (10 или 12 цифр)"
            }
        },
        "required": ["inn"]
    }
}

def handle_search_company(params: dict) -> str:
    inn = params["inn"]
    # логика поиска
    return f"Результат поиска для ИНН {inn}: ..."

Регистрация инструмента

В tools/__init__.py:

from tools.my_tool import MY_TOOL, handle_search_company

TOOL_REGISTRY = {
    "search_company": {
        "definition": MY_TOOL,
        "handler": handle_search_company,
    },
    # другие инструменты...
}

Использование в runner.py

tools = [t["definition"] for t in TOOL_REGISTRY.values()]

# При получении tool_use блока:
tool_name = tool_use_block.name
handler = TOOL_REGISTRY[tool_name]["handler"]
result = handler(tool_use_block.input)

Рекомендации

• Один файл — один инструмент (или тематическая группа)
• Описание инструмента пишите так, чтобы Claude понял, когда его использовать
• Обрабатывайте ошибки внутри handler — возвращайте строку с описанием ошибки
• Не делайте инструменты слишком широкими — лучше 3 узких, чем 1 широкий