Tutorial: Construcción de una solución de recuperación autónoma de extremo a extremo mediante Búsqueda de Azure AI

Descubra cómo crear una solución inteligente compatible con MCP que integre Búsqueda de Azure AI con Foundry Agent Service para la recuperación de agentes. Puede usar esta arquitectura para aplicaciones conversacionales que requieren un razonamiento complejo en dominios de conocimiento grandes, como el soporte técnico o la solución de problemas técnicos.

En este tutorial se usan superficies de API REST en versión preliminar en dos lugares. La base de conocimiento usa output_mode y retrieval_reasoning_effort (versión preliminar) para especificar explícitamente la salida extractiva y el razonamiento mínimo, aunque el comportamiento equivalente está disponible con carácter general. La conexión del proyecto usa RemoteTool (versión preliminar) y la identidad administrada del proyecto para autenticarse en Búsqueda de Azure AI.

En este tutorial, tú:

Requisitos previos

• Un servicio de Búsqueda de Azure AI en cualquier región que proporcione recuperación mediante agentes.

• Un proyecto Microsoft Foundry y un recurso. Al crear un proyecto, el recurso se crea automáticamente.

• Modelo de inserciones (vectores) de texto implementado en el proyecto para la vectorización en tiempo de consulta. Esta solución usa text-embedding-3-large.

• Un LLM implementado en el proyecto para el agente. Esta solución usa gpt-5-mini.

  Los modelos de familia GPT-4 están en desuso. Para conocer las fechas de retirada y el estado actual en Microsoft Foundry, consulte Programación de retirada de modelos: Microsoft Foundry.

• Permiso para acceder a Búsqueda de Azure AI y administrar los recursos de Microsoft Foundry. Para obtener más información, consulte Configuración del acceso.

• Python 3.8 o posterior.

• Visual Studio Code con las extensiones Python y Jupyter.

• El CLI de Azure para la autenticación sin claves con Microsoft Entra ID.

Descripción de la solución

Esta solución combina Búsqueda de Azure AI y Microsoft Foundry para crear una canalización de recuperación de un extremo a otro:

• Búsqueda de Azure AI hospeda la base de conocimiento, que controla la planificación de consultas, la ejecución de consultas y la síntesis de resultados. Se crea un índice de búsqueda para almacenar contenido, un origen de conocimiento que hace referencia al índice y una base de conocimiento que realiza la recuperación híbrida desde el origen de conocimiento.

• Microsoft Foundry hospeda las implementaciones del modelo openAI de Azure, la conexión del proyecto y el agente. Cree una conexión de proyecto que apunte al punto de conexión de MCP de la base de conocimiento y, a continuación, cree un agente que use la herramienta MCP para acceder a la base de conocimiento.

Un usuario inicia el procesamiento de consultas interactuando con una aplicación cliente, como un bot de chat, que llama al agente. El agente usa la herramienta MCP para orquestar las solicitudes a la base de conocimiento y sintetizar respuestas. Cuando el bot de chat llama al agente, la herramienta MCP llama a la base de conocimiento en Búsqueda de Azure AI y envía la respuesta al agente y al bot de chat.

Configuración del acceso

Antes de empezar, asegúrese de que tiene permisos para acceder al contenido y las operaciones. Se recomienda Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser Propietario o Administrador de acceso de usuarios para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Para configurar el acceso para esta solución:

1. Inicie sesión en el portal Azure.

2. Habilite una identidad administrada asignada por el sistema para el servicio de búsqueda y el proyecto. Puede hacerlo en la página Identidad de cada recurso.

3. En el servicio de búsqueda, habilite el acceso basado en roles y asigne los siguientes roles.

   Rol	Asignado	Propósito
   Colaborador del servicio de búsqueda	Su cuenta de usuario	Crear objetos
   Colaborador de datos del índice de búsqueda	Su cuenta de usuario	Carga de datos
   Lector de datos del índice de búsqueda	La cuenta de usuario y la identidad administrada del proyecto	Leer contenido indexado

4. En el recurso primario del proyecto, asigne los siguientes roles.

   Rol	Asignado	Propósito
   Usuario de Foundry	Su cuenta de usuario	Acceso a implementaciones de modelos y creación de agentes
   Administrador de proyectos de Foundry	Su cuenta de usuario	Creación de una conexión de proyecto y uso de la herramienta MCP en agentes
   Usuario de Cognitive Services	Identidad administrada del servicio de búsqueda	Acceso a la base de conocimiento

Configuración del entorno

1. Cree una carpeta denominada tutorial-agentic-retrieval en el sistema local.

2. Abra la carpeta en Visual Studio Code.

3. Seleccione View>Command Palette y seleccione Python: Create Environment. Siga las indicaciones para crear un entorno virtual.

4. Seleccione Terminal>Nuevo terminal.

5. Instale los paquetes necesarios.

   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. Cree un archivo denominado .env en la tutorial-agentic-retrieval carpeta .

7. Agregue las siguientes variables al .env archivo y reemplace los valores de marcador de posición por los suyos propios.

   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
   

   Puede encontrar los puntos de conexión y el identificador de recurso en el portal de Azure:

   • AZURE_SEARCH_ENDPOINT está en la página Información general del servicio de búsqueda.

   • PROJECT_ENDPOINT está en la página Puntos de conexión del proyecto.

   • PROJECT_RESOURCE_ID está en la página Propiedades del proyecto.

   • AZURE_OPENAI_ENDPOINT está en la página Puntos de conexión del recurso primario del proyecto.

8. Para la autenticación sin claves con Microsoft Entra ID, inicie sesión en la cuenta de Azure. Si tiene varias suscripciones, seleccione la que contiene los recursos de Búsqueda de Azure AI y Microsoft Foundry.

   az login
   

9. Cree un archivo denominado tutorial.ipynb en la tutorial-agentic-retrieval carpeta . Agregue celdas de código a este archivo en la sección siguiente.

Compilación de la solución

En esta sección, cree los componentes de la solución de recuperación agentica. Agregue cada fragmento de código a una celda de código independiente en el tutorial.ipynb cuaderno y ejecute las celdas secuencialmente.

Los pasos de esta sección incluyen:

1. Cargar conexiones
2. Creación de un índice de búsqueda
3. Carga de documentos en el índice
4. Creación de un origen de conocimiento
5. Creación de una base de conocimiento
6. Configuración de un cliente de proyecto
7. Creación de una conexión de proyecto
8. Creación de un agente con la herramienta MCP
9. Chatear con el agente
10. Limpieza de recursos

Cargar conexiones

El siguiente código carga las variables de entorno desde tu archivo .env y establece conexiones a Búsqueda de Azure AI y 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']

Creación de un índice de búsqueda

En Búsqueda de Azure AI, un índice es una colección estructurada de datos. El código siguiente crea un índice para almacenar contenido que se puede buscar en la base de conocimiento.

El esquema de índice contiene campos para la identificación del documento y el contenido de la página, las incrustaciones y los números. El esquema también incluye configuraciones para la clasificación semántica y la búsqueda de vectores, que usa la text-embedding-3-large implementación para vectorizar texto y buscar documentos en función de la similitud semántica.

Para obtener más información sobre este paso, consulte Crear un índice para la recuperación de agentes en Búsqueda de Azure AI.

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

Carga de documentos en el índice

Actualmente, el índice está vacío. El código siguiente rellena el índice con documentos JSON de NASA's Earth at Night. Según lo requiera Búsqueda de Azure AI, cada documento se ajusta a los campos y tipos de datos definidos en el esquema de índice.

Para obtener más información sobre este paso, consulte Inserción de datos en un í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}'")

Creación de un origen de conocimiento

Un origen de conocimiento es una referencia reutilizable a los datos de origen. El código siguiente crea un origen de conocimiento que tiene como destino el índice que creó anteriormente.

source_data_fields especifica los campos de índice que se incluyen en las referencias de cita. En este ejemplo solo se incluyen campos legibles para personas para evitar incrustaciones largas e ininterpretables en las respuestas.

Para obtener más información sobre este paso, consulte Creación de un origen de conocimiento del índice de búsqueda.

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

Creación de una base de conocimiento

Con el siguiente código se crea una base de conocimientos que organiza la recuperación de agentes a través de la fuente de conocimientos. El código también almacena el punto de conexión MCP de la base de conocimiento, que el agente usará para acceder a la base de conocimiento.

Para la integración con foundry Agent Service, la base de conocimiento se configura con los parámetros siguientes:

• output_mode (versión preliminar) está configurado en modo extractivo, lo que proporciona al agente contenido literal y sin procesar como base para fundamentar y razonar. El modo alternativo, síntesis de respuestas, devuelve respuestas pregeneradas que limitan la capacidad del agente para razonar sobre el contenido de origen.

• retrieval_reasoning_effort (versión preliminar) está configurado con un esfuerzo mínimo, lo que omite la planificación de consultas basada en LLM para reducir los costes y la latencia. Para otros esfuerzos de razonamiento, la base de conocimiento utiliza un LLM para reformular las consultas de usuario antes de recuperarlas.

Para obtener más información sobre este paso, consulte Crear una base de conocimiento en Búsqueda de Azure AI.

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"

Configuración de un cliente de proyecto

Use AIProjectClient para crear una conexión de cliente al proyecto de Microsoft Foundry. Es posible que el proyecto aún no contenga ningún agente, pero si ya ha completado este tutorial, el agente aparece aquí.

from azure.ai.projects import AIProjectClient

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

list(project_client.agents.list())

Creación de una conexión de proyecto

El siguiente código crea una conexión de proyecto RemoteTool (versión preliminar) en Microsoft Foundry que apunta al punto de conexión de MCP de su base de conocimiento. Esta conexión usa la identidad administrada del proyecto para autenticarse en Búsqueda de Azure AI.

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

Creación de un agente con la herramienta MCP

El código siguiente crea un agente configurado con la herramienta MCP. Cuando el agente recibe una consulta de usuario, puede llamar a la base de conocimiento a través de la herramienta MCP para recuperar contenido relevante para la base de respuesta.

La definición del agente incluye instrucciones que especifican su comportamiento y la conexión del proyecto que creó anteriormente. En función de nuestros experimentos, estas instrucciones son eficaces para maximizar la precisión de las invocaciones de la base de conocimiento y garantizar un formato de cita adecuado.

Para obtener más información sobre este paso, consulte Inicio rápido: Creación de un nuevo 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 permisos con encabezados en cada solicitud

Si alguno de los orígenes de conocimiento contiene contenido protegido con permisos, el motor de recuperación puede filtrar los resultados para que cada usuario vea solo los documentos a los que está autorizado para acceder. Para habilitar este filtrado, reenvíe el token de identidad del usuario que ha iniciado sesión en el x-ms-query-source-authorization encabezado de la conexión de la herramienta MCP. Sin el token, los orígenes con permisos habilitados devuelven resultados sin filtrar. Para obtener más información, consulte Aplicar permisos en tiempo de consulta (versión preliminar).

Para variar los encabezados MCP en cada solicitud, por ejemplo, para pasar un token de un usuario distinto en cada llamada, declare una entrada estructurada en la definición del agente y haga referencia a ella como {{placeholder}} en el headers de la herramienta. El autor de la llamada proporciona el valor en cada invocación. Este enfoque funciona para las herramientas de MCP enlazadas a una conexión de proyecto.

Para la autorización de cada usuario frente a un servidor MCP, también puede usar el traspaso de identidad de OAuth.

El código siguiente actualiza el agente del paso anterior para que la herramienta MCP lea su encabezado de autorización de una entrada estructurada.

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

Al invocar al agente, proporcione un token de Búsqueda de Azure AI en structured_inputs. En este ejemplo se resuelve un token del objeto actual credential. En el caso de una aplicación multiusuario, pase el token de cada usuario que haya iniciado sesión en su lugar. Por ejemplo, utiliza un token obtenido a través de un flujo en nombre de para que el motor de recuperación pueda filtrar los resultados para ese usuario.

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

Chatear con el agente

La aplicación cliente usa las API Conversations and Responses de Azure OpenAI para interactuar con el agente.

El código siguiente crea una conversación y pasa mensajes de usuario al agente, similar a una experiencia típica de chat. El agente determina cuándo llamar a la base de conocimiento a través de la herramienta MCP y devuelve una respuesta de lenguaje natural con referencias. La configuración tool_choice="required" garantiza que el agente siempre usa la herramienta de base de conocimiento al procesar 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}")

La respuesta debe ser similar al ejemplo siguiente.

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)

Inspección de la respuesta

La respuesta subyacente del agente contiene metadatos sobre las consultas enviadas a la base de conocimiento y las citas encontradas. Puede inspeccionar estos metadatos para comprender cómo el agente procesó la entrada del usuario.

response.to_dict()

Limpieza de recursos

Cuando trabaja en su propia suscripción, es una buena idea finalizar un proyecto quitando los recursos que ya no necesita. Los recursos que se dejan en ejecución pueden costar dinero.

En el portal de Azure, seleccione Todos los recursos o Grupos de recursos en el panel izquierdo para buscar y administrar recursos. Puede eliminar recursos individualmente o eliminar el grupo de recursos para quitar todos los recursos a la vez.

También puede ejecutar el código siguiente para eliminar objetos individuales:

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

Mejora de la calidad de los datos

De forma predeterminada, los resultados de búsqueda de las bases de conocimiento se consolidan en una única cadena de gran tamaño que puede pasarse a los agentes para su fundamentación. Búsqueda de Azure AI proporciona las siguientes características de indexación y ajuste de relevancia para ayudarle a generar resultados de alta calidad. Puede implementar estas características en el índice de búsqueda y las mejoras en la relevancia de búsqueda son evidentes en la calidad de las respuestas de recuperación.

• Los perfiles de puntuación proporcionan criterios de impulso integrados. El índice debe especificar un perfil de puntuación predeterminado, que el motor de recuperación usa cuando las consultas incluyen campos asociados a ese perfil.

• Se requiere la configuración semántica, pero se determinan los campos que se priorizan y se usan para la clasificación.

• Para el contenido de texto sin formato, puede usar analizadores para controlar la tokenización durante la indexación.

• Para contenido multimodal o de imagen, puede usar la verbalización de imágenes para las descripciones generadas por LLM de las imágenes, o el análisis clásico de OCR e imagen a través de conjuntos de aptitudes durante la indexación.

Controlar el número de subconsultas

Puede controlar el número de subconsultas al configurar el nivel de esfuerzo de la lógica de recuperación (versión preliminar) en la base de conocimientos. El esfuerzo de razonamiento determina el nivel de procesamiento de LLM para la planificación de consultas, que varía desde un nivel mínimo (sin procesamiento de LLM) hasta un nivel medio (búsqueda más profunda e iteraciones de seguimiento).

Para los esfuerzos de razonamiento no mínimos, LLM determina el número de subconsultas en función de los siguientes factores:

• Consulta de usuario
• Historial de chats
• Restricciones de entrada del clasificador semántico

Controla el contexto enviado al agente

La API de respuestas controla lo que se envía al agente y a la base de conocimiento. Para optimizar el rendimiento y la relevancia, ajuste las instrucciones del agente para resumir o filtrar el historial de chat antes de enviarlo a la herramienta MCP.

Controlar los costos y limitar las operaciones

Para obtener información sobre el plan de consulta, examine los tokens de salida en la matriz de actividades de las respuestas de la base de conocimiento.

Mejora del rendimiento

Para optimizar el rendimiento y reducir la latencia, tenga en cuenta las siguientes estrategias:

• Resumir hilos de mensajes.

• Use gpt-5-mini o un modelo más pequeño que funcione más rápido.

• Establezca maxOutputSize en la acción de recuperación para controlar el tamaño de la respuesta o maxRuntimeInSeconds para el procesamiento con límite de tiempo.

• Fragmentar documentos grandes en fragmentos más pequeños antes de la indexación. Los documentos que superan el presupuesto de salida se pueden omitir en silencio de los resultados fundamentados.

Contenido relacionado

• Recuperación de agentes en Azure AI Search
• Agentic RAG: Crear un motor de recuperación de razonamiento con Búsqueda de Azure AI (vídeo de YouTube)
• Demostración de Azure OpenAI con recuperación agentiva