Программный вызов инструментов

Программный вызов инструментов позволяет Claude писать код, который вызывает ваши инструменты программно в контейнере выполнения кода, вместо того чтобы требовать циклических обращений через модель для каждого вызова инструмента. Это снижает задержку для многоинструментальных рабочих процессов и уменьшает потребление токенов, позволяя Claude фильтровать или обрабатывать данные до того, как они попадут в контекстное окно модели. На эталонных тестах агентского поиска, таких как BrowseComp и DeepSearchQA, которые проверяют многошаговый веб-поиск и сложный поиск информации, добавление программного вызова инструментов поверх базовых инструментов поиска было ключевым фактором, который полностью раскрыл производительность агента.

Разница быстро нарастает в реальных рабочих процессах. Рассмотрим проверку соответствия бюджету для 20 сотрудников: традиционный подход требует 20 отдельных циклических обращений к модели, вытягивая тысячи строк расходов в контекст по пути. С программным вызовом инструментов один скрипт выполняет все 20 поисков, фильтрует результаты и возвращает только сотрудников, которые превысили свои лимиты, сокращая то, над чем Claude должен рассуждать, со сотен килобайт до нескольких строк.

Совместимость моделей

Программный вызов инструментов требует code_execution_20260120, который поддерживается следующими моделями:

Для полной матрицы версий инструмента выполнения кода см. таблицу совместимости моделей инструмента выполнения кода. Программный вызов инструментов доступен через Claude API и Microsoft Foundry.

Быстрый старт

Вот простой пример, где Claude программно запрашивает базу данных несколько раз и агрегирует результаты:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Query sales data for the West, East, and Central regions, then tell me which region had the highest revenue",
        }
    ],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query against the sales database. Returns a list of rows as JSON objects.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query to execute"}
                },
                "required": ["sql"],
            },
            "allowed_callers": ["code_execution_20260120"],
        },
    ],
)

print(response)

Как работает программный вызов инструментов

Когда вы настраиваете инструмент для вызова из выполнения кода и Claude решает использовать этот инструмент:

1. Claude пишет код на Python, который вызывает инструмент как функцию, потенциально включая несколько вызовов инструментов и логику предварительной/последующей обработки
2. Claude запускает этот код в изолированном контейнере через выполнение кода
3. Когда вызывается функция инструмента, выполнение кода приостанавливается и API возвращает блок tool_use
4. Вы предоставляете результат инструмента, и выполнение кода продолжается (промежуточные результаты не загружаются в контекстное окно Claude)
5. После завершения всего выполнения кода Claude получает окончательный результат и продолжает работу над задачей

Этот подход особенно полезен для:

• Обработка больших данных: Фильтруйте или агрегируйте результаты инструментов перед тем, как они попадут в контекст Claude
• Многошаговые рабочие процессы: Экономьте токены и задержку, вызывая инструменты последовательно или в цикле без выборки Claude между вызовами инструментов
• Условная логика: Принимайте решения на основе промежуточных результатов инструментов

Основные концепции

Поле allowed_callers

Поле allowed_callers указывает, какие контексты могут вызывать инструмент:

{
  "name": "query_database",
  "description": "Execute a SQL query against the database",
  "input_schema": {
    // ...
  },
  "allowed_callers": ["code_execution_20260120"]
}

Возможные значения:

• ["direct"] - Только Claude может вызывать этот инструмент напрямую (по умолчанию, если опущено)
• ["code_execution_20260120"] - Вызывается только из выполнения кода
• ["direct", "code_execution_20260120"] - Вызывается как напрямую, так и из выполнения кода

Поле caller в ответах

Каждый блок использования инструмента включает поле caller, указывающее, как он был вызван:

Прямой вызов (традиционное использование инструмента):

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": { "type": "direct" }
}

Программный вызов:

{
  "type": "tool_use",
  "id": "toolu_xyz789",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_abc123"
  }
}

tool_id ссылается на инструмент выполнения кода, который сделал программный вызов.

Жизненный цикл контейнера

Программный вызов инструментов использует те же контейнеры, что и выполнение кода:

• Создание контейнера: Новый контейнер создается для каждой сессии, если вы не повторно используете существующий
• Истечение: Контейнеры имеют максимальный срок жизни 30 дней и очищаются после 4,5 минут простоя
• ID контейнера: Возвращается в ответах через поле container
• Повторное использование: Передайте ID контейнера для сохранения состояния между запросами

Пример рабочего процесса

Вот как работает полный поток программного вызова инструментов:

Шаг 1: Начальный запрос

Отправьте запрос с выполнением кода и инструментом, который позволяет программный вызов. Чтобы включить программный вызов, добавьте поле allowed_callers в определение вашего инструмента.

Форма запроса идентична примеру Быстрый старт: включите code_execution в список инструментов, добавьте allowed_callers: ["code_execution_20260120"] к любому инструменту, который вы хотите, чтобы Claude вызывал из кода, и отправьте ваше сообщение пользователя.

Шаг 2: Ответ API с вызовом инструмента

Claude пишет код, который вызывает ваш инструмент. API приостанавливается и возвращает:

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll query the purchase history and analyze the results."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "code_execution",
      "input": {
        "code": "results = await query_database('<sql>')\ntop_customers = sorted(results, key=lambda x: x['revenue'], reverse=True)[:5]\nprint(f'Top 5 customers: {top_customers}')"
      }
    },
    {
      "type": "tool_use",
      "id": "toolu_def456",
      "name": "query_database",
      "input": { "sql": "<sql>" },
      "caller": {
        "type": "code_execution_20260120",
        "tool_id": "srvtoolu_abc123"
      }
    }
  ],
  "container": {
    "id": "container_xyz789",
    "expires_at": "2025-01-15T14:30:00Z"
  },
  "stop_reason": "tool_use"
}

Шаг 3: Предоставьте результат инструмента

Включите полную историю разговора плюс результат вашего инструмента:

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    container="container_xyz789",  # Reuse the container
    messages=[
        {
            "role": "user",
            "content": "Query customer purchase history from the last quarter and identify our top 5 customers by revenue",
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "I'll query the purchase history and analyze the results.",
                },
                {
                    "type": "server_tool_use",
                    "id": "srvtoolu_abc123",
                    "name": "code_execution",
                    "input": {"code": "..."},
                },
                {
                    "type": "tool_use",
                    "id": "toolu_def456",
                    "name": "query_database",
                    "input": {"sql": "<sql>"},
                    "caller": {
                        "type": "code_execution_20260120",
                        "tool_id": "srvtoolu_abc123",
                    },
                },
            ],
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "tool_result",
                    "tool_use_id": "toolu_def456",
                    "content": '[{"customer_id": "C1", "revenue": 45000}, {"customer_id": "C2", "revenue": 38000}, ...]',
                }
            ],
        },
    ],
    tools=[...],
)

print(response)

Шаг 4: Следующий вызов инструмента или завершение

Выполнение кода продолжается и обрабатывает результаты. Если требуются дополнительные вызовы инструментов, повторите шаг 3 до тех пор, пока все вызовы инструментов не будут выполнены.

Шаг 5: Финальный ответ

После завершения выполнения кода Claude предоставляет финальный ответ:

{
  "content": [
    {
      "type": "code_execution_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "code_execution_result",
        "stdout": "Top 5 customers by revenue:\n1. Customer C1: $45,000\n2. Customer C2: $38,000\n3. Customer C5: $32,000\n4. Customer C8: $28,500\n5. Customer C3: $24,000",
        "stderr": "",
        "return_code": 0,
        "content": []
      }
    },
    {
      "type": "text",
      "text": "I've analyzed the purchase history from last quarter. Your top 5 customers generated $167,500 in total revenue, with Customer C1 leading at $45,000."
    }
  ],
  "stop_reason": "end_turn"
}

Продвинутые паттерны

Пакетная обработка с циклами

Claude может писать код, который эффективно обрабатывает несколько элементов:

async def _claude_code():
    regions = ["West", "East", "Central", "North", "South"]
    results = {}
    for region in regions:
        data = await query_database(f"<sql for {region}>")
        results[region] = sum(row["revenue"] for row in data)

    # Process results programmatically
    top_region = max(results.items(), key=lambda x: x[1])
    print(f"Top region: {top_region[0]} with ${top_region[1]:,} in revenue")

Этот паттерн:

• Снижает количество раундов модели с N (по одному на регион) до 1
• Обрабатывает большие наборы результатов программно перед возвратом к Claude
• Экономит токены, возвращая только агрегированные выводы вместо сырых данных

Ранее завершение

Claude может остановить обработку, как только будут выполнены критерии успеха:

async def _claude_code():
    endpoints = ["us-east", "eu-west", "apac"]
    for endpoint in endpoints:
        status = await check_health(endpoint)
        if status == "healthy":
            print(f"Found healthy endpoint: {endpoint}")
            break  # Stop early, don't check remaining

Условный выбор инструмента

async def _claude_code():
    file_info = await get_file_info(path)
    if file_info["size"] < 10000:
        content = await read_full_file(path)
    else:
        content = await read_file_summary(path)
    print(content)

Фильтрация данных

async def _claude_code():
    logs = await fetch_logs(server_id)
    errors = [log for log in logs if "ERROR" in log]
    print(f"Found {len(errors)} errors")
    for error in errors[-10:]:  # Only return last 10 errors
        print(error)

Формат ответа

Программный вызов инструмента

Когда выполнение кода вызывает инструмент:

{
  "type": "tool_use",
  "id": "toolu_abc123",
  "name": "query_database",
  "input": { "sql": "<sql>" },
  "caller": {
    "type": "code_execution_20260120",
    "tool_id": "srvtoolu_xyz789"
  }
}

Обработка результата инструмента

Результат вашего инструмента передается обратно в выполняющийся код:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_abc123",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000, \"orders\": 23}, {\"customer_id\": \"C2\", \"revenue\": 38000, \"orders\": 18}, ...]"
    }
  ]
}

Завершение выполнения кода

Когда все вызовы инструментов выполнены и код завершен:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_xyz789",
  "content": {
    "type": "code_execution_result",
    "stdout": "Analysis complete. Top 5 customers identified from 847 total records.",
    "stderr": "",
    "return_code": 0,
    "content": []
  }
}

Обработка ошибок

Распространённые ошибки

Истечение контейнера во время вызова инструмента

Если ваш инструмент слишком долго отвечает, выполнение кода получает TimeoutError. Claude видит это в stderr и обычно повторяет попытку:

{
  "type": "code_execution_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "code_execution_result",
    "stdout": "",
    "stderr": "TimeoutError: Calling tool ['query_database'] timed out.",
    "return_code": 0,
    "content": []
  }
}

Чтобы предотвратить истечение времени ожидания:

• Отслеживайте поле expires_at в ответах
• Реализуйте тайм-ауты для выполнения вашего инструмента
• Рассмотрите возможность разбиения длительных операций на более мелкие части

Ошибки выполнения инструмента

Если ваш инструмент возвращает ошибку:

{
  "type": "tool_result",
  "tool_use_id": "toolu_abc123",
  "content": "Error: Query timeout - table lock exceeded 30 seconds"
}

Код Claude получает эту ошибку и может обработать её надлежащим образом.

Ограничения и ограничивающие факторы

Несовместимость функций

• Структурированные выходы: Инструменты с strict: true не поддерживаются при программном вызове
• Выбор инструмента: Вы не можете принудительно вызвать программный вызов конкретного инструмента через tool_choice
• Параллельное использование инструментов: disable_parallel_tool_use: true не поддерживается при программном вызове

Ограничения инструментов

Следующие инструменты в настоящее время не могут быть вызваны программно, но поддержка может быть добавлена в будущих версиях:

• Инструменты, предоставленные MCP коннектором

Ограничения форматирования сообщений

При ответе на программные вызовы инструментов существуют строгие требования к форматированию:

Ответы только с результатом инструмента: Если есть ожидающие программные вызовы инструментов, ожидающие результатов, ваше сообщение ответа должно содержать только блоки tool_result. Вы не можете включать никакое текстовое содержимое, даже после результатов инструментов.

Неправильно - Невозможно включить текст при ответе на программные вызовы инструментов:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    },
    { "type": "text", "text": "What should I do next?" }
  ]
}

Правильно - Только результаты инструментов при ответе на программные вызовы инструментов:

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01",
      "content": "[{\"customer_id\": \"C1\", \"revenue\": 45000}]"
    }
  ]
}

Это ограничение применяется только при ответе на программные (выполнение кода) вызовы инструментов. Для обычных вызовов инструментов на стороне клиента вы можете включать текстовое содержимое после результатов инструментов.

Ограничения скорости

Программные вызовы инструментов подлежат тем же ограничениям скорости, что и обычные вызовы инструментов. Каждый вызов инструмента из выполнения кода считается отдельным вызовом.

Проверьте результаты инструментов перед использованием

При реализации определяемых пользователем инструментов, которые будут вызваны программно:

• Результаты инструментов возвращаются в виде строк: Они могут содержать любое содержимое, включая фрагменты кода или исполняемые команды, которые могут быть обработаны средой выполнения.
• Проверьте результаты внешних инструментов: Если ваш инструмент возвращает данные из внешних источников или принимает пользовательский ввод, помните об опасности внедрения кода, если выходные данные будут интерпретированы или выполнены как код.

Эффективность токенов

Программный вызов инструментов может значительно снизить потребление токенов:

• Результаты инструментов из программных вызовов не добавляются в контекст Claude - только финальный вывод кода
• Промежуточная обработка происходит в коде - фильтрация, агрегация и т.д. не потребляют токены модели
• Несколько вызовов инструментов в одном выполнении кода - снижает накладные расходы по сравнению с отдельными оборотами модели

Например, прямой вызов 10 инструментов использует ~10x токенов по сравнению с их программным вызовом и возвратом сводки.

Использование и ценообразование

Программный вызов инструментов использует то же ценообразование, что и выполнение кода. Подробности см. в разделе ценообразование выполнения кода.

Лучшие практики

Проектирование инструмента

• Предоставьте подробные описания выходных данных: Поскольку Claude десериализует результаты инструментов в коде, чётко документируйте формат (структура JSON, типы полей и т.д.)
• Возвращайте структурированные данные: JSON или другие легко анализируемые форматы работают лучше всего для программной обработки
• Сохраняйте ответы краткими: Возвращайте только необходимые данные, чтобы минимизировать накладные расходы на обработку

Когда использовать программный вызов

Хорошие варианты использования:

• Обработка больших наборов данных, где вам нужны только агрегаты или сводки
• Многошаговые рабочие процессы с 3+ зависимыми вызовами инструментов
• Операции, требующие фильтрации, сортировки или преобразования результатов инструментов
• Задачи, где промежуточные данные не должны влиять на рассуждения Claude
• Параллельные операции по многим элементам (например, проверка 50 конечных точек)

Менее идеальные варианты использования:

• Одиночные вызовы инструментов с простыми ответами
• Инструменты, которые нуждаются в немедленной обратной связи от пользователя
• Очень быстрые операции, где накладные расходы выполнения кода превысят выгоду

Оптимизация производительности

• Повторно используйте контейнеры при выполнении нескольких связанных запросов для сохранения состояния
• Объедините похожие операции в одном выполнении кода, когда это возможно

Устранение неполадок

Распространённые проблемы

Ошибка "Tool not allowed"

• Проверьте, что определение вашего инструмента включает "allowed_callers": ["code_execution_20260120"]

Истечение контейнера

• Убедитесь, что вы отвечаете на вызовы инструментов до истечения контейнера (4,5 минуты неактивности; максимум 30 дней)
• Отслеживайте поле expires_at в ответах
• Рассмотрите возможность реализации более быстрого выполнения инструмента

Результат инструмента не анализируется правильно

• Убедитесь, что ваш инструмент возвращает строковые данные, которые Claude может десериализовать
• Предоставьте чёткую документацию формата выходных данных в описании вашего инструмента

Советы по отладке

1. Логируйте все вызовы инструментов и результаты для отслеживания потока
2. Проверьте поле caller для подтверждения программного вызова
3. Отслеживайте ID контейнеров для обеспечения надлежащего повторного использования
4. Тестируйте инструменты независимо перед включением программного вызова

Почему работает программный вызов инструментов

Обучение Claude включает обширное воздействие кода, что делает его эффективным в рассуждении и цепочке вызовов функций. Когда инструменты представлены как вызываемые функции в среде выполнения кода, Claude может использовать эту силу для:

• Естественного рассуждения о композиции инструментов: Цепочка операций и обработка зависимостей так же естественно, как написание любого кода Python
• Эффективной обработки больших результатов: Фильтруйте большие выходные данные инструментов, извлекайте только релевантные данные или записывайте промежуточные результаты в файлы перед возвратом сводок в окно контекста
• Значительного снижения задержки: Исключите накладные расходы на повторную выборку Claude между каждым вызовом инструмента в многошаговых рабочих процессах

Этот подход позволяет использовать рабочие процессы, которые были бы непрактичны при традиционном использовании инструментов (например, обработка файлов более 1M токенов), позволяя Claude работать с данными программно, а не загружать всё в окно разговора.

Альтернативные реализации

Программный вызов инструментов — это обобщаемый паттерн, который можно реализовать вне управляемого выполнения кода Anthropic. Вот обзор подходов:

Прямое выполнение на стороне клиента

Предоставьте Claude инструмент выполнения кода и опишите, какие функции доступны в этой среде. Когда Claude вызывает инструмент с кодом, ваше приложение выполняет его локально, где определены эти функции.

Преимущества:

• Простая реализация с минимальной переархитектурой
• Полный контроль над окружением и инструкциями

Недостатки:

• Выполняет ненадёжный код вне песочницы
• Вызовы инструментов могут быть векторами для внедрения кода

Используйте, когда: Ваше приложение может безопасно выполнять произвольный код, вам нужно простое решение, и управляемое предложение Anthropic не подходит вашим потребностям.

Самоуправляемое выполнение в песочнице

Тот же подход с точки зрения Claude, но код выполняется в контейнере в песочнице с ограничениями безопасности (например, без исходящего сетевого трафика). Если ваши инструменты требуют внешних ресурсов, вам потребуется протокол для выполнения вызовов инструментов вне песочницы.

Преимущества:

• Безопасный программный вызов инструментов на вашей собственной инфраструктуре
• Полный контроль над средой выполнения

Недостатки:

• Сложно строить и поддерживать
• Требует управления как инфраструктурой, так и межпроцессной коммуникацией

Используйте, когда: Безопасность критична и управляемое решение Anthropic не подходит вашим требованиям.

Управляемое выполнение Anthropic

Программный вызов инструментов Anthropic — это управляемая версия выполнения в песочнице с мнением среды Python, настроенной для Claude. Anthropic обрабатывает управление контейнерами, выполнение кода и безопасную коммуникацию вызова инструментов.

Преимущества:

• Безопасно и надёжно по умолчанию
• Легко включить с минимальной конфигурацией
• Окружение и инструкции оптимизированы для Claude

Рассмотрите использование управляемого решения Anthropic, если вы используете Claude API.

Сохранение данных

Программный вызов инструментов построен на инфраструктуре выполнения кода и использует те же контейнеры в песочнице. Данные контейнера, включая артефакты выполнения и выходные данные, сохраняются до 30 дней.

Для соответствия ZDR по всем функциям см. API и сохранение данных.

Связанные функции