Google Gemini

Google Gemini может обеспечивать работу агента, созданного с помощью Agent Framework, через Gemini Developer API или Gemini Enterprise Agent Platform (ранее Vertex AI). Клиент для конкретного поставщика обрабатывает аутентификацию и параметры запросов Gemini, в то время как Agent Framework отвечает за определение агента и оркестрацию.

Это важно

Google Gemini и Vertex AI являются сторонними системами. Просмотрите условия обслуживания, обработку данных, региональные границы, доступ к модели и затраты на использование перед отправкой данных приложения.

Установите Gemini IChatClient

Пример .NET демонстрирует официальный клиент Google GenAI и реализацию сообществаMscc.GenerativeAI.Microsoft.

dotnet add package Google.GenAI
dotnet add package Mscc.GenerativeAI.Microsoft
dotnet add package Microsoft.Agents.AI --prerelease

Configuration

GOOGLE_GENAI_API_KEY="<google-ai-studio-api-key>"
GOOGLE_GENAI_MODEL="gemini-2.5-flash"

const string JokerInstructions = "You are good at telling jokes.";
const string JokerName = "JokerAgent";

string apiKey = Environment.GetEnvironmentVariable("GOOGLE_GENAI_API_KEY") ?? throw new InvalidOperationException("Please set the GOOGLE_GENAI_API_KEY environment variable.");
string model = Environment.GetEnvironmentVariable("GOOGLE_GENAI_MODEL") ?? "gemini-2.5-flash";

// Using a Google GenAI IChatClient implementation

ChatClientAgent agentGenAI = new(
    new Client(vertexAI: false, apiKey: apiKey).AsIChatClient(model),
    name: JokerName,
    instructions: JokerInstructions);

AgentResponse response = await agentGenAI.RunAsync("Tell me a joke about a pirate.");
Console.WriteLine($"Google GenAI client based agent response:\n{response}");

// Using a community driven Mscc.GenerativeAI.Microsoft package

ChatClientAgent agentCommunity = new(
    new GeminiChatClient(apiKey: apiKey, model: model),
    name: JokerName,
    instructions: JokerInstructions);

response = await agentCommunity.RunAsync("Tell me a joke about a pirate.");
Console.WriteLine($"Community client based agent response:\n{response}");

Выберите одну реализацию IChatClient и настройте Gemini Developer API или аутентификацию в Vertex AI.

Установите пакет

pip install agent-framework-gemini --pre

Configuration

Используйте либо API разработчика Gemini:

GOOGLE_API_KEY="<api-key>"
GOOGLE_MODEL="gemini-2.5-flash"

Или настройте платформу агента Gemini Enterprise:

GOOGLE_GENAI_USE_ENTERPRISE="true"
GOOGLE_CLOUD_PROJECT="<project-id>"
GOOGLE_CLOUD_LOCATION="global"
GOOGLE_MODEL="gemini-2.5-flash"

Старый GOOGLE_GENAI_USE_VERTEXAI=true параметр остается поддерживаемым. Коннектор больше не считывает GEMINI_API_KEY, GEMINI_MODEL или GEMINI_EMBEDDING_MODEL; используйте соответствующие переменные GOOGLE_* или передавайте значения явно.

GeminiChatClient поддерживает потоковую передачу, средства функций, структурированные выходные данные, расширенные средства мышления и средства, размещенные у поставщика.

    """Runs the agent and waits for the complete response before printing it."""
    print("=== Non-streaming ===")

    # 1. Create the agent with the Gemini chat client and local weather tool.
    agent = Agent(
        client=GeminiChatClient(),
        name="WeatherAgent",
        instructions="You are a helpful weather agent.",
        tools=[get_weather],
    )

    # 2. Ask the agent for a single weather lookup and print the final response.
    query = "What's the weather like in Karlsruhe, Germany?"
    print(f"User: {query}")
    result = await agent.run(query)
    print(f"Result: {result}\n")


async def streaming_example() -> None:
    """Runs the agent and prints each chunk as it is received."""
    print("=== Streaming ===")

    # 1. Create the same agent configuration for a streaming tool-call example.
    agent = Agent(
        client=GeminiChatClient(),
        name="WeatherAgent",
        instructions="You are a helpful weather agent.",
        tools=[get_weather],
    )

    # 2. Ask a multi-location question and stream the model output as it arrives.
    query = "What's the weather like in Portland and in Paris?"
    print(f"User: {query}")
    print("Agent: ", end="", flush=True)
    async for chunk in agent.run(query, stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print("\n")

Обработка сбоев запросов

При потоковых и непотоковых запусках ошибки запросов Gemini SDK передаются через исключения Agent Framework. Сбои HTTP 401 и 403 вызывают ChatClientInvalidAuthException, другие сбои HTTP 4xx вызывают ChatClientInvalidRequestException, а все остальные сбои поставщика вызывают ChatClientException.

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

Включить сводки мыслей

В примере расширенного мышления показано, как настроить ThinkingConfig. Чтобы получать сводки рассуждений Gemini, задайте include_thoughts=True в конфигурации рассуждений:

options: GeminiChatOptions = {
    "thinking_config": ThinkingConfig(include_thoughts=True, thinking_budget=2048),
}

Когда Gemini возвращает сводку рассуждений, GeminiChatClient включает её в ответ в виде Content с type == "text_reasoning". Прочитайте сводку от content.text.

Для запуска без потоковой передачи отфильтруйте contents каждого элемента в result.messages. Для выполнения потоковой передачи фильтруйте каждый chunk.contentsиз них. Такие средства доступа к тексту, как result.text и chunk.text, включают только содержимое text, поэтому, если вашему приложению нужны сводки рассуждений, проверяйте коллекции содержимого.

Генерация эмбеддингов

GeminiEmbeddingClient используется gemini-embedding-2 по умолчанию. Переопределите это с помощью GOOGLE_EMBEDDING_MODEL или параметра конструктора model. Для ввода текста требуется тип задачи для каждого вызова; используется RETRIEVAL_DOCUMENT при индексировании и RETRIEVAL_QUERY при поиске одного векторного пространства.

import asyncio

from agent_framework.gemini import GeminiEmbeddingClient
from dotenv import load_dotenv

load_dotenv()


async def main() -> None:
    """Embed a document and a search query for the same vector index."""
    # 1. Choose task instructions for each call, not for the client.
    client = GeminiEmbeddingClient()
    try:
        # 2. Use matching dimensions for stored documents and search queries.
        document = await client.get_embeddings(
            ["Agent Framework helps build and orchestrate AI agents."],
            options={"task_type": "RETRIEVAL_DOCUMENT", "title": "Agent Framework", "dimensions": 768},
        )
        query = await client.get_embeddings(
            ["How can I orchestrate AI agents?"],
            options={"task_type": "RETRIEVAL_QUERY", "dimensions": 768},
        )
        print(f"Document embedding: {document[0].dimensions} dimensions")
        print(f"Query embedding: {query[0].dimensions} dimensions")

Используйте одну и ту же модель и размерность для эмбеддингов документов и запросов. Клиент также принимает значения Part и Content из Google SDK для мультимедиа для изображений, аудио, видео, PDF-файлов или комбинированных эмбеддингов текста и мультимедиа. Мультимедийные входные данные не используют префикс для текстовой задачи.

Когда коллекция векторов генерирует эмбеддинги, передавайте задачу для документа через upsert(..., embeddings_options=...), а задачу для запроса — через search(..., embeddings_options=...) или create_vector_search_tool(..., embeddings_options=...). Для нескольких векторных полей используйте embeddings_options_by_field. Agent Framework предоставляет измерения выбранного поля и отклоняет конфликтующие значения.

Пакет включает фабрики для подключения к Google Search, подключения к Google Maps, выполнения кода, поиска файлов и MCP.

Обоснование с помощью Поиска Google

from agent_framework import Agent
from agent_framework.gemini import GeminiChatClient
from dotenv import load_dotenv

load_dotenv()


async def main() -> None:
    """Run the Google Search grounding example."""
    print("=== Google Search grounding ===")

    # 1. Create the agent with Gemini and the built-in Google Search grounding tool.
    agent = Agent(
        client=GeminiChatClient(),
        name="SearchAgent",
        instructions="You are a helpful assistant. Use Google Search to provide accurate, up-to-date answers.",
        tools=[GeminiChatClient.get_web_search_tool()],
    )

    # 2. Ask a current-events style question and stream the grounded answer.
    query = "What is the latest stable release of the .NET SDK?"
    print(f"User: {query}")
    print("Agent: ", end="", flush=True)
    async for chunk in agent.run(query, stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print("\n")


if __name__ == "__main__":
    asyncio.run(main())

Go SDK предоставляет geminiprovider для инференса Gemini. Создайте стандарт *agent.Agent с помощью конструктора для конкретного поставщика.

Ознакомьтесь с пакетом и примерамипоставщика Gemini.

Tools

инструмент	C#	Python	Go	Notes
Средства функций	✅	✅	✅	Вызов функций стандартной модели.
Утверждение инструмента	✅	✅	✅	Применяется циклом инструментов фреймворка.
Интерпретатор кода	❌	✅	❌	GeminiChatClient.get_code_interpreter_tool().
Поиск файлов	❌	✅	❌	GeminiChatClient.get_file_search_tool().
Поиск в Интернете	❌	✅	❌	Обоснование через get_web_search_tool() Google Search.
Привязка к Google Maps	❌	✅	❌	GeminiChatClient.get_maps_grounding_tool().
Размещенные средства MCP	❌	✅	❌	GeminiChatClient.get_mcp_tool().
Локальные средства MCP	✅	✅	✅	Выполняется в процессе приложения.

Дальнейшие действия

ONNX