Kılavuz: Azure Yapay Zeka Arama kullanarak uçtan uca etmen tabanlı alma çözümü oluşturma

Azure Yapay Zeka Arama ile Foundry Agent Service'i tümleştirerek ajan temelli geri alma için akıllı, MCP özellikli bir çözüm oluşturmayı öğrenin. Bu mimariyi, müşteri desteği veya teknik sorun giderme gibi büyük bilgi etki alanları üzerinde karmaşık mantık yürütme gerektiren konuşma uygulamaları için kullanabilirsiniz.

Bu öğreticide önizleme REST API'leri iki yerde kullanılır. Eşdeğer davranış genel olarak mevcut olsa da bilgi tabanı, ayıklayıcı çıktıyı ve asgari düzeyde akıl yürütmeyi açıkça belirtmek için retrieval_reasoning_effort ve output_mode (önizleme) kullanır. Proje bağlantısı, Azure Yapay Zeka Arama’te kimlik doğrulaması yapmak için RemoteTool (önizleme) ve projenin yönetilen kimliğini kullanır.

Bu öğreticide:

Önkoşullar

• Etkin alma sağlayan herhangi bir bölgede Azure Yapay Zeka Arama hizmeti.

• Microsoft Kuluçka projesi ve kaynak. Proje oluşturduğunuzda, kaynak otomatik olarak oluşturulur.

• Sorgu zamanı vektörleştirmesi için projenize dağıtılan bir metin ekleme modeli. Bu çözüm, text-embedding-3-large kullanır.

• Projenize aracı için bir LLM uygulandı. Bu çözüm, gpt-5-mini kullanır.

  GPT-4 aile modelleri kullanım dışıdır. Microsoft Foundry'deki emeklilik tarihleri ve mevcut durum için bkz: Model emeklilik zamanlaması - Microsoft Foundry.

• Azure Yapay Zeka Arama ve Microsoft Dökümhane kaynaklarına erişme ve yönetme izni. Daha fazla bilgi için bkz. Erişimi yapılandırma.

• Python 3.8 veya üzeri.

• Python ve Jupyter uzantılarıyla Visual Studio Code.

• Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure CLI.

Çözümü anlama

Bu çözüm, uçtan uca alma işlem hattı oluşturmak için Azure Yapay Zeka Arama ve Microsoft Foundry'yi birleştirir:

• Azure Yapay Zeka Arama sorgu planlama, sorgu yürütme ve sonuç sentezini işleyen bilgi bankanızı barındırıyor. İçeriği depolamak için bir arama dizini, dizine başvuran bir bilgi kaynağı ve bilgi kaynağından karma alma gerçekleştiren bir bilgi bankası oluşturursunuz.

• Microsoft Foundry Azure OpenAI model dağıtımlarınızı, proje bağlantınızı ve aracınızı barındırıyor. Bilgi bankanızın MCP uç noktasına işaret eden bir proje bağlantısı oluşturursunuz ve ardından bilgi bankasına erişmek için MCP aracını kullanan bir aracı oluşturursunuz.

Kullanıcı, aracıyı çağıran sohbet botu gibi bir istemci uygulamasıyla etkileşim kurarak sorgu işlemeyi başlatır. Aracı, bilgi bankasına yönelik istekleri yönetmek ve yanıtları sentezlemek için MCP aracını kullanır. Sohbet botu aracıyı çağırdığında, MCP aracı Azure Yapay Zeka Arama bilgi bankasını çağırır ve yanıtı aracıya ve sohbet botuna gönderir.

Erişimi yapılandırma

Başlamadan önce içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim öneririz. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Bu çözüme erişimi yapılandırmak için:

1. Azure portalında oturum açın.

2. Hem arama hizmetiniz hem de projeniz için sistem tarafından atanan yönetilen kimliği etkinleştirin. Bunu her kaynağın Kimlik sayfasında yapabilirsiniz.

3. Arama hizmetinizde rol tabanlı erişimi etkinleştirin ve aşağıdaki rolleri atayın.

   Rolü	Görevli	Amaç
   Arama Servisi Katkıcısı	Kullanıcı hesabınız	Nesne oluşturma
   Arama Dizini Veri Katılımcısı	Kullanıcı hesabınız	Verileri yükleme
   Arama Dizini Veri Okuyucusu	Kullanıcı hesabınız ve proje yönetilen kimliğiniz	Dizine alınan içeriği okuma

4. Projenizin üst kaynağında aşağıdaki rolleri atayın.

   Rolü	Görevli	Amaç
   Dökümhane Kullanıcısı	Kullanıcı hesabınız	Model dağıtımlarına erişme ve ajanlar oluşturma
   Dökümhane Project Yöneticisi	Kullanıcı hesabınız	Proje bağlantısı oluşturma ve aracılarda MCP aracını kullanma
   Bilişsel Hizmetler Kullanıcısı	Arama hizmeti yönetilen kimliği	Bilgi bankasına erişme

Ortamınızı ayarlama

1. Yerel sisteminizde adlı tutorial-agentic-retrieval bir klasör oluşturun.

2. Klasörü Visual Studio Code içinde açın.

3. View>Command Palette öğesini seçin ve ardından Python: Create Environment öğesini seçin. Sanal ortam oluşturmak için istemleri izleyin.

4. Terminal>Yeni Terminal öğesini seçin.

5. Gerekli paketleri yükleyin.

   pip install azure-ai-projects==2.0.0b1 azure-mgmt-cognitiveservices azure-identity ipykernel python-dotenv azure-search-documents==11.7.0b2 requests openai
   

6. klasöründe .env adlı tutorial-agentic-retrieval bir dosya oluşturun.

7. Aşağıdaki değişkenleri dosyaya .env ekleyin ve yer tutucu değerlerini kendi değerlerinizle değiştirin.

   AZURE_SEARCH_ENDPOINT = https://{your-service-name}.search.windows.net
   PROJECT_ENDPOINT = https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}
   PROJECT_RESOURCE_ID = /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.CognitiveServices/accounts/{account-name}/projects/{project-name}
   AZURE_OPENAI_ENDPOINT = https://{your-resource-name}.openai.azure.com
   AZURE_OPENAI_EMBEDDING_DEPLOYMENT = text-embedding-3-large
    AGENT_MODEL = gpt-5-mini
   

   Uç noktaları ve kaynak kimliğini Azure portalında bulabilirsiniz:

   • AZURE_SEARCH_ENDPOINT arama hizmetinizin Genel Bakış sayfasındadır.

   • PROJECT_ENDPOINT , projenizin Uç Noktalar sayfasındadır.

   • PROJECT_RESOURCE_ID , projenizin Özellikler sayfasındadır.

   • AZURE_OPENAI_ENDPOINT , projenizin üst kaynağının Uç Noktalar sayfasındadır.

8. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure Yapay Zeka Arama ve Microsoft Dökümhane kaynaklarınızı içeren aboneliği seçin.

   az login
   

9. klasöründe tutorial.ipynb adlı tutorial-agentic-retrieval bir dosya oluşturun. Sonraki bölümde bu dosyaya kod hücreleri ekleyebilirsiniz.

Çözümü oluşturma

Bu bölümde aracılı alma çözümünün bileşenlerini oluşturacaksınız. Her kod parçacığını not defterindeki ayrı bir kod hücresine tutorial.ipynb ekleyin ve hücreleri sırayla çalıştırın.

Bu bölümdeki adımlar şunlardır:

1. Bağlantıları yükleme
2. Arama dizini oluşturma
3. Belgeleri dizine yükleme
4. Bilgi kaynağı oluşturma
5. Bilgi bankası oluşturma
6. Proje istemcisi ayarlama
7. Proje bağlantısı oluşturma
8. MCP aracıyla aracı oluşturma
9. Temsilciyle sohbet edin
10. Kaynakları temizle

Bağlantıları yükleme

Aşağıdaki kod, .env dosyanızdan ortam değişkenlerini yükler ve Azure Yapay Zeka Arama ve Microsoft Foundry ile bağlantılar kurar.

import os

from azure.identity import DefaultAzureCredential
from azure.mgmt.core.tools import parse_resource_id
from dotenv import load_dotenv

load_dotenv(override=True) # Take environment variables from .env

project_endpoint = os.environ["PROJECT_ENDPOINT"]
project_resource_id = os.environ["PROJECT_RESOURCE_ID"]
project_connection_name = os.getenv("PROJECT_CONNECTION_NAME", "earthknowledgeconnection")
agent_model = os.getenv("AGENT_MODEL", "gpt-5-mini")
agent_name = os.getenv("AGENT_NAME", "earth-knowledge-agent")
endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
knowledge_source_name = os.getenv("AZURE_SEARCH_KNOWLEDGE_SOURCE_NAME", "earth-knowledge-source")
index_name = os.getenv("AZURE_SEARCH_INDEX", "earth-at-night")
azure_openai_endpoint = os.environ["AZURE_OPENAI_ENDPOINT"]
azure_openai_embedding_deployment = os.getenv("AZURE_OPENAI_EMBEDDING_DEPLOYMENT", "text-embedding-3-large")
azure_openai_embedding_model = os.getenv("AZURE_OPENAI_EMBEDDING_MODEL", "text-embedding-3-large")
base_name = os.getenv("AZURE_SEARCH_AGENT_NAME", "earth-knowledge-base")

# Parse the resource ID to extract subscription and other components
parsed_resource_id = parse_resource_id(project_resource_id)
subscription_id = parsed_resource_id['subscription']
resource_group = parsed_resource_id['resource_group']
account_name = parsed_resource_id['name']
project_name = parsed_resource_id['child_name_1']

Arama dizini oluşturma

Azure Yapay Zeka Arama'de dizin, yapılandırılmış bir veri koleksiyonudur. Aşağıdaki kod, bilgi bankanızın aranabilir içeriğini depolamak için bir dizin oluşturur.

Dizin şeması belge tanımlama ve sayfa içeriği, eklemeler ve sayılar için alanlar içerir. Şema ayrıca, metni vektörleştirmek ve semantik benzerlik temelinde belgeleri eşleştirmek için dağıtımınızı text-embedding-3-large kullanan anlamsal derecelendirme ve vektör araması yapılandırmalarını da içerir.

Bu adım hakkında daha fazla bilgi için bkz. Azure Yapay Zeka Arama'da aracısal alma için dizin oluşturma.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizer, AzureOpenAIVectorizerParameters,
    HnswAlgorithmConfiguration, SearchField, SearchIndex,
    SemanticConfiguration, SemanticField, SemanticPrioritizedFields,
    SemanticSearch, VectorSearch, VectorSearchProfile
)

index = SearchIndex(
    name=index_name,
    fields=[
        SearchField(name="id", type="Edm.String", key=True, filterable=True, sortable=True, facetable=True),
        SearchField(name="page_chunk", type="Edm.String", filterable=False, sortable=False, facetable=False),
        SearchField(name="page_embedding_text_3_large", type="Collection(Edm.Single)", stored=False, vector_search_dimensions=3072, vector_search_profile_name="hnsw_text_3_large"),
        SearchField(name="page_number", type="Edm.Int32", filterable=True, sortable=True, facetable=True)
    ],
    vector_search=VectorSearch(
        profiles=[VectorSearchProfile(name="hnsw_text_3_large", algorithm_configuration_name="alg", vectorizer_name="azure_openai_text_3_large")],
        algorithms=[HnswAlgorithmConfiguration(name="alg")],
        vectorizers=[
            AzureOpenAIVectorizer(
                vectorizer_name="azure_openai_text_3_large",
                parameters=AzureOpenAIVectorizerParameters(
                    resource_url=azure_openai_endpoint,
                    deployment_name=azure_openai_embedding_deployment,
                    model_name=azure_openai_embedding_model
                )
            )
        ]
    ),
    semantic_search=SemanticSearch(
        default_configuration_name="semantic_config",
        configurations=[
            SemanticConfiguration(
                name="semantic_config",
                prioritized_fields=SemanticPrioritizedFields(
                    content_fields=[
                        SemanticField(field_name="page_chunk")
                    ]
                )
            )
        ]
    )
)

index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
index_client.create_or_update_index(index)
print(f"Index '{index_name}' created or updated successfully")

Belgeleri dizine yükleme

Şu anda dizin boş. Aşağıdaki kod, dizini NASA's Earth at Night e-book JSON belgeleriyle doldurur. Azure Yapay Zeka Arama gerektirdiği gibi, her belge dizin şemasında tanımlanan alanlara ve veri türlerine uygundur.

Bu adım hakkında daha fazla bilgi için bkz . Dizine veri gönderme.

import requests
from azure.search.documents import SearchIndexingBufferedSender

url = "https://raw.githubusercontent.com/Azure-Samples/azure-search-sample-data/refs/heads/main/nasa-e-book/earth-at-night-json/documents.json"
documents = requests.get(url).json()

with SearchIndexingBufferedSender(endpoint=endpoint, index_name=index_name, credential=credential) as client:
    client.upload_documents(documents=documents)

print(f"Documents uploaded to index '{index_name}'")

Bilgi kaynağı oluşturma

Bilgi kaynağı, kaynak verilere yeniden kullanılabilir bir başvurudur. Aşağıdaki kod, daha önce oluşturduğunuz dizini hedefleyen bir bilgi kaynağı oluşturur.

source_data_fields hangi dizin alanlarının alıntı başvurularına dahil olduğunu belirtir. Bu örnek, yanıtlarda uzun ve anlaşılmaz eklemelerden kaçınmak için yalnızca insan tarafından okunabilen alanları içerir.

Bu adım hakkında daha fazla bilgi için bkz. Arama dizini bilgi kaynağı oluşturma.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    SearchIndexFieldReference, SearchIndexKnowledgeSource,
    SearchIndexKnowledgeSourceParameters
)

ks = SearchIndexKnowledgeSource(
    name=knowledge_source_name,
    description="Knowledge source for Earth at night data",
    search_index_parameters=SearchIndexKnowledgeSourceParameters(
        search_index_name=index_name,
        semantic_configuration_name="semantic_config",
        source_data_fields=[
            SearchIndexFieldReference(name="id"),
            SearchIndexFieldReference(name="page_chunk"),
            SearchIndexFieldReference(name="page_number")
        ]
    ),
)

index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
index_client.create_or_update_knowledge_source(knowledge_source=ks)
print(f"Knowledge source '{knowledge_source_name}' created or updated successfully.")

Bilgi bankası oluşturma

Aşağıdaki kod, bilgi kaynağınızdan aracılı alma işlemlerini düzenleyen bir bilgi tabanı oluşturur. Kod ayrıca, aracınızın bilgi bankasına erişmek için kullanacağı bilgi bankasının MCP uç noktasını da depolar.

Foundry Aracı Hizmeti ile tümleştirme için bilgi bankası aşağıdaki parametrelerle yapılandırılır:

• output_mode (önizleme), aracıya topraklama ve akıl yürütme için ayrıntılı, işlenmemiş içerik sağlayan ayıklayıcı verilere ayarlanır. Alternatif mod olan yanıt sentezi, aracının kaynak içerik üzerinde mantık yürütme becerisini sınırlayan önceden oluşturulmuş yanıtlar döndürür.

• retrieval_reasoning_effort (önizleme), maliyetleri ve gecikmeyi azaltmak için LLM tabanlı sorgu planlamasını atlayan minimum çaba olarak ayarlanmıştır. Diğer mantık yürütme çabaları için bilgi tabanı, kullanıcı sorgularını temin edilmeden önce yeniden oluşturmak için bir LLM kullanır.

Bu adım hakkında daha fazla bilgi için bkz. Azure Yapay Zeka Arama'da bilgi bankası oluşturma.

from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeSourceReference
from azure.search.documents.knowledgebases.models import KnowledgeRetrievalMinimalReasoningEffort

knowledge_base = KnowledgeBase(
    name=base_name,
    knowledge_sources=[
        KnowledgeSourceReference(
            name=knowledge_source_name
        )
    ],
    output_mode="extractiveData",
    retrieval_reasoning_effort=KnowledgeRetrievalMinimalReasoningEffort()
)


index_client = SearchIndexClient(endpoint=endpoint, credential=credential)
index_client.create_or_update_knowledge_base(knowledge_base=knowledge_base)
print(f"Knowledge base '{base_name}' created or updated successfully")

mcp_endpoint = f"{endpoint.rstrip('/')}/knowledgebases/{base_name}/mcp?api-version=2026-08-01-preview"

Proje istemcisi ayarlama

Microsoft Foundry projenize istemci bağlantısı oluşturmak için AIProjectClient kullanın. Projeniz henüz herhangi bir aracı içermiyor olabilir, ancak bu öğreticiyi zaten tamamladıysanız aracı burada listelenir.

from azure.ai.projects import AIProjectClient

project_client = AIProjectClient(endpoint=project_endpoint, credential=credential)

list(project_client.agents.list())

Proje bağlantısı oluşturma

Aşağıdaki kod, Microsoft Foundry'de bilgi bankanızın MCP uç noktasını gösteren bir RemoteTool proje bağlantısı (önizleme) oluşturur. Bu bağlantı, Azure Yapay Zeka Arama kimlik doğrulaması yapmak için proje yönetilen kimliğinizi kullanır.

import requests
from azure.identity import get_bearer_token_provider

bearer_token_provider = get_bearer_token_provider(credential, "https://management.azure.com/.default")
headers = {
    "Authorization": f"Bearer {bearer_token_provider()}",
}

response = requests.put(
    f"https://management.azure.com{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview",
    headers=headers,
    json={
        "name": project_connection_name,
        "type": "Microsoft.MachineLearningServices/workspaces/connections",
        "properties": {
            "authType": "ProjectManagedIdentity",
            "category": "RemoteTool",
            "target": mcp_endpoint,
            "isSharedToAll": True,
            "audience": "https://search.azure.com/",
            "metadata": { "ApiType": "Azure" }
        }
    }
)

response.raise_for_status()
print(f"Connection '{project_connection_name}' created or updated successfully.")

MCP aracıyla aracı oluşturma

Aşağıdaki kod, MCP aracıyla yapılandırılmış bir aracı oluşturur. Aracı bir kullanıcı sorgusu aldığında, yanıt topraklama için ilgili içeriği almak üzere MCP aracı aracılığıyla bilgi bankanızı çağırabilir.

Aracı tanımı, davranışını ve daha önce oluşturduğunuz proje bağlantısını belirten yönergeler içerir. Denemelerimize dayanarak, bu yönergeler bilgi bankası çağrılarının doğruluğunu en üst düzeye çıkarmada ve uygun alıntı biçimlendirmesinin sağlanmasında etkilidir.

Bu adım hakkında daha fazla bilgi için bkz . Hızlı Başlangıç: Yeni aracı oluşturma.

from azure.ai.projects.models import PromptAgentDefinition, MCPTool

instructions = """
You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.
Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`
If you cannot find the answer in the provided knowledge base you must respond with "I don't know".
"""

mcp_kb_tool = MCPTool(
    server_label="knowledge-base",
    server_url=mcp_endpoint,
    require_approval="never",
    allowed_tools=["knowledge_base_retrieve"],
    project_connection_id=project_connection_name
)

agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=agent_model,
        instructions=instructions,
        tools=[mcp_kb_tool]
    )
)

print(f"AI agent '{agent_name}' created or updated successfully")

(İsteğe bağlı) İstek başına başlıklarla izinleri uygula

Bilgi kaynaklarınızdan herhangi biri izin korumalı içerik içeriyorsa, alma altyapısı sonuçları filtreleyebilir ve böylece her kullanıcı yalnızca erişim yetkisine sahip olduğu belgeleri görebilir. Bu filtrelemeyi etkinleştirmek için oturum açmış kullanıcının kimlik belirtecini MCP araç bağlantısının üst bilgisine x-ms-query-source-authorization iletin. Belirteç olmadan, izin etkin kaynaklar sonuçları filtrelenmemiş olarak döndürür. Daha fazla bilgi için Sorgu sırasında izinleri zorlama (önizleme) bölümüne bakın.

Her istekte MCP başlıklarını değiştirmek, örneğin her çağrıda farklı bir kullanıcının belirtecini iletmek için, aracı tanımında yapılandırılmış bir girdi bildirin ve buna aracın headers bölümünde {{placeholder}} olarak başvurun. Çağıran, her çağrıda bu değeri iletir. Bu yaklaşım, proje bağlantısına bağlı MCP araçları için çalışır.

Bir MCP sunucusunda kullanıcı başına yetkilendirme için OAuth kimlik geçişi de kullanabilirsiniz.

Aşağıdaki kod aracıyı önceki adımdan güncelleştirir, böylece MCP aracı yapılandırılmış bir girişten yetkilendirme üst bilgisini okur.

from azure.ai.projects.models import StructuredInputDefinition

# Reference the token as a placeholder in the header
mcp_kb_tool = MCPTool(
    server_label="knowledge-base",
    server_url=mcp_endpoint,
    require_approval="never",
    allowed_tools=["knowledge_base_retrieve"],
    project_connection_id=project_connection_name,
    headers={
        "x-ms-query-source-authorization": "{{search_auth_token}}"
    }
)

# Declare the structured input so the caller can supply the token per request
agent = project_client.agents.create_version(
    agent_name=agent_name,
    definition=PromptAgentDefinition(
        model=agent_model,
        instructions=instructions,
        tools=[mcp_kb_tool],
        structured_inputs={
            "search_auth_token": StructuredInputDefinition(
                description="Per-user Azure AI Search bearer token",
                required=True,
                schema={"type": "string"},
            )
        }
    )
)

print(f"AI agent '{agent_name}' created or updated successfully")

Aracıyı çağırdığınızda, Azure Yapay Zeka Arama belirtecini structured_inputs içinde sağlayın. Bu örnek, geçerli credentialiçinden bir belirteci çözümler. Çok kullanıcılı bir uygulama için, bunun yerine oturum açan her kullanıcının belirtecini geçirin. Örneğin, geri getirme altyapısının sonuçları o kullanıcı için filtreleyebilmesi amacıyla, on-behalf-of akışı aracılığıyla alınan bir belirteç kullanın.

# Resolve an Azure AI Search token from the current credential (use a per-user token in production)
from azure.identity import get_bearer_token_provider

search_token = get_bearer_token_provider(credential, "https://search.azure.com/.default")()

openai_client = project_client.get_openai_client()
conversation = openai_client.conversations.create()

response = openai_client.responses.create(
    conversation=conversation.id,
    tool_choice="required",
    input="{user_query}",
    extra_body={
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"search_auth_token": search_token},
    },
)

print(f"Response: {response.output_text}")

Temsilciyle sohbet edin

İstemci uygulamanız, aracıyla etkileşimde Azure OpenAI'deki Konuşmalar ve Responses API'lerini kullanır.

Aşağıdaki kod bir konuşma oluşturur ve tipik bir sohbet deneyimine benzeyen kullanıcı iletilerini aracıya geçirir. Ajans, MCP aracılığıyla bilgi bankanızı ne zaman çağıracağını belirler ve referanslar içeren doğal dilde bir yanıt döndürür. Ayarı tool_choice="required" , aracının sorguları işlerken her zaman bilgi bankası aracını kullanmasını sağlar.

# Get the OpenAI client for responses and conversations
openai_client = project_client.get_openai_client()

conversation = openai_client.conversations.create()

# Send initial request that will trigger the MCP tool
response = openai_client.responses.create(
    conversation=conversation.id,
    tool_choice="required",
    input="""
        Why do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?
        Why is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?
    """,
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)

print(f"Response: {response.output_text}")

Yanıt aşağıdaki örneğe benzer olmalıdır.

Response: Here are evidence-based explanations to your questions:

---

**1. Why do suburban belts display larger December brightening than urban cores, even though absolute light levels are higher downtown?**

- Suburban belts show a *larger percentage increase* in night brightness during December compared to urban cores, largely because suburban residential areas feature more single-family homes and larger yards, which are typically decorated with holiday lights. These areas start from a lower baseline (less bright overall at night compared to dense urban centers), so the relative change (brightening) is much more noticeable.

- In contrast, the downtown core is already very bright at night due to dense commercial lighting and streetlights. While it also sees a December increase (often 20–30% brighter), the *absolute* change is less striking because it begins at a much higher base of illumination.

- This pattern is observed across U.S. cities, with the phenomenon driven by widespread cultural practices and the suburban landscape’s suitability for holiday lighting displays. The effect is visible in satellite data and was quantified at 20–50% brighter in December, especially in suburbs and city outskirts.

---

**2. Why is the Phoenix nighttime street grid so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?**

- Phoenix’s sharply visible nighttime street grid from space is a result of its urban layout: the city (like many western U.S. cities) was developed using a regular grid system, with extensive and uniform street lighting and strong urban sprawl. The grid pattern, and the dense network of intersecting surface streets, is brightly illuminated, particularly at intersections, commercial areas, and major thoroughfares.

- The interstate highways between midwestern cities, though significant in length and crucial to national infrastructure, traverse sparsely populated rural areas. These stretches typically have very little artificial lighting (due to low traffic volumes at night and cost considerations), making them much less visible in nighttime satellite imagery. Only nodes (cities and towns) along the route show as bright "pearls" in the darkness, while the "strings" (highways) connecting them remain faint or invisible.

- In summary:
  - Urban areas like Phoenix stand out with strong, connected patterns of light due to dense development and extensive lighting.
  - Rural interstates are sparsely lit, and only their endpoints—cities and large towns—generate notable light visible from space.

---

**References**:
- [Holiday Lights increase most dramatically in suburbs, not downtowns: earth_at_night_508_page_176_verbalized, page 160](4:5)
- [Lighting paths and urban grids are visible from space, while rural highways remain dim: earth_at_night_508_page_124_verbalized, page 108](4:3)
- [Phoenix’s grid and surrounding urban structure: earth_at_night_508_page_104_verbalized, page 88](4:1)

Yanıtı inceleme

Aracıdan alınan temel yanıt, bilgi bankasına gönderilen sorgular ve bulunan alıntılar hakkındaki meta verileri içerir. Aracının kullanıcı girişini nasıl işlediğini anlamak için bu meta verileri inceleyebilirsiniz.

response.to_dict()

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Nesneleri tek tek silmek için aşağıdaki kodu da çalıştırabilirsiniz:

# Delete the agent
project_client.agents.delete_version(agent.name, agent.version)
print(f"AI agent '{agent.name}' version '{agent.version}' deleted successfully")

# Delete the knowledge base
index_client.delete_knowledge_base(base_name)
print(f"Knowledge base '{base_name}' deleted successfully")

# Delete the knowledge source
index_client.delete_knowledge_source(knowledge_source=knowledge_source_name)
print(f"Knowledge source '{knowledge_source_name}' deleted successfully.")

# Delete the search index
index_client.delete_index(index_name)
print(f"Index '{index_name}' deleted successfully")

Veri kalitesini geliştirme

Varsayılan olarak, bilgi tabanlarındaki arama sonuçları, ajanlara bağlam sağlamak için iletebileceğiniz tek ve büyük bir dize hâlinde birleştirilir. Azure Yapay Zeka Arama, yüksek kaliteli sonuçlar oluşturmanıza yardımcı olmak için aşağıdaki dizin oluşturma ve ilgi ayarlama özelliklerini sağlar. Bu özellikleri arama dizininde uygulayabilirsiniz ve aramayla ilgili iyileştirmeler, alma yanıtlarının kalitesinde belirgindir.

• Puanlama profilleri yerleşik artırma ölçütleri sağlar. Dizininiz, sorgular bu profille ilişkili alanları içerdiğinde alma altyapısının kullandığı varsayılan bir puanlama profili belirtmelidir.

• Anlamsal yapılandırma gereklidir, ancak hangi alanların önceliklendirildiğini ve derecelendirme için kullanıldığını siz belirlersiniz.

• Düz metin içeriği için, dizin oluşturma sırasında belirteç oluşturmayı denetlemek için çözümleyicileri kullanabilirsiniz.

• Çok modlu veya görüntü içeriği için, LLM tarafından oluşturulan açıklamaların görselleştirilmesi veya dizin oluşturma sırasında beceri kümeleri aracılığıyla klasik OCR ve görüntü analizini kullanabilirsiniz.

Alt sorgu sayısını denetleme

Bilgi bankasındaki alma mantığı eforunu (önizleme) ayarlayarak alt sorgu sayısını denetleyebilirsiniz. Gerekçe belirleme çalışması, sorgu planlaması için en az (LLM işleme yok) ile orta (daha derin arama ve izleme yinelemeleri) arasında değişen LLM işleme düzeyini belirler.

En düşük düzeyde olmayan mantık yürütme çabaları için LLM, aşağıdaki faktörlere göre alt sorgu sayısını belirler:

• Kullanıcı sorgusu
• Sohbet geçmişi
• Anlam dereceleyici giriş kısıtlamaları

Aracıya gönderilen bağlamı kontrol etme

Yanıtlar API'si aracıya ve bilgi bankasına gönderilenleri denetler. Performansı ve ilgi düzeyini iyileştirmek için, mcp aracısına göndermeden önce sohbet geçmişini özetlemek veya filtrelemek için aracı yönergelerini ayarlayın.

Maliyetleri denetleme ve işlemleri sınırlama

Sorgu planıyla ilgili içgörüler için bilgi bankası yanıtlarının etkinlik dizisindeki çıkış belirteçlerine bakın.

Performansı geliştirme

Performansı iyileştirmek ve gecikme süresini azaltmak için aşağıdaki stratejileri göz önünde bulundurun:

• Mesaj dizilerini özetleyin.

• Veya daha hızlı performans gösteren daha küçük bir model kullanın gpt-5-mini .

• Yanıtın boyutunu yönetmek veya maxOutputSize zamana bağlı işleme için alma eyleminde ayarlayınmaxRuntimeInSeconds.

• Dizin oluşturmadan önce büyük belgeleri daha küçük parçalara ayırın. Çıkış bütçesini aşan belgeler , temel alınan sonuçlardan sessizce atlanabilir.

İlgili içerik

• Azure Yapay Zeka Arama'te Agentic retrieval
• Agentik RAG: Azure AI Araması ile bir akıl yürütme alma motoru oluşturun (YouTube videosu)
• Ajan tabanlı alma özelliğine sahip Azure OpenAI tanıtımı