Мастерство вызова функций для создания инструментальных AI-агентов в реальном времени с Gemini 2.0 Flash

Вызов функций — мост между естественным языком и реальными API

Вызов функций позволяет большим языковым моделям (LLM) выступать посредниками между запросами на естественном языке и вызовами кода или API. Вместо генерации простого текста модель может вызывать заранее определённые функции, формируя структурированные JSON-вызовы с именем функции и аргументами. Приложение выполняет эти вызовы и возвращает результаты. Этот цикл может повторяться несколько раз, обеспечивая сложные многошаговые взаимодействия, полностью управляемые разговором.

Создание погодного ассистента с Gemini 2.0 Flash

В этом руководстве показано, как реализовать вызов функций на примере погодного ассистента с использованием модели Google Gemini 2.0 Flash. Интеграция вызовов функций позволяет ассистенту получать актуальные погодные данные и выполнять другие задачи в реальном времени через разговорный интерфейс, исключая необходимость заполнять формы или переключаться между экранами.

Настройка окружения и SDK

Установите Python SDK Gemini, а также библиотеки geopy и requests для геолокации и HTTP-запросов:

!pip install "google-genai>=1.0.0" geopy requests

Импортируйте SDK и создайте клиент с вашим API-ключом:

import os
from google import genai
 
GEMINI_API_KEY = "Use_Your_API_Key"
client = genai.Client(api_key=GEMINI_API_KEY)
model_id = "gemini-2.0-flash"

Пример простой генерации текста

Отправьте запрос модели и выведите ответ:

res = client.models.generate_content(
    model=model_id,
    contents=["Tell me 1 good fact about Nuremberg."]
)
print(res.text)

Определение вызовов функций через JSON Schema

Опишите функцию погоды с помощью JSON Schema, указав имя, описание и параметры:

weather_function = {
    "name": "get_weather_forecast",
    "description": "Получает погоду через Open-Meteo API для указанного города и даты (yyyy-mm-dd). Возвращает словарь с временем и температурой по часам.",
    "parameters": {
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "Город и штат, например, San Francisco, CA"
            },
            "date": {
                "type": "string",
                "description": "Дата прогноза в формате (yyyy-mm-dd)"
            }
        },
        "required": ["location","date"]
    }
}

Настройте модель для использования этого инструмента:

from google.genai.types import GenerateContentConfig
 
config = GenerateContentConfig(
    system_instruction="Вы — полезный ассистент, который использует инструменты для доступа и получения информации из погодного API. Сегодня 2025-03-04.",
    tools=[{"function_declarations": [weather_function]}],
)

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

Запрос без конфигурации функций возвращает обычный текст:

response = client.models.generate_content(
    model=model_id,
    contents='Whats the weather in Berlin today?'
)
print(response.text)

С конфигурацией Gemini обнаружит и создаст вызов функции:

response = client.models.generate_content(
    model=model_id,
    config=config,
    contents='Whats the weather in Berlin today?'
)
 
for part in response.candidates[0].content.parts:
    print(part.function_call)

Реализация цикла выполнения вызовов функций

Определите Python-функцию для получения погодных данных с помощью geopy и Open-Meteo API:

from google.genai import types
from geopy.geocoders import Nominatim
import requests
 
g = Nominatim(user_agent="weather-app")
def get_weather_forecast(location, date):
    location = g.geocode(location)
    if location:
        try:
            response = requests.get(f"https://api.open-meteo.com/v1/forecast?latitude={location.latitude}&longitude={location.longitude}&hourly=temperature_2m&start_date={date}&end_date={date}")
            data = response.json()
            return {time: temp for time, temp in zip(data["hourly"]["time"], data["hourly"]["temperature_2m"])}
        except Exception as e:
            return {"error": str(e)}
    else:
        return {"error": "Местоположение не найдено"}

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

def call_function(function_name, **kwargs):
    return functions[function_name](**kwargs)
 
def function_call_loop(prompt):
    contents = [types.Content(role="user", parts=[types.Part(text=prompt)])]
    response = client.models.generate_content(
        model=model_id,
        config=config,
        contents=contents
    )
    for part in response.candidates[0].content.parts:
        contents.append(types.Content(role="model", parts=[part]))
        if part.function_call:
            print("Обнаружен вызов инструмента")
            function_call = part.function_call
            print(f"Вызов инструмента: {function_call.name} с аргументами: {function_call.args}")
            tool_result = call_function(function_call.name, **function_call.args)
            function_response_part = types.Part.from_function_response(
                name=function_call.name,
                response={"result": tool_result},
            )
            contents.append(types.Content(role="user", parts=[function_response_part]))
            print(f"Отправка результатов инструмента в LLM")
            func_gen_response = client.models.generate_content(
                model=model_id, config=config, contents=contents
            )
            contents.append(types.Content(role="model", parts=[func_gen_response]))
    return contents[-1].parts[0].text.strip()
 
result = function_call_loop("Whats the weather in Berlin today?")
print(result)

Вызов функций напрямую через Python

Определите функцию с типами и докстрингом:

from geopy.geocoders import Nominatim
import requests
 
geolocator = Nominatim(user_agent="weather-app")
 
def get_weather_forecast(location: str, date: str) -> str:
    """
    Получает погоду через Open-Meteo API для заданного города и даты (yyyy-mm-dd). Возвращает словарь с временем и температурой по часам.
   
    Args:
        location (str): Город и штат, например, San Francisco, CA
        date (str): Дата прогноза в формате (yyyy-mm-dd)
    Returns:
        Dict[str, float]: Словарь с ключами-временем и значениями-температурами
    """
    location = geolocator.geocode(location)
    if location:
        try:
            response = requests.get(f"https://api.open-meteo.com/v1/forecast?latitude={location.latitude}&longitude={location.longitude}&hourly=temperature_2m&start_date={date}&end_date={date}")
            data = response.json()
            return {time: temp for time, temp in zip(data["hourly"]["time"], data["hourly"]["temperature_2m"])}
        except Exception as e:
            return {"error": str(e)}
    else:
        return {"error": "Местоположение не найдено"}

Настройка Gemini для использования Python-функции

Зарегистрируйте Python-функцию как вызываемый инструмент и управляйте автоматическим вызовом:

from google.genai.types import GenerateContentConfig
 
config = GenerateContentConfig(
    system_instruction="Вы — полезный ассистент, который помогает с вопросами о погоде. Сегодня 2025-03-04.",
    tools=[get_weather_forecast],
    automatic_function_calling={"disable": True}
)

Просмотр решений Gemini о вызове функций

Отправьте запрос и изучите сгенерированный вызов функции без автоматического выполнения:

r = client.models.generate_content(
    model=model_id,
    config=config,
    contents='Whats the weather in Berlin today?'
)
for part in r.candidates[0].content.parts:
    print(part.function_call)

Включение автоматического вызова функций

Включите автоматический вызов, чтобы Gemini самостоятельно вызывал инструмент и возвращал естественно-языковой ответ:

config = GenerateContentConfig(
    system_instruction="Вы — полезный ассистент, который использует инструменты для получения информации из погодного API.",
    tools=[get_weather_forecast],
)
 
r = client.models.generate_content(
    model=model_id,
    config=config,
    contents='Whats the weather in Berlin today?'
)
 
print(r.text)

Добавление пользовательского контекста для персонализации

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

prompt = f"""
Сегодня 2025-03-04. Вы общаетесь с Эндрю, у вас есть дополнительная информация о нем.
 
Контекст пользователя:
- имя: Эндрю
- местоположение: Нюрнберг
 
Пользователь: Могу ли я сегодня надеть футболку?"""
 
r = client.models.generate_content(
    model=model_id,
    config=config,
    contents=prompt
)
 
print(r.text)

Модель выдаст рекомендацию на основе прогноза для указанного дня.

Итог

Определяя функции через JSON Schema или Python, настраивая Gemini 2.0 Flash для распознавания и генерации вызовов функций и реализуя цикл исполнения, разработчики могут создавать мощных инструментальных AI-ассистентов в реальном времени. Такие агенты автоматизируют рабочие процессы, получают актуальные данные и взаимодействуют с API в рамках естественных диалогов.

Дополнительные ресурсы

Полный Colab ноутбук доступен для практики. Присоединяйтесь к сообществу в Twitter, Telegram, LinkedIn и на ML SubReddit с более чем 90 тысячами участников. Зарегистрируйтесь на виртуальную конференцию miniCON по AGENTIC AI с мастер-классами и сертификатами.