Объедините встроенные инструменты и вызов функций.

Gemini позволяет комбинировать встроенные инструменты , такие как google_search , и вызовы функций (также известные как пользовательские инструменты ) в рамках одного взаимодействия, сохраняя и предоставляя историю контекста вызовов инструментов. Комбинации встроенных и пользовательских инструментов позволяют создавать сложные, агентные рабочие процессы, где, например, модель может основываться на веб-данных в реальном времени, прежде чем вызывать вашу конкретную бизнес-логику.

Вот пример, позволяющий комбинировать встроенные и пользовательские инструменты с помощью google_search и пользовательской функции getWeather :

from google import genai

client = genai.Client()

getWeather = {
    "type": "function",
    "name": "getWeather",
    "description": "Gets the weather for a requested city.",
    "parameters": {
        "type": "object",
        "properties": {
            "city": {
                "type": "string",
                "description": "The city and state, e.g. Utqiaġvik, Alaska",
            },
        },
        "required": ["city"],
    },
}

# The Interactions API manages context automatically across tool calls.
# The model will first use Google Search, then call getWeather.
interaction = client.interactions.create(
    model="gemini-3-flash-preview",
    input="What is the northernmost city in the United States? What's the weather like there today?",
    tools=[
        {"google_search": {}},
        getWeather,
    ],
)

# Process steps: the interaction contains search results and a function call
for step in interaction.steps:
    if step.type == "function_call":
        print(f"Function call: {step.name} with args: {step.arguments}")
        # In a real application, you would execute the function here
        # and provide the result back to the model.

import { GoogleGenAI } from '@google/genai';

const client = new GoogleGenAI({});

const getWeather = {
    type: "function",
    name: "getWeather",
    description: "Get the weather in a given location",
    parameters: {
        type: "object",
        properties: {
            location: {
                type: "string",
                description: "The city and state, e.g. San Francisco, CA"
            }
        },
        required: ["location"]
    }
};

// The Interactions API manages context automatically across tool calls.
// The model will first use Google Search, then call getWeather.
const interaction = await client.interactions.create({
    model: "gemini-3-flash-preview",
    input: "What is the northernmost city in the United States? What's the weather like there today?",
    tools: [
        { googleSearch: {} },
        getWeather,
    ],
});

// Process steps: the interaction contains search results and a function call
for (const step of interaction.steps) {
    if (step.type === "function_call") {
        console.log(`Function call: ${step.name} with args: ${JSON.stringify(step.arguments)}`);
        // In a real application, you would execute the function here
        // and provide the result back to the model.
    }
}

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
  "model": "gemini-3-flash-preview",
  "input": "What is the northernmost city in the United States? What'\''s the weather like there today?",
  "tools": [
    { "type": "google_search" },
    {
      "type": "function",
      "name": "getWeather",
      "description": "Get the weather in a given location",
      "parameters": {
          "type": "object",
          "properties": {
              "location": {
                  "type": "string",
                  "description": "The city and state, e.g. San Francisco, CA"
              }
          },
          "required": ["location"]
      }
    }
  ]
}'

Как это работает

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

Включить комбинацию инструментов

• Включите в файл function_declarations , а также встроенные инструменты, которые вы хотите использовать, чтобы активировать комбинированное поведение.

API возвращает шаги

В ответе на запрос взаимодействия API возвращает отдельные шаги для вызовов встроенных инструментов и вызовов функций (пользовательских инструментов):

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

Критические поля в возвращаемых шагах

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

• id : Найдено на этапах function_call и function_response . Уникальный идентификатор, сопоставляющий вызов с соответствующим ответом.
• signature : Найдено на этапах выполнения thought , а также на всех этапах вызова инструмента (например, function_call ) и получения результата (например, function_response ) для моделей Gemini 3+. Этот зашифрованный контекст обеспечивает циркуляцию контекста инструмента между взаимодействиями.

Управление этими полями:

• Режим сохранения состояния (рекомендуется) : При использовании previous_interaction_id сервер автоматически обрабатывает как поле id , так и поле signature .
• Режим без сохранения состояния : При ручном управлении историей переписки необходимо убедиться, что в последующих запросах в модель передаются поля id и signature для проверки подлинности и сохранения контекста. Официальные SDK обрабатывают это автоматически, если вы передаете полный объект ответа обратно в историю.

Данные, специфичные для инструмента

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

Токены и цены

Обратите внимание, что части запросов, выполняемые встроенными инструментами, учитываются в показателе prompt_token_count . Поскольку эти промежуточные шаги инструментов теперь видны и возвращаются вам, они являются частью истории диалога. Это относится только к запросам , а не к ответам .

Инструмент поиска Google является исключением из этого правила. Google Search уже применяет собственную модель ценообразования на уровне запроса, поэтому токены не облагаются двойной оплатой (см. страницу «Цены» ).

Для получения более подробной информации ознакомьтесь со страницей «Токены» .

Ограничения

• При включении циркуляции контекста инструмента по умолчанию используется режим validated ( auto режим не поддерживается).
• Встроенные инструменты, такие как google_search полагаются на информацию о местоположении и текущем времени, поэтому, если в вашем system_instruction или function_declaration.description содержится противоречивая информация о местоположении и времени, функция комбинирования инструментов может работать некорректно.

Поддерживаемые инструменты

Стандартная циркуляция контекста применяется к встроенным инструментам на стороне сервера. Выполнение кода также является инструментом на стороне сервера, но имеет собственное встроенное решение для циркуляции контекста. Использование компьютера и вызов функций являются инструментами на стороне клиента и также имеют встроенные решения для циркуляции контекста.

Что дальше?

• Узнайте больше о вызове функций в API Gemini.
• Ознакомьтесь с поддерживаемыми инструментами:
  • Поиск Google
  • Google Карты
  • Контекст URL
  • Поиск файлов