Google Gemini

Installer une Gemini IChatClient

L’exemple .NET illustre le client Google GenAI officiel et l’implémentation de la communauté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}");

Choisissez une IChatClient implémentation et configurez son API de développeur Gemini ou son authentification IA Vertex.

Installer le package

pip install agent-framework-gemini --pre

Configuration

Utilisez l’API Gemini pour les développeurs :

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

Ou configurer Gemini Enterprise Agent Platform :

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

L’ancien paramètre GOOGLE_GENAI_USE_VERTEXAI=true est toujours pris en charge. Le connecteur ne lit plus GEMINI_MODEL, GEMINI_EMBEDDING_MODEL ou GEMINI_API_KEY ; utilisez les variables GOOGLE_* correspondantes ou transmettez les valeurs explicitement.

GeminiChatClient prend en charge la diffusion en continu, les outils de fonction, la sortie structurée, la pensée étendue et les outils hébergés par un fournisseur.

    """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")

Gérer les échecs de requête

Pour les exécutions avec ou sans diffusion en continu, les échecs des requêtes du SDK Gemini sont signalés sous forme d’exceptions du framework Agent. Les échecs HTTP 401 et 403 déclenchent ChatClientInvalidAuthException, d’autres échecs HTTP 4xx déclenchent ChatClientInvalidRequestExceptionet tous les autres échecs de fournisseur déclenchent ChatClientException.

Interceptez ChatClientException lorsque le même traitement des erreurs doit s’appliquer chez les différents fournisseurs de chat.

Inclure des résumés de pensée

L’exemple de réflexion étendu montre comment configurer ThinkingConfig. Pour recevoir des résumés de pensée Gemini, définissez include_thoughts=True dans la configuration de la pensée :

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

Lorsque Gemini retourne un résumé de pensée, GeminiChatClient l’ajoute à la réponse comme Content avec type == "text_reasoning". Lisez le résumé de content.text.

Pour une exécution sans diffusion en continu, filtrez le contents de chaque élément dans result.messages. Pour une exécution en continu, filtrez chaque chunk.contents. Les accesseurs de texte tels que result.text et chunk.text n’incluent que le contenu de text ; examinez donc les collections de contenu lorsque votre application a besoin de résumés du raisonnement.

Générer des embeddings

GeminiEmbeddingClient utilise gemini-embedding-2 par défaut. Remplacez-la par GOOGLE_EMBEDDING_MODEL ou par le paramètre du constructeur model. Les entrées de texte nécessitent un type de tâche sur chaque appel ; utiliser RETRIEVAL_DOCUMENT lors de l’indexation et RETRIEVAL_QUERY lors de la recherche dans le même espace vectoriel.

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")

Utilisez le même modèle et les mêmes dimensions pour les incorporations de documents et de requêtes. Le client accepte également les valeurs de média du SDK Google Part et Content pour les représentations vectorielles d’images, d’audio, de vidéo, de PDF ou de texte et média combinés. Les entrées multimédias n’utilisent pas de préfixe de tâche de texte.

Lorsqu’une collection de vecteurs génère des représentations vectorielles, transmettez la tâche de document via upsert(..., embeddings_options=...) et la tâche de requête via search(..., embeddings_options=...) ou create_vector_search_tool(..., embeddings_options=...). Pour plusieurs champs vectoriels, utilisez embeddings_options_by_field. Agent Framework fournit les dimensions du champ sélectionné et rejette les valeurs en conflit.

Le package comprend des fabriques pour l'ancrage Google Search ou Google Maps, l’exécution du code, la recherche de fichiers et MCP.

Ancrage avec Google Search

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())

Le kit de développement logiciel (SDK) Go fournit geminiprovider pour l’inférence Gemini. Créez une norme *agent.Agent via le constructeur spécifique au fournisseur.

Installez le module Go :

go get github.com/microsoft/agent-framework-go

Définissez GEMINI_API_KEY et, éventuellement, GEMINI_MODEL. L’exemple maintenu est défini par défaut sur gemini-2.5-flash et sélectionne explicitement le back-end de l’API Gemini :

// Copyright (c) Microsoft. All rights reserved.

package main

import (
    "cmp"
    "context"
    "os"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/provider/geminiprovider"
    "google.golang.org/genai"
)

var (
    apiKey = os.Getenv("GEMINI_API_KEY")
    model  = cmp.Or(os.Getenv("GEMINI_MODEL"), "gemini-2.5-flash")
)

var logger = demo.NewLogger(
    "Basic Run",
    "Demonstrates a simple Gemini agent run.",
    "Model", model,
)

func main() {
    ctx := context.Background()
    client, err := genai.NewClient(ctx, &genai.ClientConfig{
        APIKey:  apiKey,
        Backend: genai.BackendGeminiAPI,
    })
    if err != nil {
        demo.Panicf("failed to create Gemini client: %v", err)
    }

    // Create Gemini agent.
    a := geminiprovider.NewAgent(
        client,
        geminiprovider.AgentConfig{
            Model:        model,
            Instructions: "You are good at telling jokes.",
            Config: agent.Config{
                Name:        "Joker",
                Middlewares: []agent.Middleware{logger}, // for logging agent interactions
            },
        },
    )

    // Invoke the agent and output the text result.
    resp, err := a.RunText(ctx, "Tell me a joke about a pirate.").Collect()
    demo.Response(resp, err)
}

Le fournisseur prend en charge les outils de fonction et mappe la recherche web hébergée, l’exécution du code et la recherche de fichiers aux déclarations d’outils natives de Gemini. Les fonctionnalités hébergées restent soumises au modèle et au service sélectionnés. Les déclarations de serveur MCP hébergées ne sont pas implémentées par ce fournisseur ; connectez les outils MCP localement quand vous avez besoin d’outils de fonction.

Consultez le package de fournisseur Gemini et l’exemple complet.