Google Gemini

Installare un Gemini IChatClient

L'esempio .NET illustra il client Ufficiale di Google GenAI e l'implementazione della communityMscc.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}");

Scegli un'implementazione IChatClient e configurane l'autenticazione per l'API Gemini Developer o per Vertex AI.

Installare il pacchetto

pip install agent-framework-gemini --pre

Configuration

Usa una delle seguenti API Gemini per sviluppatori:

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

In alternativa, configurare 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'impostazione precedente GOOGLE_GENAI_USE_VERTEXAI=true rimane supportata. Il connettore non legge più GEMINI_API_KEY, GEMINI_MODEL o GEMINI_EMBEDDING_MODEL; utilizzare le variabili GOOGLE_* corrispondenti o passare i valori esplicitamente.

GeminiChatClient supporta lo streaming, gli strumenti per le funzioni, l'output strutturato, il pensiero esteso e gli strumenti ospitati dal provider.

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

Gestire gli errori delle richieste

Per le esecuzioni di streaming e non in streaming, gli errori di richiesta di Gemini SDK vengono esposti tramite eccezioni di Agent Framework. Gli errori HTTP 401 e 403 generano ChatClientInvalidAuthException, altri errori HTTP 4xx generano ChatClientInvalidRequestExceptione tutti gli altri errori del provider generano ChatClientException.

Intercettare ChatClientException quando la stessa gestione degli errori deve essere applicata tra provider di chat.

Includi riepiloghi di pensiero

L'esempio di pensiero esteso illustra come configurare ThinkingConfig. Per ricevere i riepiloghi del pensiero di Gemini, imposta include_thoughts=True nella configurazione del pensiero:

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

Quando Gemini restituisce un riepilogo del pensiero, GeminiChatClient lo aggiunge alla risposta come Content con type == "text_reasoning". Leggere il riepilogo da content.text.

Per un'esecuzione non in streaming, filtrare il contents di ogni elemento in result.messages. Per un'esecuzione in streaming, filtra ogni chunk.contents. Gli accessor di testo come result.text e chunk.text includono solo il contenuto text, quindi esamina le raccolte di contenuti quando l'app richiede riepiloghi del ragionamento.

Generare incorporamenti

GeminiEmbeddingClient usa gemini-embedding-2 per impostazione predefinita. Sostituiscilo con GOOGLE_EMBEDDING_MODEL o con il parametro del costruttore model. Gli input di testo richiedono un tipo di attività per ogni chiamata; usare RETRIEVAL_DOCUMENT quando si esegue l'indicizzazione e RETRIEVAL_QUERY quando si esegue la ricerca nello stesso spazio vettoriale.

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

Usa lo stesso modello e le stesse dimensioni per gli embedding dei documenti e delle query. Il client accetta anche i valori Google SDK per contenuti multimediali Part e Content per incorporamenti di immagini, audio, video, PDF o testo e contenuti multimediali combinati. Gli input multimediali non usano un prefisso di attività di testo.

Quando una raccolta di vettori genera embedding, passa l'attività relativa al documento tramite upsert(..., embeddings_options=...) e l'attività relativa alla query tramite search(..., embeddings_options=...) o create_vector_search_tool(..., embeddings_options=...). Per più campi vettoriali, usare embeddings_options_by_field. Agent Framework fornisce le dimensioni del campo selezionato e rifiuta i valori in conflitto.

Il pacchetto include factory per il grounding di Google Search, il grounding di Google Maps, l'esecuzione di codice, la ricerca di file e MCP.

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

L'SDK Go fornisce geminiprovider per l'inferenza con Gemini. Creare uno standard *agent.Agent tramite il costruttore specifico del provider.

Consulta il pacchetto del provider Gemini e gli esempi.