Esercitazione: Costruire una soluzione di recupero agentico end-to-end con Azure AI Search

Scopri come creare una soluzione intelligente abilitata per MCP che integra Azure AI Search con il Foundry Agent Service per recupero agentico. È possibile usare questa architettura per applicazioni conversazionali che richiedono un ragionamento complesso su domini di conoscenze di grandi dimensioni, ad esempio il supporto tecnico o la risoluzione dei problemi tecnici.

Questa esercitazione usa le superfici dell'API REST di anteprima in due posizioni. La Knowledge Base usa output_mode e retrieval_reasoning_effort (anteprima) per specificare in modo esplicito l'output estratto e il ragionamento minimo, anche se il comportamento equivalente è disponibile a livello generale. La connessione del progetto utilizza RemoteTool (anteprima) e l'identità gestita del progetto per autenticarsi ad Azure AI Search.

In questa esercitazione:

Prerequisiti

• Un servizio Azure AI Search, in qualsiasi area che fornisce il recupero agentico.

• Un progetto Microsoft Foundry e risorsa. Quando si crea un progetto, la risorsa viene creata automaticamente.

• Modello di incorporamento di testo distribuito nel progetto per la vettorizzazione in fase di query. Questa soluzione usa text-embedding-3-large.

• Un LLM distribuito nel progetto per l'agente. Questa soluzione usa gpt-5-mini.

  I modelli della famiglia GPT-4 sono deprecati. Per le date di ritiro e lo stato corrente in Microsoft Foundry, vedere Pianificazione del ritiro del modello - Microsoft Foundry.

• Autorizzazione per accedere e gestire le risorse Azure AI Search e Microsoft Foundry. Per altre informazioni, vedere Configurare l'accesso.

• Python 3.8 o versione successiva.

• Visual Studio Code con le estensioni Python e Jupyter.

• interfaccia della riga di comando di Azure per l'autenticazione senza chiave con Microsoft Entra ID.

Informazioni sulla soluzione

Questa soluzione combina Azure AI Search e Microsoft Foundry per creare una pipeline di recupero end-to-end:

• Azure AI Search ospita la Knowledge Base, che gestisce la pianificazione delle query, l'esecuzione di query e la sintesi dei risultati. Si crea un indice di ricerca per archiviare il contenuto, una fonte di conoscenza che fa riferimento all'indice e una base di conoscenza che esegue il recupero ibrido dalla fonte di conoscenza.

• Microsoft Foundry ospita le distribuzioni di modelli OpenAI Azure, la connessione al progetto e l'agente. Si crea una connessione di progetto che punta all'endpoint MCP della knowledge base e quindi si crea un agente che usa lo strumento MCP per accedere alla Knowledge Base.

Un utente avvia l'elaborazione delle query interagendo con un'app client, ad esempio un chatbot, che chiama l'agente. L'agente usa lo strumento MCP per orchestrare le richieste alla Knowledge Base e sintetizzare le risposte. Quando il chatbot chiama l'agente, lo strumento MCP chiama la Knowledge Base in Azure AI Search e invia la risposta all'agente e al chatbot.

Configurare l'accesso

Prima di iniziare, assicurarsi di disporre delle autorizzazioni per accedere al contenuto e alle operazioni. È consigliabile Microsoft Entra ID per l'autenticazione e l'accesso basato sui ruoli per l'autorizzazione. Per assegnare i ruoli, è necessario essere proprietario o amministratore accesso utenti . Se i ruoli non sono fattibili, usare invece l'autenticazione basata su chiave .

Per configurare l'accesso per questa soluzione:

1. Accedere al portale Azure.

2. Abilitare un'identità gestita assegnata dal sistema sia per il servizio di ricerca che per il progetto. È possibile farlo nella pagina Identità di ogni risorsa.

3. Nel servizio di ricerca abilitare l'accesso in base al ruolo e assegnare i ruoli seguenti.

   Ruolo	Assegnatario	Scopo
   Collaboratore servizio di ricerca	Account utente	Creare oggetti
   Collaboratore ai dati dell'indice di ricerca	Account utente	Caricare i dati
   Lettore di dati dell'indice di ricerca	Account utente e identità gestita del progetto	Leggere il contenuto indicizzato

4. Nella risorsa padre del progetto assegnare i ruoli seguenti.

   Ruolo	Assegnatario	Scopo
   Utente Foundry	Account utente	Accedere alle distribuzioni del modello e creare agenti
   Responsabile di progetto Foundry	Account utente	Creare una connessione al progetto e usare lo strumento MCP negli agenti
   Utente di Servizi cognitivi	Identità gestita del servizio di ricerca	Accedere alla Knowledge Base

Configurare l'ambiente

1. Creare una cartella denominata tutorial-agentic-retrieval nel sistema locale.

2. Aprire la cartella in Visual Studio Code.

3. Selezionare View>Comand Palette e quindi selezionare Python: Create Environment. Seguire le istruzioni per creare un ambiente virtuale.

4. Selezionare Terminale>Nuovo terminale.

5. Installare i pacchetti necessari.

   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. Creare un file denominato .env nella tutorial-agentic-retrieval cartella .

7. Aggiungere le variabili seguenti al .env file, sostituendo i valori segnaposto con i propri.

   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
   

   Gli endpoint e l'ID risorsa sono disponibili nel portale di Azure:

   • AZURE_SEARCH_ENDPOINT è disponibile nella pagina Panoramica del servizio di ricerca.

   • PROJECT_ENDPOINT si trova nella pagina Endpoint del progetto.

   • PROJECT_RESOURCE_ID si trova nella pagina Proprietà del progetto.

   • AZURE_OPENAI_ENDPOINT si trova nella pagina Endpoint della risorsa padre del progetto.

8. Per l'autenticazione senza chiave con Microsoft Entra ID, accedere all'account Azure. Se sono presenti più sottoscrizioni, selezionare quella che contiene le risorse Azure AI Search e Microsoft Foundry.

   az login
   

9. Creare un file denominato tutorial.ipynb nella tutorial-agentic-retrieval cartella . Aggiungere celle di codice a questo file nella sezione successiva.

Compilare la soluzione

In questa sezione vengono creati i componenti della soluzione di recupero agentico. Aggiungere ogni frammento di codice a una cella di codice separata nel tutorial.ipynb notebook ed eseguire le celle in sequenza.

I passaggi descritti in questa sezione includono:

1. Caricare le connessioni
2. Creare un indice di ricerca
3. Caricare documenti nell'indice
4. Creare una fonte di conoscenza
5. Creare una knowledge base
6. Configurare un client di progetto
7. Creare una connessione al progetto
8. Creare un agente con lo strumento MCP
9. Chat con l'agente
10. Pulire le risorse

Caricare le connessioni

Il codice seguente carica le variabili di ambiente dal file .env e stabilisce le connessioni a Azure AI Search e Microsoft Foundry.

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']

Creare un indice di ricerca

In Azure AI Search, un indice è una raccolta strutturata di dati. Il codice seguente crea un indice per archiviare il contenuto ricercabile per la knowledge base.

Lo schema dell'indice contiene campi per l'identificazione dei documenti e il contenuto della pagina, gli incorporamenti e i numeri. Lo schema include anche configurazioni per la classificazione semantica e la ricerca vettoriale, che usa la text-embedding-3-large distribuzione per vettorizzare il testo e associare i documenti in base alla somiglianza semantica.

Per altre informazioni su questo passaggio, vedere Creare un indice per il recupero agentico in Azure AI Search.

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

Caricare documenti nell'indice

Attualmente, l'indice è vuoto. Il codice seguente popola l'indice con i documenti JSON di NASA's Earth at Night. Come richiesto da Azure AI Search, ogni documento è conforme ai campi e ai tipi di dati definiti nello schema dell'indice.

Per altre informazioni su questo passaggio, vedere Push di dati in un indice.

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

Creare una fonte di conoscenza

Una fonte di conoscenza è un riferimento riutilizzabile ai dati di origine. Il codice seguente crea un'origine delle conoscenze destinata all'indice creato in precedenza.

source_data_fields specifica i campi di indice inclusi nei riferimenti di citazione. Questo esempio include solo campi leggibili per evitare incorporamenti lunghi e non interpretabili nelle risposte.

Per altre informazioni su questo passaggio, vedere Creare una fonte di conoscenza per l'indice di ricerca.

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

Creare una base di conoscenza

Il codice seguente crea una knowledge base che orchestra il recupero attraverso agenti dalla tua origine di conoscenza. Il codice archivia anche l'endpoint MCP della Knowledge Base, che verrà usato dall'agente per accedere alla Knowledge Base.

Per l'integrazione con il servizio Foundry Agent, la Knowledge Base viene configurata con i parametri seguenti:

• output_mode (anteprima) è impostato su dati estrattivi, fornendo all'agente un contenuto letterale e non elaborato per il fondamento e il ragionamento. La modalità alternativa, la sintesi delle risposte, restituisce risposte pregenerate che limitano la capacità dell'agente di ragionare sul contenuto di origine.

• retrieval_reasoning_effort (anteprima) è impostato su sforzo minimo, che aggira la pianificazione delle query basata su LLM per ridurre i costi e la latenza. Per altre attività di ragionamento, la Knowledge Base usa un LLM per riformulare le query utente prima del recupero.

Per altre informazioni su questo passaggio, vedere Creare una knowledge base in Azure AI Search.

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"

Configurare un client di progetto

Usare AIProjectClient per creare una connessione client al progetto Foundry Microsoft. Il progetto potrebbe non contenere ancora agenti, ma se è già stata completata questa esercitazione, l'agente è elencato qui.

from azure.ai.projects import AIProjectClient

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

list(project_client.agents.list())

Creare una connessione al progetto

Il codice seguente crea una connessione di progetto RemoteTool (anteprima) in Microsoft Foundry che punta all'endpoint MCP della base di conoscenza. Questa connessione usa l'identità gestita del progetto per eseguire l'autenticazione a Azure AI Search.

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

Creare un agente con lo strumento MCP

Il codice seguente crea un agente configurato con lo strumento MCP. Quando l'agente riceve una richiesta dell'utente, può chiamare la base di conoscenza tramite lo strumento MCP per recuperare il contenuto pertinente per la contestualizzazione della risposta.

La definizione dell'agente include istruzioni che specificano il comportamento e la connessione al progetto creata in precedenza. In base agli esperimenti, queste istruzioni sono efficaci per massimizzare l'accuratezza delle chiamate della Knowledge Base e garantire una corretta formattazione delle citazioni.

Per altre informazioni su questo passaggio, vedere Avvio rapido: Creare un nuovo agente.

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

(Facoltativo) Applicare le autorizzazioni con intestazioni per richiesta

Se una delle origini conoscenze contiene contenuto protetto da autorizzazioni, il motore di recupero può filtrare i risultati in modo che ogni utente veda solo i documenti a cui è autorizzato ad accedere. Per abilitare questo filtro, inoltrare il token di identità dell'utente connesso nell'intestazione x-ms-query-source-authorization della connessione dello strumento MCP. Senza il token, le fonti abilitate dalle autorizzazioni restituiscono risultati senza filtro. Per altre informazioni, vedere Applicare le autorizzazioni in fase di query (anteprima).

Per variare le intestazioni MCP per ogni richiesta, ad esempio per passare il token di un utente diverso a ogni chiamata, dichiara un input strutturato nella definizione dell'agente e facci riferimento come headers nel {{placeholder}} dello strumento. Il chiamante fornisce il valore per ogni chiamata. Questo approccio funziona per gli strumenti MCP associati a una connessione di progetto.

Per l'autorizzazione per utente su un server MCP, è anche possibile usare il pass-through dell'identità OAuth.

Il codice seguente aggiorna l'agente dal passaggio precedente in modo che lo strumento MCP legga l'intestazione di autorizzazione da un input strutturato.

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

Quando si richiama l'agente, specificare un token Azure AI Search in structured_inputs. Questo esempio risolve un token a partire dall'elemento corrente credential. Per un'app multiutente, passare invece il token di ogni utente connesso. Ad esempio, utilizza un token ottenuto tramite un flusso on-behalf-of in modo che il motore di recupero dati possa filtrare i risultati per quell’utente.

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

Chat con l'agente

L'app client usa le API Conversations e Responses da Azure OpenAI per interagire con l'agente.

Il codice seguente crea una conversazione e passa i messaggi utente all'agente, simile a un'esperienza di chat tipica. L'agente determina quando chiamare la knowledge base tramite lo strumento MCP e restituisce una risposta in linguaggio naturale con riferimenti. L'impostazione tool_choice="required" garantisce che l'agente usi sempre lo strumento knowledge base durante l'elaborazione delle query.

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

La risposta dovrebbe essere simile all'esempio seguente.

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)

Esaminare la risposta

La risposta sottostante dell'agente contiene i metadati relativi alle query inviate alla Knowledge Base e alle citazioni trovate. È possibile esaminare questi metadati per comprendere come l'agente ha elaborato l'input dell'utente.

response.to_dict()

Pulire le risorse

Quando si lavora nella propria sottoscrizione, è consigliabile completare un progetto rimuovendo le risorse non più necessarie. Le risorse che rimangono in esecuzione hanno un costo.

Nel portale di Azure selezionare Tutte le risorse o Gruppi di risorse dal riquadro sinistro per trovare e gestire le risorse. È possibile eliminare le risorse singolarmente o eliminare il gruppo di risorse per rimuovere tutte le risorse contemporaneamente.

È anche possibile eseguire il codice seguente per eliminare singoli oggetti:

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

Migliorare la qualità dei dati

Per impostazione predefinita, i risultati della ricerca nelle basi di conoscenza vengono consolidati in un’unica ampia stringa che è possibile passare agli agenti per fornire contesto. Azure AI Search fornisce le funzionalità di indicizzazione e ottimizzazione della pertinenza seguenti per generare risultati di alta qualità. È possibile implementare queste funzionalità nell'indice di ricerca e i miglioramenti nella pertinenza della ricerca sono evidenti nella qualità delle risposte di recupero.

• I profili di scoring forniscono criteri di potenziamento predefiniti. L'indice deve specificare un profilo di punteggio predefinito, che il motore di recupero usa quando le query includono campi associati a tale profilo.

• La configurazione semantica è obbligatoria, ma si determinano quali campi sono classificati in ordine di priorità e usati per la classificazione.

• Per il contenuto di testo normale, è possibile usare analizzatori per controllare la tokenizzazione durante l'indicizzazione.

• Per il contenuto multimodale o di immagini, è possibile usare la verbalizzazione delle immagini per le descrizioni generate da LLM delle immagini o l'analisi OCR classica e dell'immagine tramite set di competenze durante l'indicizzazione.

Controllare il numero di sottoquery

È possibile controllare il numero di sottoquery impostando lo sforzo di ragionamento del recupero (anteprima) nella Knowledge Base. Lo sforzo di ragionamento determina il livello di elaborazione LLM per la pianificazione delle query, dal minimo (nessuna elaborazione LLM) a media (ricerca più approfondita e iterazioni di completamento).

Per gli sforzi di ragionamento non minimi, l'LLM determina il numero di sottoquery in base ai fattori seguenti:

• Query utente
• Cronologia chat
• Vincoli di input del ranker semantico

Controllare il contesto inviato all'agente

L'API Risposte controlla gli elementi inviati all'agente e alla Knowledge Base. Per ottimizzare le prestazioni e la pertinenza, modificare le istruzioni dell'agente per riepilogare o filtrare la cronologia delle chat prima di inviarla allo strumento MCP.

Controllare i costi e limitare le operazioni

Per informazioni dettagliate sul piano di query, esaminare i token di output nella matrice di attività delle risposte della Knowledge Base.

Migliorare le prestazioni

Per ottimizzare le prestazioni e ridurre la latenza, considerare le strategie seguenti:

• Riepilogare i thread di messaggio.

• Usare gpt-5-mini o un modello più piccolo con prestazioni più veloci.

• Impostare maxOutputSize sull' azione di recupero per gestire le dimensioni della risposta o maxRuntimeInSeconds per l'elaborazione vincolata al tempo.

• Suddividere documenti di grandi dimensioni in parti più piccole prima dell'indicizzazione. I documenti che superano il budget di produzione possono essere omessi silenziosamente dai risultati effettivi.

Contenuto correlato

• Recupero agentico in Azure AI Search
• Agentic RAG: Creare un motore di recupero di ragionamento con Azure AI Search (video di YouTube)
• Demo Azure OpenAI con recupero agentico