Вызов функций с помощью Gemini API

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

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

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

Как работает вызов функций

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

1. Определите декларацию функции: Определите декларацию функции в коде вашего приложения. Декларации функций описывают имя функции, параметры и цель для модели.
2. Вызов LLM с декларациями функций: отправка приглашения пользователя вместе с декларацией(ями) функций в модель. Она анализирует запрос и определяет, будет ли полезен вызов функции. Если да, она отвечает структурированным объектом JSON.
3. Выполнение кода функции (ваша ответственность): Модель не выполняет функцию сама по себе. Это ответственность вашего приложения — обрабатывать ответ и проверять вызов функции, если
   • Да : извлеките имя и аргументы функции и выполните соответствующую функцию в вашем приложении.
   • Нет: Модель предоставила прямой текстовый ответ на подсказку (этот поток менее подчеркнут в примере, но является возможным результатом).
4. Создать удобный для пользователя ответ: Если функция была выполнена, захватить результат и отправить его обратно в модель в последующем повороте диалога. Она будет использовать результат для генерации окончательного удобного для пользователя ответа, который включает информацию из вызова функции.

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

Шаг 1: Определение объявления функции

Определите функцию и ее объявление в коде вашего приложения, которое позволяет пользователям устанавливать значения света и делать запрос API. Эта функция может вызывать внешние службы или API.

from google.genai import types

# Define a function that the model can call to control smart lights
set_light_values_declaration = {
    "name": "set_light_values",
    "description": "Sets the brightness and color temperature of a light.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "integer",
                "description": "Light level from 0 to 100. Zero is off and 100 is full brightness",
            },
            "color_temp": {
                "type": "string",
                "enum": ["daylight", "cool", "warm"],
                "description": "Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.",
            },
        },
        "required": ["brightness", "color_temp"],
    },
}

# This is the actual function that would be called based on the model's suggestion
def set_light_values(brightness: int, color_temp: str) -> dict[str, int | str]:
    """Set the brightness and color temperature of a room light. (mock API).

    Args:
        brightness: Light level from 0 to 100. Zero is off and 100 is full brightness
        color_temp: Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.

    Returns:
        A dictionary containing the set brightness and color temperature.
    """
    return {"brightness": brightness, "colorTemperature": color_temp}

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

// Define a function that the model can call to control smart lights
const setLightValuesFunctionDeclaration = {
  name: 'set_light_values',
  description: 'Sets the brightness and color temperature of a light.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'Light level from 0 to 100. Zero is off and 100 is full brightness',
      },
      color_temp: {
        type: Type.STRING,
        enum: ['daylight', 'cool', 'warm'],
        description: 'Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.',
      },
    },
    required: ['brightness', 'color_temp'],
  },
};

/**
* Set the brightness and color temperature of a room light. (mock API)
* @param {number} brightness - Light level from 0 to 100. Zero is off and 100 is full brightness
* @param {string} color_temp - Color temperature of the light fixture, which can be `daylight`, `cool` or `warm`.
* @return {Object} A dictionary containing the set brightness and color temperature.
*/
function setLightValues(brightness, color_temp) {
  return {
    brightness: brightness,
    colorTemperature: color_temp
  };
}

Шаг 2: Вызов модели с объявлениями функций

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

from google import genai

# Generation Config with Function Declaration
tools = types.Tool(function_declarations=[set_light_values_declaration])
config = types.GenerateContentConfig(tools=[tools])

# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

# Define user prompt
contents = [
    types.Content(
        role="user", parts=[types.Part(text="Turn the lights down to a romantic level")]
    )
]

# Send request with function declarations
response = client.models.generate_content(
    model="gemini-2.0-flash", config=config, contents=contents
)

print(response.candidates[0].content.parts[0].function_call)

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

// Generation Config with Function Declaration
const config = {
  tools: [{
    functionDeclarations: [setLightValuesFunctionDeclaration]
  }]
};

// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Define user prompt
const contents = [
  {
    role: 'user',
    parts: [{ text: 'Turn the lights down to a romantic level' }]
  }
];

// Send request with function declarations
const response = await ai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: contents,
  config: config
});

console.log(response.functionCalls[0]); 

Затем модель возвращает объект functionCall в схеме, совместимой с OpenAPI, определяющей, как вызвать одну или несколько объявленных функций, чтобы ответить на вопрос пользователя.

id=None args={'color_temp': 'warm', 'brightness': 25} name='set_light_values'

{
  name: 'set_light_values',
  args: { brightness: 25, color_temp: 'warm' }
}

Шаг 3: Выполнить код функции set_light_values

Извлеките сведения о вызове функции из ответа модели, проанализируйте аргументы и выполните функцию set_light_values ​​в нашем коде.

# Extract tool call details
tool_call = response.candidates[0].content.parts[0].function_call

if tool_call.name == "set_light_values":
    result = set_light_values(**tool_call.args)
    print(f"Function execution result: {result}")

// Extract tool call details
const tool_call = response.functionCalls[0]

let result;
if (tool_call.name === 'set_light_values') {
  result = setLightValues(tool_call.args.brightness, tool_call.args.color_temp);
  console.log(`Function execution result: ${JSON.stringify(result)}`);
}

Шаг 4: Создайте удобный для пользователя ответ с результатом функции и вызовите модель еще раз.

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

# Create a function response part
function_response_part = types.Part.from_function_response(
    name=tool_call.name,
    response={"result": result},
)

# Append function call and result of the function execution to contents
contents.append(types.Content(role="model", parts=[types.Part(function_call=tool_call)])) # Append the model's function call message
contents.append(types.Content(role="user", parts=[function_response_part])) # Append the function response

final_response = client.models.generate_content(
    model="gemini-2.0-flash",
    config=config,
    contents=contents,
)

print(final_response.text)

// Create a function response part
const function_response_part = {
  name: tool_call.name,
  response: { result }
}

// Append function call and result of the function execution to contents
contents.push({ role: 'model', parts: [{ functionCall: tool_call }] });
contents.push({ role: 'user', parts: [{ functionResponse: function_response_part }] });

// Get the final response from the model
const final_response = await ai.models.generateContent({
  model: 'gemini-2.0-flash',
  contents: contents,
  config: config
});

console.log(final_response.text);

Это завершает поток вызова функции. Модель успешно использовала функцию set_light_values ​​для выполнения действия запроса пользователя.

Декларации функций

При реализации вызова функции в приглашении вы создаете объект tools , который содержит одно или несколько function declarations . Вы определяете функции с помощью JSON, в частности, с выбранным подмножеством формата схемы OpenAPI . Одно объявление функции может включать следующие параметры:

• name (string): Уникальное имя для функции ( get_weather_forecast , send_email ). Используйте описательные имена без пробелов и специальных символов (используйте подчеркивания или camelCase).
• description (string): Четкое и подробное объяснение цели и возможностей функции. Это важно для модели, чтобы понять, когда использовать функцию. Будьте конкретны и приведите примеры, если это полезно («Находит кинотеатры на основе местоположения и, возможно, названия фильма, который в данный момент идет в кинотеатрах»).
• parameters (объект): определяет входные параметры, ожидаемые функцией.
  • type (строка): определяет общий тип данных, например, object .
  • properties (объект): Перечисляет отдельные параметры, каждый из которых содержит:
    • type (строка): тип данных параметра, например string , integer , boolean, array .
    • description (string): Описание назначения и формата параметра. Предоставьте примеры и ограничения («Город и штат, например, «Сан-Франциско, Калифорния» или почтовый индекс, например, «95616».)
    • enum (массив, необязательно): Если значения параметров из фиксированного набора, используйте "enum" для перечисления допустимых значений вместо того, чтобы просто описывать их в описании. Это повышает точность ("enum": ["daylight", "cool", "warm"]).
  • required (массив): массив строк, в котором перечислены имена параметров, обязательные для работы функции.

Параллельный вызов функций

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

power_disco_ball = {
    "name": "power_disco_ball",
    "description": "Powers the spinning disco ball.",
    "parameters": {
        "type": "object",
        "properties": {
            "power": {
                "type": "boolean",
                "description": "Whether to turn the disco ball on or off.",
            }
        },
        "required": ["power"],
    },
}

start_music = {
    "name": "start_music",
    "description": "Play some music matching the specified parameters.",
    "parameters": {
        "type": "object",
        "properties": {
            "energetic": {
                "type": "boolean",
                "description": "Whether the music is energetic or not.",
            },
            "loud": {
                "type": "boolean",
                "description": "Whether the music is loud or not.",
            },
        },
        "required": ["energetic", "loud"],
    },
}

dim_lights = {
    "name": "dim_lights",
    "description": "Dim the lights.",
    "parameters": {
        "type": "object",
        "properties": {
            "brightness": {
                "type": "number",
                "description": "The brightness of the lights, 0.0 is off, 1.0 is full.",
            }
        },
        "required": ["brightness"],
    },
}

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

const powerDiscoBall = {
  name: 'power_disco_ball',
  description: 'Powers the spinning disco ball.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      power: {
        type: Type.BOOLEAN,
        description: 'Whether to turn the disco ball on or off.'
      }
    },
    required: ['power']
  }
};

const startMusic = {
  name: 'start_music',
  description: 'Play some music matching the specified parameters.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      energetic: {
        type: Type.BOOLEAN,
        description: 'Whether the music is energetic or not.'
      },
      loud: {
        type: Type.BOOLEAN,
        description: 'Whether the music is loud or not.'
      }
    },
    required: ['energetic', 'loud']
  }
};

const dimLights = {
  name: 'dim_lights',
  description: 'Dim the lights.',
  parameters: {
    type: Type.OBJECT,
    properties: {
      brightness: {
        type: Type.NUMBER,
        description: 'The brightness of the lights, 0.0 is off, 1.0 is full.'
      }
    },
    required: ['brightness']
  }
};

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

from google import genai
from google.genai import types

# Set up function declarations
house_tools = [
    types.Tool(function_declarations=[power_disco_ball, start_music, dim_lights])
]

config = {
    "tools": house_tools,
    "automatic_function_calling": {"disable": True},
    # Force the model to call 'any' function, instead of chatting.
    "tool_config": {"function_calling_config": {"mode": "any"}},
}

# Configure the client
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

chat = client.chats.create(model="gemini-2.0-flash", config=config)
response = chat.send_message("Turn this place into a party!")

# Print out each of the function calls requested from this single call
print("Example 1: Forced function calling")
for fn in response.function_calls:
    args = ", ".join(f"{key}={val}" for key, val in fn.args.items())
    print(f"{fn.name}({args})")

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

// Set up function declarations
const houseFns = [powerDiscoBall, startMusic, dimLights];

const config = {
    tools: [{
        functionDeclarations: houseFns
    }],
    // Force the model to call 'any' function, instead of chatting.
    toolConfig: {
        functionCallingConfig: {
        mode: 'any'
        }
    }
};

// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Create a chat session
const chat = ai.chats.create({
    model: 'gemini-2.0-flash',
    config: config
});
const response = await chat.sendMessage({message: 'Turn this place into a party!'});

// Print out each of the function calls requested from this single call
console.log("Example 1: Forced function calling");
for (const fn of response.functionCalls) {
    const args = Object.entries(fn.args)
        .map(([key, val]) => `${key}=${val}`)
        .join(', ');
    console.log(`${fn.name}(${args})`);
}

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

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

from google import genai
from google.genai import types

# Actual implementation functions
def power_disco_ball_impl(power: bool) -> dict:
    """Powers the spinning disco ball.

    Args:
        power: Whether to turn the disco ball on or off.

    Returns:
        A status dictionary indicating the current state.
    """
    return {"status": f"Disco ball powered {'on' if power else 'off'}"}

def start_music_impl(energetic: bool, loud: bool) -> dict:
    """Play some music matching the specified parameters.

    Args:
        energetic: Whether the music is energetic or not.
        loud: Whether the music is loud or not.

    Returns:
        A dictionary containing the music settings.
    """
    music_type = "energetic" if energetic else "chill"
    volume = "loud" if loud else "quiet"
    return {"music_type": music_type, "volume": volume}

def dim_lights_impl(brightness: float) -> dict:
    """Dim the lights.

    Args:
        brightness: The brightness of the lights, 0.0 is off, 1.0 is full.

    Returns:
        A dictionary containing the new brightness setting.
    """
    return {"brightness": brightness}

config = {
    "tools": [power_disco_ball_impl, start_music_impl, dim_lights_impl],
}

chat = client.chats.create(model="gemini-2.0-flash", config=config)
response = chat.send_message("Do everything you need to this place into party!")

print("\nExample 2: Automatic function calling")
print(response.text)
# I've turned on the disco ball, started playing loud and energetic music, and dimmed the lights to 50% brightness. Let's get this party started!

Вызов композиционной функции

Gemini 2.0 поддерживает композиционный вызов функций, что означает, что модель может объединять несколько вызовов функций вместе. Например, чтобы ответить «Получить температуру в моем текущем местоположении», API Gemini может вызвать как функцию get_current_location() , так и функцию get_weather() , которая принимает местоположение в качестве параметра.

# Light control schemas
turn_on_the_lights_schema = {'name': 'turn_on_the_lights'}
turn_off_the_lights_schema = {'name': 'turn_off_the_lights'}

prompt = """
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
  """

tools = [
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]}
]

await run(prompt, tools=tools, modality="AUDIO")

// Light control schemas
const turnOnTheLightsSchema = { name: 'turn_on_the_lights' };
const turnOffTheLightsSchema = { name: 'turn_off_the_lights' };

const prompt = `
  Hey, can you write run some python code to turn on the lights, wait 10s and then turn off the lights?
`;

const tools = [
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] }
];

await run(prompt, tools=tools, modality="AUDIO")

Режимы вызова функций

API Gemini позволяет вам контролировать, как модель использует предоставленные инструменты (декларации функций). В частности, вы можете установить режим в function_calling_config .

• AUTO (Default) : модель решает, генерировать ли ответ на естественном языке или предлагать вызов функции на основе подсказки и контекста. Это наиболее гибкий режим, рекомендуемый для большинства сценариев.
• ANY : Модель ограничена тем, чтобы всегда предсказывать вызов функции и гарантировать соответствие схеме функции. Если allowed_function_names не указано, модель может выбирать из любого из предоставленных объявлений функций. Если allowed_function_names указано в виде списка, модель может выбирать только из функций в этом списке. Используйте этот режим, когда требуется вызов функции в ответ на каждый запрос (если применимо).

• NONE : модели запрещено делать вызовы функций. Это эквивалентно отправке запроса без каких-либо объявлений функций. Используйте это, чтобы временно отключить вызов функций, не удаляя определения инструментов.

from google.genai import types

# Configure function calling mode
tool_config = types.ToolConfig(
    function_calling_config=types.FunctionCallingConfig(
        mode="ANY", allowed_function_names=["get_current_temperature"]
    )
)

# Create the generation config
config = types.GenerateContentConfig(
    temperature=0,
    tools=[tools],  # not defined here.
    tool_config=tool_config,
)

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

// Configure function calling mode
const toolConfig = {
  functionCallingConfig: {
    mode: FunctionCallingConfigMode.ANY,
    allowedFunctionNames: ['get_current_temperature']
  }
};

// Create the generation config
const config = {
  temperature: 0,
  tools: tools, // not defined here.
  toolConfig: toolConfig,
};

Автоматический вызов функций (только Python)

При использовании Python SDK вы можете предоставлять функции Python напрямую как инструменты. SDK автоматически преобразует функцию Python в объявления, обрабатывает выполнение вызова функции и цикл ответа для вас. Затем Python SDK автоматически:

1. Обнаруживает ответы на вызовы функций из модели.
2. Вызовите соответствующую функцию Python в вашем коде.
3. Отправляет ответ функции обратно в модель.
4. Возвращает окончательный текстовый ответ модели.

Чтобы использовать это, определите свою функцию с подсказками типов и строкой документации, а затем передайте саму функцию (не декларацию JSON) в качестве инструмента:

from google import genai
from google.genai import types

# Define the function with type hints and docstring
def get_current_temperature(location: str) -> dict:
    """Gets the current temperature for a given location.

    Args:
        location: The city and state, e.g. San Francisco, CA

    Returns:
        A dictionary containing the temperature and unit.
    """
    # ... (implementation) ...
    return {"temperature": 25, "unit": "Celsius"}

# Configure the client and model
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))  # Replace with your actual API key setup
config = types.GenerateContentConfig(
    tools=[get_current_temperature]
)  # Pass the function itself

# Make the request
response = client.models.generate_content(
    model="gemini-2.0-flash",
    contents="What's the temperature in Boston?",
    config=config,
)

print(response.text)  # The SDK handles the function call and returns the final text

Вы можете отключить автоматический вызов функций с помощью:

# To disable automatic function calling:
config = types.GenerateContentConfig(
    tools=[get_current_temperature],
    automatic_function_calling=types.AutomaticFunctionCallingConfig(disable=True)
)

Декларация схемы автоматической функции

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

AllowedType = (int | float | bool | str | list['AllowedType'] | dict[str, AllowedType])

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

def multiply(a: float, b: float):
    """Returns a * b."""
    return a * b

fn_decl = types.FunctionDeclaration.from_callable(callable=multiply, client=client)

# to_json_dict() provides a clean JSON representation.
print(fn_decl.to_json_dict())

Многофункциональное использование: объединение собственных инструментов с вызовом функций

С Gemini 2.0 вы можете включить несколько инструментов, объединяющих собственные инструменты с вызовом функций одновременно. Вот пример, который включает два инструмента, Grounding with Google Search и code execution , в запросе с использованием Live API .

# Multiple tasks example - combining lights, code execution, and search
prompt = """
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
  """

tools = [
    {'google_search': {}},
    {'code_execution': {}},
    {'function_declarations': [turn_on_the_lights_schema, turn_off_the_lights_schema]} # not defined here.
]

# Execute the prompt with specified tools in audio modality
await run(prompt, tools=tools, modality="AUDIO")

// Multiple tasks example - combining lights, code execution, and search
const prompt = `
  Hey, I need you to do three things for me.

    1.  Turn on the lights.
    2.  Then compute the largest prime palindrome under 100000.
    3.  Then use Google Search to look up information about the largest earthquake in California the week of Dec 5 2024.

  Thanks!
`;

const tools = [
  { googleSearch: {} },
  { codeExecution: {} },
  { functionDeclarations: [turnOnTheLightsSchema, turnOffTheLightsSchema] } // not defined here.
];

// Execute the prompt with specified tools in audio modality
await run(prompt, {tools: tools, modality: "AUDIO"});

Разработчики Python могут опробовать это в блокноте Live API Tool Use .

Модель контекстного протокола (MCP)

Model Context Protocol (MCP) — открытый стандарт для подключения приложений ИИ к внешним инструментам и данным. MCP предоставляет общий протокол для моделей для доступа к контексту, такому как функции (инструменты), источники данных (ресурсы) или предопределенные подсказки.

Gemini SDK имеют встроенную поддержку MCP, что сокращает шаблонный код и предлагает автоматический вызов инструментов для инструментов MCP. Когда модель генерирует вызов инструмента MCP, клиентский SDK Python и JavaScript может автоматически выполнить инструмент MCP и отправить ответ обратно модели в последующем запросе, продолжая этот цикл до тех пор, пока модель не перестанет делать вызовы инструментов.

Здесь вы можете найти пример использования локального сервера MCP с Gemini и mcp SDK.

pip install mcp

import os
import asyncio
from datetime import datetime
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from google import genai

client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))

# Create server parameters for stdio connection
server_params = StdioServerParameters(
    command="npx",  # Executable
    args=["-y", "@philschmid/weather-mcp"],  # MCP Server
    env=None,  # Optional environment variables
)

async def run():
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Prompt to get the weather for the current day in London.
            prompt = f"What is the weather in London in {datetime.now().strftime('%Y-%m-%d')}?"
            # Initialize the connection between client and server
            await session.initialize()
            # Send request to the model with MCP function declarations
            response = await client.aio.models.generate_content(
                model="gemini-2.0-flash",
                contents=prompt,
                config=genai.types.GenerateContentConfig(
                    temperature=0,
                    tools=[session],  # uses the session, will automatically call the tool
                    # Uncomment if you **don't** want the sdk to automatically call the tool
                    # automatic_function_calling=genai.types.AutomaticFunctionCallingConfig(
                    #     disable=True
                    # ),
                ),
            )
            print(response.text)

# Start the asyncio event loop and run the main function
asyncio.run(run())

npm install @modelcontextprotocol/sdk

import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai';
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create server parameters for stdio connection
const serverParams = new StdioClientTransport({
  command: "npx", // Executable
  args: ["-y", "@philschmid/weather-mcp"] // MCP Server
});

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0"
  }
);

// Configure the client
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

// Initialize the connection between client and server
await client.connect(serverParams);

// Send request to the model with MCP tools
const response = await ai.models.generateContent({
  model: "gemini-2.0-flash",
  contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`,
  config: {
    tools: [mcpToTool(client)],  // uses the session, will automatically call the tool
    // Uncomment if you **don't** want the sdk to automatically call the tool
    // automaticFunctionCalling: {
    //   disable: true,
    // },
  },
});
console.log(response.text)

// Close the connection
await client.close();

Ограничения при встроенной поддержке MCP

Встроенная поддержка MCP является экспериментальной функцией в наших SDK и имеет следующие ограничения:

• Поддерживаются только инструменты, а не ресурсы или подсказки.
• Он доступен для Python и JavaScript/TypeScript SDK.
• В будущих версиях могут произойти критические изменения.

Ручная интеграция серверов MCP всегда возможна, если это ограничивает ваши возможности.

Поддерживаемые модели

Экспериментальные модели не включены. Их возможности вы можете найти на странице обзора моделей .

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

• Описания функций и параметров: будьте предельно ясны и конкретны в своих описаниях. Модель опирается на них, чтобы выбрать правильную функцию и предоставить соответствующие аргументы.
• Именование: используйте описательные имена функций (без пробелов, точек и тире).
• Строгая типизация: используйте определенные типы (целое число, строка, перечисление) для параметров, чтобы уменьшить количество ошибок. Если параметр имеет ограниченный набор допустимых значений, используйте перечисление.
• Выбор инструмента: Хотя модель может использовать произвольное количество инструментов, предоставление слишком большого количества может увеличить риск выбора неправильного или неоптимального инструмента. Для достижения наилучших результатов стремитесь предоставлять только соответствующие инструменты для контекста или задачи, в идеале сохраняя активный набор максимум в 10-20. Рассмотрите динамический выбор инструментов на основе контекста разговора, если у вас большое общее количество инструментов.
• Оперативное проектирование:
  • Предоставьте контекст: расскажите модели о ее роли (например, «Вы полезный помощник по прогнозу погоды»).
  • Дайте инструкции: укажите, как и когда использовать функции (например, «Не угадывайте даты; всегда используйте будущую дату для прогнозов»).
  • Поощряйте уточнения: попросите модель задавать уточняющие вопросы при необходимости.
• Температура: используйте низкую температуру (например, 0) для более детерминированных и надежных вызовов функций.
• Проверка: если вызов функции имеет существенные последствия (например, размещение заказа), проверьте вызов у ​​пользователя перед его выполнением.
• Обработка ошибок : реализуйте надежную обработку ошибок в своих функциях, чтобы изящно обрабатывать неожиданные входные данные или сбои API. Возвращайте информативные сообщения об ошибках, которые модель может использовать для генерации полезных ответов пользователю.
• Безопасность: Помните о безопасности при вызове внешних API. Используйте соответствующие механизмы аутентификации и авторизации. Избегайте раскрытия конфиденциальных данных при вызовах функций.
• Ограничения по токенам: Описания функций и параметры учитываются в вашем лимите входных токенов. Если вы достигаете лимитов по токенам, рассмотрите возможность ограничения количества функций или длины описаний, разбейте сложные задачи на более мелкие, более целевые наборы функций.

Примечания и ограничения

• Поддерживается только подмножество схемы OpenAPI .
• Поддерживаемые типы параметров в Python ограничены.
• Автоматический вызов функций доступен только в Python SDK.