البحث على الويب

يسمح Web Search للوكلاء بالبحث في الويب عن معلومات up-to-date. تمكن هذه الأداة الوكلاء من الإجابة عن الأسئلة حول الأحداث الحالية، والعثور على الوثائق، والوصول إلى المعلومات بخلاف بيانات التدريب الخاصة بهم.

Note

يعتمد توفر Web Search على موفر العامل الأساسي. راجع نظرة عامة على الموفرين للحصول على الدعم الخاص بموفر الخدمة.

يوضح المثال التالي كيفية إنشاء عامل باستخدام أداة Web Search:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Requires: dotnet add package Microsoft.Agents.AI.Foundry --prerelease
var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";

// Create an agent with hosted web search.
AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant that can search the web for current information.",
        tools: [new HostedWebSearchTool()]);

Console.WriteLine(await agent.RunAsync("What is the current weather in Seattle?"));

تحذير

DefaultAzureCredential مناسب للتنمية ولكنه يتطلب دراسة متأنية في الإنتاج. في الإنتاج، ضع في اعتبارك استخدام بيانات اعتماد محددة (على سبيل المثال، ManagedIdentityCredential) لتجنب مشكلات زمن الانتقال، وبحث بيانات الاعتماد غير المقصودة، والمخاطر الأمنية المحتملة من الآليات الاحتياطية.

يوضح المثال التالي كيفية إنشاء عامل باستخدام أداة Web Search:

# Copyright (c) Microsoft. All rights reserved.

import asyncio

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient

"""
OpenAI Responses Client with Web Search Example

This sample demonstrates using get_web_search_tool() with OpenAI Responses Client
for direct real-time information retrieval and current data access.
"""


async def main() -> None:
    client = OpenAIChatClient()

    # Create web search tool with location context
    web_search_tool = client.get_web_search_tool(
        user_location={"city": "Seattle", "country": "US"},
    )

    agent = Agent(
        client=client,
        instructions="You are a helpful assistant that can search the web for current information.",
        tools=[web_search_tool],
    )

    message = "What is the current weather? Do not ask for my current location."
    stream = False
    print(f"User: {message}")

    if stream:
        print("Assistant: ", end="")
        async for chunk in agent.run(message, stream=True):
            if chunk.text:
                print(chunk.text, end="")
        print("")
    else:
        response = await agent.run(message)
        print(f"Assistant: {response}")


if __name__ == "__main__":
    asyncio.run(main())

البحث على الويب

hostedtool.WebSearch يتيح النوع البحث على الويب من جانب الخادم عند استخدام موفر يدعمه.

import "github.com/microsoft/agent-framework-go/tool/hostedtool"

webSearch := &hostedtool.WebSearch{}

a := foundryprovider.NewAgent(endpoint, token, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
    Config: agent.Config{
        Tools: []tool.Tool{webSearch},
    },
})

Note

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

استخدام بحث الويب مع Harness Agent

بالنسبة إلى عامل عادي، أضف HostedWebSearchTool إلى أدوات العامل، كما هو موضح سابقا. HarnessAgent يضيف واحدا HostedWebSearchTool بشكل افتراضي، لذلك لا يلزم تسجيل الأداة:

using Microsoft.Agents.AI;

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    ChatOptions = new()
    {
        Instructions = "Use web search for current information and cite the sources you used.",
    },
});

تعيين DisableWebSearch = true عندما لا يدعم الموفر المحدد البحث المستضاف على الويب أو عندما تريد تسجيل أداة بحث خاصة بالموفر بنفسك من خلال ChatOptions.Tools. إذا أضفت أداة البحث على الويب الخاصة بك دون تعطيل الإعداد الافتراضي، فسيتلقى العامل كلتا الأدوتين.

تتم استضافة البحث على الويب من قبل موفر النموذج؛ لا توجد دورة حياة عميل بحث محلية ل Harness لإدارتها. يعتمد التوفر والنماذج المدعومة ومعلمات البحث وإقامة البيانات والفوترة IChatClient على الموفر. يمكن للعملاء غير المعتمدين رفض الأداة المستضافة عند إرسال الطلب.

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

HarnessAgent متوفر من الحزمة Microsoft.Agents.AI.Harness .

بالنسبة إلى عامل عادي، قم باستدعاء client.get_web_search_tool(...) الأداة التي تم إرجاعها وتمريرها إلى Agent، كما هو موضح سابقا. create_harness_agent استدعاءات client.get_web_search_tool() بدون وسيطات بشكل افتراضي عند تنفيذ SupportsWebSearchToolالعميل :

from agent_framework import create_harness_agent

agent = create_harness_agent(client=client)

إذا لم ينفذ SupportsWebSearchToolالعميل ، يسجل المصنع تحذيرا ويستمر دون بحث على الويب. تعيين disable_web_search=True لمنع التسجيل التلقائي والتحذير.

لتمرير الإعدادات الخاصة بالموفر، قم بتعطيل الإعداد الافتراضي وتسجيل الأداة المكونة بشكل صريح:

agent = create_harness_agent(
    client=client,
    disable_web_search=True,
    tools=[
        client.get_web_search_tool(
            user_location={"city": "Seattle", "country": "US"},
            search_context_size="medium",
        )
    ],
)

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

create_harness_agent يتم إصداره في agent-framework-core؛ يظل البحث على الويب متوفرا فقط من خلال العملاء الذين ينفذون SupportsWebSearchTool.

لا تتوفر حاليا حزمة Go Harness. أضف hostedtool.WebSearch إلى عامل Go عادي كما هو موضح سابقا.

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

أدوات MCP المستضافة