Google Gemini

Google Gemini dapat mendukung agen Agent Framework melalui Gemini Developer API atau Gemini Enterprise Agent Platform (sebelumnya Vertex AI). Klien khusus penyedia menangani opsi autentikasi dan permintaan Gemini sementara Agent Framework memiliki definisi dan orkestrasi agen.

Penting

Google Gemini dan Vertex AI adalah sistem pihak ketiga. Tinjau persyaratan layanan, penanganan data, batas wilayah, akses model, dan biaya penggunaan sebelum mengirim data aplikasi.

Instal Gemini IChatClient

Sampel .NET menunjukkan klien Google GenAI resmi dan implementasi komunitasMscc.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}");

Pilih satu IChatClient implementasi dan konfigurasikan API Pengembang Gemini atau autentikasi Vertex AI-nya.

Pasang paketnya

pip install agent-framework-gemini --pre

Configuration

Gunakan salah satu dari API Developer Gemini berikut:

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

Atau konfigurasikan Gemini Enterprise Agent Platform:

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

Pengaturan lama GOOGLE_GENAI_USE_VERTEXAI=true tetap didukung. Konektor tidak lagi membaca GEMINI_API_KEY, , GEMINI_MODELatau GEMINI_EMBEDDING_MODEL; menggunakan variabel yang sesuai atau meneruskan GOOGLE_* nilai secara eksplisit.

GeminiChatClient mendukung streaming, alat bantu fungsi, output terstruktur, penalaran mendalam, dan alat yang dihosting oleh penyedia.

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

Menangani kegagalan permintaan

Untuk eksekusi streaming dan non-streaming, kegagalan permintaan Gemini SDK diekspos melalui pengecualian Agent Framework. Kegagalan HTTP 401 dan 403 memunculkan ChatClientInvalidAuthException, kegagalan HTTP 4xx lainnya meningkatkan ChatClientInvalidRequestException, dan semua kegagalan penyedia lainnya memunculkan ChatClientException.

Gunakan ChatClientException ketika penanganan kesalahan yang sama harus diterapkan ke semua penyedia chat.

Sertakan ringkasan pemikiran

Sampel pemikiran yang diperluas menunjukkan cara mengonfigurasi ThinkingConfig. Untuk menerima ringkasan pemikiran Gemini, atur include_thoughts=True dalam konfigurasi pemikiran:

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

Ketika Gemini memberikan ringkasan pemikiran, GeminiChatClient menambahkannya ke dalam respons sebagai Content dengan type == "text_reasoning". Baca ringkasan dari content.text.

Untuk eksekusi tanpa streaming, filter contents setiap item di result.messages. Untuk proses streaming, saring setiap chunk.contents. Aksesor teks seperti result.text dan chunk.text hanya mencakup konten text, jadi periksa koleksi konten ketika aplikasi Anda memerlukan ringkasan penalaran.

Hasilkan embedding

GeminiEmbeddingClient menggunakan gemini-embedding-2 secara bawaan. Ambil alih dengan GOOGLE_EMBEDDING_MODEL atau model parameter konstruktor. Input teks memerlukan jenis tugas pada setiap panggilan; gunakan RETRIEVAL_DOCUMENT saat mengindeks dan RETRIEVAL_QUERY saat mencari ruang vektor yang sama.

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

Gunakan model dan dimensi yang sama untuk penyematan dokumen dan kueri. Klien juga menerima nilai media Google SDK Part dan Content untuk embedding gambar, audio, video, PDF, atau gabungan teks dan media. Masukan media tidak menggunakan prefiks tugas teks.

Saat koleksi vektor menghasilkan embedding, teruskan tugas dokumen melalui upsert(..., embeddings_options=...) dan tugas kueri melalui search(..., embeddings_options=...) atau create_vector_search_tool(..., embeddings_options=...). Untuk beberapa bidang vektor, gunakan embeddings_options_by_field. Kerangka Kerja Agen menyediakan dimensi bidang yang dipilih dan menolak nilai yang bertentangan.

Paket ini mencakup pabrik untuk grounding Google Search, grounding Google Maps, eksekusi kode, pencarian file, dan MCP.

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

SDK Go menyediakan geminiprovider untuk inferensi Gemini. Buat standar *agent.Agent melalui konstruktor khusus penyedia.

Lihat paket penyedia Gemini dan contohnya.

Tools

Alat	C#	Python	Go	Catatan
Peralatan Fungsional	✅	✅	✅	Panggilan fungsi model standar.
Persetujuan Alat	✅	✅	✅	Diterapkan oleh loop alat framework.
Penerjemah Kode	❌	✅	❌	GeminiChatClient.get_code_interpreter_tool().
Pencarian File	❌	✅	❌	GeminiChatClient.get_file_search_tool().
Pencarian Web	❌	✅	❌	Landasan Google Search melalui get_web_search_tool().
Dasar Google Maps	❌	✅	❌	GeminiChatClient.get_maps_grounding_tool().
Alat MCP yang Dihosting	❌	✅	❌	GeminiChatClient.get_mcp_tool().
Alat MCP Lokal	✅	✅	✅	Berjalan di proses aplikasi.

Langkah berikutnya

ONNX