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

Программный вызов инструментов позволяет Claude писать код, который вызывает ваши инструменты программно внутри контейнера code execution (выполнения кода), вместо того чтобы требовать обращения к модели для каждого вызова инструмента. Это снижает задержку для рабочих процессов с несколькими инструментами и уменьшает потребление токенов, позволяя Claude фильтровать или обрабатывать данные до того, как они попадут в контекстное окно модели. В бенчмарках агентного поиска, таких как BrowseComp и DeepSearchQA, которые тестируют многошаговое веб-исследование и сложный поиск информации, добавление программного вызова инструментов поверх базовых инструментов поиска улучшило производительность в среднем на 11% при использовании на 24% меньше входных токенов (см. Improved web search with dynamic filtering).

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



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

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

Полную матрицу версий инструмента выполнения кода см. в таблице совместимости моделей инструмента выполнения кода. Программный вызов инструментов доступен в Claude API, Claude Platform on AWS и Microsoft Foundry. В настоящее время он недоступен в Amazon Bedrock или Vertex AI.



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

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    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"] — Claude направляется на вызов этого инструмента только из выполнения кода
• ["direct", "code_execution_20260120"] — Claude может вызывать этот инструмент напрямую или из выполнения кода



Поле 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 минут простоя
• Идентификатор контейнера: возвращается в ответах в поле container
• Переиспользование: передайте идентификатор контейнера, чтобы сохранить состояние между запросами



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

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



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

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

Форма запроса идентична примеру из раздела Быстрый старт: включите code_execution в список инструментов, добавьте allowed_callers: ["code_execution_20260120"] к любому инструменту, который Claude должен вызывать из кода, и отправьте ваше пользовательское сообщение. Остальные шаги в этом рабочем процессе используют пользовательское сообщение "Query customer purchase history from the last quarter and identify our top 5 customers by revenue".



Шаг 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": "2026-01-20T14:30:00Z"
  },
  "stop_reason": "tool_use"
}



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

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

response = client.messages.create(
    model="claude-opus-4-8",
    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: [{'customer_id': 'C1', 'revenue': 45000}, {'customer_id': 'C2', 'revenue': 38000}, {'customer_id': 'C5', 'revenue': 32000}, {'customer_id': 'C8', 'revenue': 28500}, {'customer_id': 'C3', 'revenue': 24000}]",
        "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)

    # Программная обработка результатов
    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 инструментов использует примерно в 10 раз больше токенов, чем их программный вызов с возвратом сводки.

Во внутренних оценках Anthropic на производственной модели Claude:

• В бенчмарке агента управления проектами с 75 инструментами включение программного вызова инструментов снизило тарифицируемые входные токены примерно на 38% без изменения точности выполнения задач.
• В τ²-bench (домены авиаперевозок, розничной торговли и телекоммуникаций), где каждый ход делает один или два последовательных вызова инструментов, программный вызов инструментов не изменил результаты и стоил примерно на 8% больше. Последовательные рабочие процессы с одиночными вызовами не получают выгоды.
• По производственному трафику API запросы, чей массив tools содержит от 10 до 49 определений инструментов, показывают типичную экономию токенов от 20% до 40% при включённом программном вызове инструментов.

Фактическая экономия зависит от характера рабочей нагрузки; см. Когда использовать программный вызов.



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

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



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



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

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



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

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

Хорошо подходит:

• Веерные или параллельные операции над многими элементами (например, проверка 50 конечных точек или поиск 20 записей)
• Большие результаты инструментов, которые можно отфильтровать, агрегировать или суммировать до попадания в контекст Claude
• Агентный поиск и извлечение, где итеративные запросы и фильтрация результатов доминируют в рабочем процессе

Плохо подходит:

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

Если вы не уверены, измерьте тарифицируемые входные токены с allowed_callers и без него на репрезентативной выборке вашего трафика, прежде чем включать его повсеместно.



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

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



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



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

invalid_request_error при установке tool_choice

• tool_choice не может указывать на инструмент, чей allowed_callers не содержит "direct". Либо добавьте "direct" в allowed_callers этого инструмента, либо удалите инструмент из tool_choice и позвольте Claude вызывать его из кода.

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

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

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

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



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

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



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

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

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

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



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

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



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

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

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

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

Недостатки:

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

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



Самоуправляемое изолированное выполнение

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

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

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

Недостатки:

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

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



Выполнение под управлением Anthropic

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

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

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

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



Хранение данных

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

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



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