Tutorial: Construa uma solução de busca agentica de ponta a ponta usando o Pesquisa de IA do Azure

Aprenda a criar uma solução inteligente, compatível com MCP, que integre Pesquisa de IA do Azure com o Foundry Agent Service para recuperação agentica. Pode usar esta arquitetura para aplicações conversacionais que requerem raciocínio complexo em grandes domínios de conhecimento, como apoio ao cliente ou resolução de problemas técnica.

Este tutorial utiliza interfaces da API REST em versão de pré-visualização em dois pontos. A base de conhecimento utiliza output_mode e retrieval_reasoning_effort (pré-visualização) para especificar explicitamente a saída extrativa e o raciocínio mínimo, embora geralmente esteja disponível comportamento equivalente. A ligação ao projeto utiliza RemoteTool (pré-visualização) e a identidade gerida do projeto para autenticar no Pesquisa de IA do Azure.

Neste tutorial, tu:

Pré-requisitos

• Um serviço Pesquisa de IA do Azure em qualquer região que forneça recuperação proativa.

• Um projeto e recurso do Microsoft Foundry. Quando cria um projeto, o recurso é criado automaticamente.

• Um modelo de embedding de texto implementado no seu projeto para vetorização em tempo de consulta. Esta solução utiliza text-embedding-3-large.

• Um LLM alocado ao seu projeto, destinado ao agente. Esta solução utiliza gpt-5-mini.

  Os modelos da família GPT-4 estão obsoletos. Para ver as datas de descontinuação e o estado atual no Microsoft Foundry, consulte Calendário de descontinuação dos modelos - Microsoft Foundry.

• Permissão para aceder e gerir recursos do Pesquisa de IA do Azure e Microsoft Foundry. Para mais informações, consulte Configurar acesso.

• Python 3.8 ou posterior.

• Visual Studio Code com as extensões Python e Júpiter.

• O CLI do Azure para autenticação sem chave com Microsoft Entra ID.

Compreenda a solução

Esta solução combina o Pesquisa de IA do Azure e o Microsoft Foundry para criar um pipeline de recuperação de ponta a ponta:

• Pesquisa de IA do Azure aloja a sua base de conhecimento, que trata do planeamento de consultas, execução de consultas e síntese de resultados. Cria-se um índice de pesquisa para armazenar conteúdo, uma fonte de conhecimento que faz referência ao índice e uma base de conhecimento que realiza a recuperação híbrida a partir da fonte de conhecimento.

• Microsoft Foundry aloja as suas implementações de modelos OpenAI do Azure, a ligação de projeto e o agente. Crias uma ligação ao projeto que aponta para o endpoint MCP da tua base de conhecimento, e depois crias um agente que usa a ferramenta MCP para aceder à base de conhecimento.

Um utilizador inicia o processamento de consultas interagindo com uma aplicação cliente, como um chatbot, que liga para o agente. O agente utiliza a ferramenta MCP para orquestrar pedidos para a base de conhecimento e sintetizar respostas. Quando o chatbot liga para o agente, a ferramenta MCP liga à base de conhecimento no Pesquisa de IA do Azure e envia a resposta ao agente e ao chatbot.

Configurar acesso

Antes de começar, certifique-se de que tem permissões para aceder a conteúdos e operações. Recomendamos o Microsoft Entra ID para autenticação e acesso baseado em funções para autorização. Deve ser Proprietário ou Administrador de Acesso ao Utilizador para atribuir funções. Se as funções não forem viáveis, use autenticação baseada em chaves .

Para configurar o acesso para esta solução:

1. Inicie sessão no portal Azure.

2. Ative uma identidade gerida atribuída pelo sistema tanto para o seu serviço de pesquisa como para o seu projeto. Podes fazê-lo na página de Identidade de cada recurso.

3. No seu serviço de pesquisa, ative o acesso baseado em funções e atribua as seguintes funções.

   Função	Cessionário	Finalidade
   Contribuidor do Serviço de Pesquisa	A sua conta de utilizador	Criar objetos
   Contribuidor de Dados do Índice de Pesquisa	A sua conta de utilizador	Carregar dados
   Leitor de Dados do Índice de Pesquisa	A sua conta de utilizador e identidade gerida pelo projeto	Leia conteúdo indexado

4. No recurso principal do seu projeto, atribua as seguintes funções.

   Função	Cessionário	Finalidade
   Utilizador do Foundry	A sua conta de utilizador	Aceder a implementações de modelos e criar agentes
   Gestor de Projeto da Fundição	A sua conta de utilizador	Criar ligação ao projeto e usar a ferramenta MCP nos agentes
   Utilizador de Serviços Cognitivos	Identidade gerida do serviço de pesquisa	Aceder à base de conhecimento

Configura o teu ambiente

1. Crie uma pasta com o nome tutorial-agentic-retrieval do seu sistema local.

2. Abra a pasta no Visual Studio Code.

3. Selecione View>Command Palette e depois selecione Python: Criar Ambiente. Siga as instruções para criar um ambiente virtual.

4. Selecione Terminal>New Terminal.

5. Instale os pacotes necessários.

   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. Crie um ficheiro com nome .env na tutorial-agentic-retrieval pasta.

7. Adicione as seguintes variáveis ao .env ficheiro, substituindo os valores provisórios pelos seus próprios.

   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
   

   Pode encontrar os endpoints e o ID do recurso no portal Azure:

   • AZURE_SEARCH_ENDPOINT está na página de Visão Geral do seu serviço de pesquisa.

   • PROJECT_ENDPOINT está na página Endpoints do seu projeto.

   • PROJECT_RESOURCE_ID está na página de Propriedades do seu projeto.

   • AZURE_OPENAI_ENDPOINT está na página de Endpoints do recurso pai do seu projeto.

8. Para autenticação sem chave com o Microsoft Entra ID, inicie sessão na sua conta Azure. Se tiver várias subscrições, selecione aquela que contém os seus recursos do Pesquisa de IA do Azure e do Microsoft Foundry.

   az login
   

9. Crie um ficheiro com nome tutorial.ipynb na tutorial-agentic-retrieval pasta. Adiciona células de código a este ficheiro na secção seguinte.

Constrói a solução

Nesta secção, cria os componentes da solução de recuperação agentica. Adicione cada excerto de código a uma célula de código separada no tutorial.ipynb caderno e execute as células sequencialmente.

Os passos desta secção incluem:

1. Ligações de carga
2. Criar um índice de pesquisa
3. Carregar documentos para o índice
4. Criar uma fonte de conhecimento
5. Crie uma base de conhecimento
6. Configurar um cliente de projeto
7. Criar uma ligação ao projeto
8. Crie um agente com a ferramenta MCP
9. Converse com o agente
10. Limpar recursos

Conexões de carga elétrica

O código seguinte carrega as variáveis de ambiente do seu ficheiro .env e estabelece ligações ao Pesquisa de IA do Azure e ao 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']

Criar um índice de pesquisa

No Pesquisa de IA do Azure, um índice é uma coleção estruturada de dados. O código seguinte cria um índice para armazenar conteúdo pesquisável na sua base de conhecimento.

O esquema índice contém campos para identificação de documentos e conteúdo da página, embeddings e números. O esquema inclui também configurações para classificação semântica e pesquisa vetorial, que utiliza a sua text-embedding-3-large implementação para vetorizar texto e corresponder documentos com base na similaridade semântica.

Para mais informações sobre este passo, veja Criar um índice para recuperação agentica em Pesquisa de IA do Azure.

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

Carregar documentos para o índice

Atualmente, o índice está vazio. O código seguinte preenche o índice com documentos JSON do e-book Earth at Night da NASA. Conforme exigido pelo Pesquisa de IA do Azure, cada documento cumpre os campos e tipos de dados definidos no esquema do índice.

Para mais informações sobre esta etapa, consulte Empurrar dados para um índice.

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

Criar uma fonte de conhecimento

Uma fonte de conhecimento é uma referência reutilizável a dados fonte. O código seguinte cria uma fonte de conhecimento que direciona o índice que criou anteriormente.

source_data_fields especifica quais os campos de índice incluídos nas referências de citação. Este exemplo inclui apenas campos legíveis por humanos para evitar incorporações extensas e ininterpretáveis nas respostas.

Para mais informações sobre este passo, consulte Criar uma fonte de conhecimento de índice de pesquisa.

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

Crie uma base de conhecimento

O código seguinte cria uma base de conhecimento que orquestra a recuperação por agente da sua fonte de conhecimento. O código também armazena o endpoint MCP da base de conhecimento, que o seu agente usará para aceder à base de conhecimento.

Para integração com o Foundry Agent Service, a base de conhecimento está configurada com os seguintes parâmetros:

• output_mode (pré-visualização) está configurado para dados extrativos, o que fornece ao agente conteúdo literal, não processado, para contextualização e raciocínio. O modo alternativo, síntese de respostas, devolve respostas pré-geradas que limitam a capacidade do agente de raciocinar sobre o conteúdo de origem.

• retrieval_reasoning_effort (pré-visualização) está configurado para um esforço mínimo, o que dispensa o planeamento de consultas baseado em LLM para reduzir os custos e a latência. Para outros esforços de raciocínio, a base de conhecimento utiliza um LLM para reformular as consultas dos utilizadores antes de serem recuperadas.

Para mais informações sobre este passo, consulte Criar uma base de conhecimento em Pesquisa de IA do Azure.

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"

Configurar um cliente de projeto

Use AIProjectClient para criar uma ligação de cliente ao seu projeto Microsoft Foundry. O teu projeto pode ainda não ter agentes, mas se já completaste este tutorial, o agente está listado aqui.

from azure.ai.projects import AIProjectClient

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

list(project_client.agents.list())

Criar uma ligação ao projeto

O código seguinte cria uma RemoteTool ligação de projeto (pré-visualização) no Microsoft Foundry que aponta para o ponto final MCP da sua base de conhecimento. Esta ligação utiliza a identidade gerida do seu projeto para autenticar-se no Pesquisa de IA do Azure.

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

Crie um agente com a ferramenta MCP

O código seguinte cria um agente configurado com a ferramenta MCP. Quando o agente recebe uma consulta do utilizador, pode ligar à sua base de conhecimento através da ferramenta MCP para recuperar conteúdo relevante e fundamentar a resposta.

A definição do agente inclui instruções que especificam o seu comportamento e a ligação ao projeto que criou anteriormente. Com base nos nossos experimentos, estas instruções são eficazes para maximizar a precisão das invocações da base de conhecimento e garantir a formatação correta das citações.

Para mais informações sobre este passo, consulte Quickstart: Criar um novo 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")

(Opcional) Aplicar permissões com cabeçalhos em cada pedido

Se alguma das suas fontes de conhecimento contiver conteúdo protegido por permissão, o motor de recuperação pode filtrar os resultados para que cada utilizador veja apenas os documentos a que está autorizado a aceder. Para permitir esta filtragem, encaminhe o token de identidade do utilizador iniciado para o x-ms-query-source-authorization cabeçalho da ligação à ferramenta MCP. Sem o token, as fontes com permissões devolvem resultados sem filtro. Para mais informações, consulte Impor permissões no momento da consulta (pré-visualização).

Para variar os cabeçalhos MCP em cada pedido, por exemplo, ao passar o token de um utilizador diferente em cada chamada, declare uma entrada estruturada na definição do agente e refira-a como {{placeholder}} no headers da ferramenta. O chamador fornece o valor de cada invocação. Esta abordagem funciona para ferramentas MCP ligadas a uma ligação de projeto.

Para autorização por utilizador contra um servidor MCP, também pode usar o passthrough de identidade OAuth.

O código seguinte atualiza o agente do passo anterior para que a ferramenta MCP leia o seu cabeçalho de autorização a partir de uma entrada estruturada.

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 invocar o agente, forneça um token Pesquisa de IA do Azure em structured_inputs. Este exemplo resolve um token a partir do atual credential. Para uma aplicação multiutilizador, passa o token de cada utilizador iniciado em vez disso. Por exemplo, use um token obtido através de um fluxo on-behalf-of para que o motor de recuperação possa filtrar resultados para esse utilizador.

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

Converse com o agente

A tua aplicação cliente usa as APIs Conversations e Responses da Azure OpenAI para interagir com o agente.

O código seguinte cria uma conversa e transmite mensagens do utilizador ao agente, assemelhando-se a uma experiência típica de chat. O agente determina quando chamar a sua base de conhecimento através da ferramenta MCP e devolve uma resposta em linguagem natural com referências. A definição tool_choice="required" garante que o agente utiliza sempre a ferramenta de base de conhecimento ao processar consultas.

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

A resposta deve ser semelhante ao exemplo a seguir.

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)

Verificar a resposta

A resposta subjacente do agente contém metadados sobre as consultas enviadas para a base de conhecimento e as citações encontradas. Pode inspecionar estes metadados para perceber como o agente processou a entrada do utilizador.

response.to_dict()

Recursos de limpeza

Quando trabalha com a sua própria subscrição, é boa ideia terminar um projeto removendo os recursos de que já não precisa. Os recursos que ficam a funcionar podem custar-lhe dinheiro.

No portal Azure, selecione Todos os recursos ou Resource groups no painel esquerdo para encontrar e gerir recursos. Podes eliminar recursos individualmente ou eliminar o grupo de recursos para remover todos os recursos de uma só vez.

Também pode executar o seguinte código para eliminar objetos individuais:

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

Melhorar a qualidade dos dados

Por predefinição, os resultados da pesquisa nas bases de conhecimento são consolidados numa única cadeia de texto, que pode ser passada aos agentes para lhes fornecer contexto. O Pesquisa de IA do Azure oferece as seguintes funcionalidades de indexação e ajuste de relevância para o ajudar a gerar resultados de alta qualidade. Pode implementar estas funcionalidades no índice de pesquisa, e as melhorias na relevância da pesquisa são evidentes na qualidade das respostas de recuperação.

• Os perfis de pontuação fornecem critérios de reforço incorporados. O seu índice deve especificar um perfil de pontuação predefinido, que o motor de recuperação utiliza quando as consultas incluem campos associados a esse perfil.

• É necessária uma configuração semântica , mas tu determinas quais os campos que são priorizados e usados para o ranking.

• Para conteúdo em texto simples, pode usar analisadores para controlar a tokenização durante a indexação.

• Para conteúdo multimodal ou de imagem, pode usar verbalização de imagens para descrições das suas imagens geradas por LLM ou OCR clássico e análise de imagens através de conjuntos de habilidades durante a indexação.

Controlar o número de subconsultas

Pode controlar o número de subconsultas definindo o esforço de raciocínio de recuperação (pré-visualização) na base de conhecimento. O esforço de raciocínio determina o nível de processamento de LLM para o planeamento de consultas, variando desde o mínimo (sem processamento LLM) até o médio (pesquisa mais profunda e iterações de seguimento).

Para esforços de raciocínio não mínimo, o LLM determina o número de subconsultas com base nos seguintes fatores:

• Consulta do utilizador
• Histórico de chat
• Restrições semânticas de entrada do ranker

Controla o contexto enviado ao agente

A API Respostas controla o que é enviado ao agente e à base de conhecimento. Para otimizar o desempenho e a relevância, ajuste as instruções do agente para resumir ou filtrar o histórico de chat antes de o enviar para a ferramenta MCP.

Controlo de custos e limitação de operações

Para obter informações sobre o plano de consulta, consulte os tokens de saída na matriz de atividades das respostas da base de conhecimento.

Melhorar o desempenho

Para otimizar o desempenho e reduzir a latência, considere as seguintes estratégias:

• Resume os tópicos de mensagens.

• Utilize gpt-5-mini ou um modelo menor que tenha um desempenho mais rápido.

• Defina maxOutputSize na ação de recuperar para governar o tamanho da resposta ou maxRuntimeInSeconds para processamento temporal.

• Divida documentos grandes em pedaços mais pequenos antes de indexar. Documentos que excedam o orçamento de produção podem ser silenciosamente omitidos dos resultados fundamentados.

Conteúdo relacionado

• Busca de agência no Pesquisa de IA do Azure
• Agentic RAG: Constrói um motor de recuperação de raciocínio com Pesquisa de IA do Azure (vídeo do YouTube)
• Demo do Azure OpenAI com recuperação de agentes