Tool Use в Claude API: агенты с инструментами

Tool use позволяет Claude вызывать функции из твоего кода — получать погоду, читать файлы, делать поиск. Claude решает когда вызвать инструмент, ты решаешь как его выполнить.

Как работает протокол

1. Ты отправляешь messages + список tools
2. Claude отвечает с stop_reason="tool_use" и блоком tool_use в content
3. Ты выполняешь инструмент и возвращаешь tool_result
4. Claude генерирует финальный текстовый ответ

Описание инструмента (JSON Schema)

TOOLS = [
    {
        "name": "get_weather",
        "description": "Получает текущую погоду для города. Используй когда спрашивают о погоде.",
        "input_schema": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string",
                    "description": "Название города на английском"
                }
            },
            "required": ["city"]
        }
    }
]

Первый запрос с tools=

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=TOOLS,
    messages=[{"role": "user", "content": "Какая погода в Москве?"}]
)

print(response.stop_reason)  # "tool_use"

Обработка вызова инструмента

for block in response.content:
    if block.type == "tool_use":
        tool_name = block.name          # "get_weather"
        tool_input = block.input        # {"city": "Moscow"}
        tool_id = block.id

        # Выполняем инструмент
        result = get_weather(tool_input["city"])

        # Возвращаем результат Claude
        messages.append({"role": "assistant", "content": response.content})
        messages.append({
            "role": "user",
            "content": [{
                "type": "tool_result",
                "tool_use_id": tool_id,
                "content": result
            }]
        })

Полный agentic loop

def run_agent(user_message: str) -> str:
    messages = [{"role": "user", "content": user_message}]

    while True:
        response = client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            tools=TOOLS,
            messages=messages,
        )

        if response.stop_reason == "end_turn":
            return response.content[0].text

        # Обрабатываем все вызовы инструментов
        messages.append({"role": "assistant", "content": response.content})
        tool_results = []

        for block in response.content:
            if block.type == "tool_use":
                result = execute_tool(block.name, block.input)
                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        messages.append({"role": "user", "content": tool_results})