Google Gemini

يمكن ل Google Gemini دعم وكيل إطار عمل العامل من خلال واجهة برمجة تطبيقات مطور Gemini أو Gemini Enterprise Agent Platform (المعروف سابقا بالذكاء الاصطناعي Vertex). يعالج العميل الخاص بالموفر خيارات المصادقة وطلب Gemini بينما يمتلك إطار عمل العامل تعريف العامل وتنسيقه.

Important

Google Gemini وVertex AI هما نظامان تابعان لجهة خارجية. راجع شروط الخدمة ومعالجة البيانات والحدود الإقليمية والوصول إلى النموذج وتكاليف الاستخدام قبل إرسال بيانات التطبيق.

تعامل مع إخراج النموذج أو تضمينه واستدعاءات الأدوات التي تم إنشاؤها بواسطة النموذج عند دعمها، كإدخال تطبيق غير موثوق به. تحقق من صحتها قبل أن تنفذ التعليمات البرمجية آثارا جانبية أو تعرض المحتوى. إذا قمت بتكوين نقطة نهاية مخصصة، فتحقق من أنك تثق في عنوان URL الخاص به وعامل التشغيل الخاص به.

تثبيت الجوزاء 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

الإعداد

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 أو مصادقة Vertex AI.

تثبيت الحزمة

pip install agent-framework-gemini --pre

الإعداد

استخدم إما واجهة برمجة تطبيقات مطور Gemini:

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

أو قم بتكوين Gemini Enterprise Agent Platform:

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 من خلال استثناءات إطار عمل العامل. تؤدي حالات فشل HTTP 401 و403 إلى رفع ChatClientInvalidAuthException، وترفع ChatClientInvalidRequestExceptionحالات فشل HTTP 4xx الأخرى ، وترفع ChatClientExceptionجميع حالات فشل الموفر الأخرى .

التقاط ChatClientException متى يجب تطبيق نفس معالجة الأخطاء عبر موفري الدردشة.

تضمين ملخصات الفكر

يوضح نموذج التفكير الموسع كيفية تكوين ThinkingConfig. لتلقي ملخصات التفكير الجوزاء، تعيين 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 Google SDK وقيم الصورة أو Content الصوت أو الفيديو أو PDF أو تضمينات النص والوسائط المجمعة. لا تستخدم إدخالات الوسائط بادئة مهمة نصية.

عندما تقوم مجموعة متجهات بإنشاء عمليات تضمين، قم بتمرير مهمة المستند من خلالها upsert(..., embeddings_options=...) ومهمة الاستعلام من خلال search(..., embeddings_options=...) أو create_vector_search_tool(..., embeddings_options=...). بالنسبة لحقول متجهات متعددة، استخدم embeddings_options_by_field. يوفر إطار عمل العامل أبعاد الحقل المحدد ويرفض القيم المتعارضة.

تتضمن الحزمة مصانع لتاريض بحث Google، وتكوين خرائط Google، وتنفيذ التعليمات البرمجية، والبحث في الملفات، و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())

يوفر geminiprovider Go SDK استدلال Gemini. إنشاء معيار *agent.Agent من خلال الدالة الإنشائية الخاصة بالموفر.

تثبيت الوحدة النمطية Go:

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

قم بتعيين GEMINI_API_KEY و، اختياريا، GEMINI_MODEL. العينة التي يتم الاحتفاظ بها افتراضيا إلى gemini-2.5-flash الواجهة الخلفية لواجهة برمجة تطبيقات 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)
}

يدعم الموفر أدوات الوظائف وخرائط البحث المستضاف على الويب وتنفيذ التعليمات البرمجية والبحث عن الملفات إلى إعلانات أداة Gemini الأصلية. تظل القدرات المستضافة خاضعة للنموذج والخدمة المحددين. لا يتم تنفيذ إعلانات خادم MCP المستضافة من قبل هذا الموفر؛ قم بتوصيل أدوات MCP محليا عندما تحتاج إلى أدوات وظيفية.

راجع حزمة موفر Geminiوعينة كاملة.

ادوات

الأداة	C#‎	Python	Go	Notes
أدوات الدالة	✅	✅	✅	استدعاء دالة النموذج القياسي.
الموافقة على الأداة	✅	✅	✅	يتم تطبيقه بواسطة حلقة أداة إطار العمل.
مترجم شفرة	❌	✅	✅
البحث عن الملفات	❌	✅	✅
بحث الويب	❌	✅	✅
أرضية خرائط Google	❌	✅	❌	GeminiChatClient.get_maps_grounding_tool().
أدوات MCP المستضافة	❌	✅	❌	GeminiChatClient.get_mcp_tool().
أدوات MCP المحلية	✅	✅	✅	يتم تشغيله في عملية التطبيق.

الخطوات التالية

ONNX