Google Gemini

Google Gemini, Gemini Geliştirici API'si veya Gemini Enterprise Agent Platform (eski adıyla Köşe AI) aracılığıyla bir Agent Framework aracısını yedekleyebilir. Sağlayıcıya özgü istemci, kimlik doğrulama ve Gemini istek seçeneklerini yönetirken Agent Framework, aracı tanımlama ve orkestrasyondan sorumludur.

Önemli

Google Gemini ve Vertex AI üçüncü taraf sistemlerdir. Uygulama verilerini göndermeden önce hizmet koşullarını, veri işlemeyi, bölgesel sınırları, model erişimini ve kullanım maliyetlerini gözden geçirin.

Gemini'yi yükleyin IChatClient

.NET örneği, resmi Google GenAI istemcisini ve topluluk Mscc.GenerativeAI.Microsoft uygulamasını gösterir.

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

Bir IChatClient uygulaması seçin ve Gemini Developer API veya Vertex AI kimlik doğrulamasını yapılandırın.

Paketi yükle

pip install agent-framework-gemini --pre

Configuration

Gemini Developer API’yi kullanın:

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

Veya Gemini Enterprise Agent Platform'ını yapılandırın:

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

Eski GOOGLE_GENAI_USE_VERTEXAI=true ayar desteklenmeye devam eder. Bağlayıcı artık GEMINI_MODEL, GEMINI_EMBEDDING_MODEL veya GEMINI_API_KEY öğelerini okumuyor; bunun yerine ilgili GOOGLE_* değişkenlerini kullanın veya değerleri açıkça iletin.

GeminiChatClient akışlı işleme, fonksiyon araçları, yapılandırılmış çıktı, genişletilmiş akıl yürütme ve sağlayıcı tarafından barındırılan araçları destekler.

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

İstek hatalarını işleme

Akışlı ve akışsız çalışmalarda, Gemini SDK istek başarısızlıkları Agent Framework özel durumları olarak yansıtılır. HTTP 401 ve 403 hataları ChatClientInvalidAuthException yükseltir, diğer HTTP 4xx hataları ChatClientInvalidRequestException yükseltir ve diğer tüm sağlayıcı hataları ChatClientException yükseltir.

Sohbet sağlayıcıları arasında aynı hata işlemenin ne zaman geçerli olması gerektiğini yakalayın ChatClientException .

Düşünce özetlerini dahil et

Genişletilmiş düşünme örneği, yapılandırmasının ThinkingConfignasıl yapılacağını gösterir. İkizler düşünce özetlerini almak için düşünme yapılandırmasında ayarlayın include_thoughts=True :

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

Gemini bir düşünce özeti döndürdüğünde, GeminiChatClient bunu yanıta Content ile type == "text_reasoning" olarak ekler. content.text kaynağındaki özeti okuyun.

Akış olmadan yapılan bir çalıştırma için, contents içindeki her öğenin result.messages öğesini filtreleyin. Bir akış yürütmesi için her chunk.contents öğesini filtreleyin. gibi result.text metin erişimcileri ve chunk.text yalnızca text içerik içerdiğinden, uygulamanızın akıl özetlerine ihtiyacı olduğunda içerik koleksiyonlarını inceleyin.

Eklemeler oluşturma

GeminiEmbeddingClient varsayılan olarak kullanır gemini-embedding-2 . Bunu model veya GOOGLE_EMBEDDING_MODEL oluşturucu parametresiyle geçersiz kılın. Metin girişleri her çağrıda bir görev türü gerektirir; dizin oluştururken ve RETRIEVAL_QUERY aynı vektör alanında arama yaparken kullanınRETRIEVAL_DOCUMENT.

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

Belge ve sorgu ekleme işlemleri için aynı modeli ve boyutları kullanın. İstemci ayrıca görüntü, ses, video, PDF veya birleşik metin ve medya gömmeleri için Google SDK medya Part ve Content değerlerini de kabul eder. Medya girişleri metin görevi ön eki kullanmaz.

Bir vektör koleksiyonu gömüler oluşturduğunda, belge görevini upsert(..., embeddings_options=...) üzerinden, sorgu görevini ise search(..., embeddings_options=...) veya create_vector_search_tool(..., embeddings_options=...) üzerinden geçirin. Birden çok vektör alanı için kullanın embeddings_options_by_field. Aracı Çerçevesi seçilen alanın boyutlarını sağlar ve çakışan değerleri reddeder.

Paket, Google Arama dayanaklandırması, Google Haritalar dayanaklandırması, kod yürütme, dosya arama ve MCP için fabrika sınıfları içerir.

Google Search ile temellendirme

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, Gemini çıkarımı için geminiprovider sağlar. Sağlayıcıya özgü oluşturucu aracılığıyla bir standart *agent.Agent oluşturun.

Gemini sağlayıcı paketine ve örneklere bakın.

Tools

Araç	C#	Python	Go	Notes
İşlev Araçları	✅	✅	✅	Standart model fonksiyon çağırma.
Araç Onayı	✅	✅	✅	Framework araç döngüsü tarafından uygulanır.
Kod Yorumlayıcısı	❌	✅	❌	GeminiChatClient.get_code_interpreter_tool().
Dosya Arama	❌	✅	❌	GeminiChatClient.get_file_search_tool().
Web Araması	❌	✅	❌	get_web_search_tool() aracılığıyla Google Search temellendirme.
Google Haritalar temellendirmesi	❌	✅	❌	GeminiChatClient.get_maps_grounding_tool().
Barındırılan MCP Araçları	❌	✅	❌	GeminiChatClient.get_mcp_tool().
Yerel MCP Araçları	✅	✅	✅	Uygulama işleminde çalışır.

Sonraki Adımlar

ONNX