Connettere una knowledge base di IQ Foundry al Servizio agenti Foundry

• Nella risorsa padre del progetto, è necessario il ruolo Utente Foundry per accedere alle distribuzioni dei modelli e creare agenti. I proprietari ottengono automaticamente questo ruolo quando creano la risorsa. Altri utenti necessitano di un'assegnazione di ruolo specifica. Per altre informazioni, vedere Controllo degli accessi in base al ruolo nel portale di Foundry.

  Importante

  I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

• Nella risorsa padre del progetto, è necessario il ruolo Foundry Project Manager per creare una connessione di progetto per l'autenticazione MCP e il ruolo Foundry User oppure Foundry Project Manager per usare lo strumento MCP negli agenti.

• (Facoltativo) Nella risorsa padre del tuo progetto, assegna il ruolo Utente di Servizi cognitivi all'identità gestita assegnata dal sistema del tuo servizio di ricerca. Questo passaggio è obbligatorio solo se la Knowledge Base specifica un LLM. A seconda della configurazione, la Knowledge Base usa questa identità per chiamare LLM per la pianificazione delle query, la sintesi delle risposte o entrambi. Per altre informazioni, vedere Connettersi a Azure AI Search usando un'identità gestita.

• Nel progetto creare un'identità gestita assegnata dal sistema per le interazioni con Azure AI Search.

• Nel servizio di ricerca, assegnare il ruolo Search Index Data Reader all'identità gestita del progetto per l'accesso in sola lettura agli indici di ricerca. Se l'agente deve scrivere documenti per eseguire ricerche negli indici, assegnare anche il ruolo Collaboratore ai dati dell'indice di ricerca .

• Per il contenuto indicizzato con elenchi di controllo di accesso (ACL), includere i campi dei metadati delle autorizzazioni nell'indice di ricerca e passare i token utente tramite l'intestazione x-ms-query-source-authorization in fase di query per filtrare i risultati in base all'identità dell'utente. Per ulteriori informazioni, consultare l'applicazione di ACL e RBAC durante la fase di interrogazione.

• Per le fonti di conoscenza remote di SharePoint, l'intestazione x-ms-query-source-authorization passa l'identità dell'utente, consentendo a SharePoint di applicare le autorizzazioni ai documenti durante le query. Il contenuto non è indicizzato. Al contrario, SharePoint applica le autorizzazioni direttamente tramite l'API di recupero Copilot. Per ulteriori informazioni, vedere Creare un'origine di conoscenza SharePoint remota.

import requests
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Provide connection details
credential = DefaultAzureCredential()
project_resource_id = "{project_resource_id}" # e.g. /subscriptions/{subscription}/resourceGroups/{resource_group}/providers/Microsoft.CognitiveServices/accounts/{account_name}/projects/{project_name}
project_connection_name = "{project_connection_name}"
mcp_endpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2026-08-01-preview" # This endpoint enables the MCP connection between the agent and knowledge base

# Get bearer token for authentication
bearer_token_provider = get_bearer_token_provider(credential, "https://management.azure.com/.default")
headers = {
  "Authorization": f"Bearer {bearer_token_provider()}",
}

# Create project connection
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.")

Usare il interfaccia della riga di comando di Azure per ottenere un token di accesso per Azure Resource Manager:

az account get-access-token --scope https://management.azure.com/.default --query accessToken -o tsv

Creare la connessione al progetto effettuando una richiesta di PUT a Azure Resource Manager:

PUT https://management.azure.com/{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview
Authorization: Bearer {management_access_token}
Content-Type: application/json

{
  "name": "{project_connection_name}",
  "type": "Microsoft.MachineLearningServices/workspaces/connections",
  "properties": {
    "authType": "ProjectManagedIdentity",
    "category": "RemoteTool",
    "target": "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2026-08-01-preview", // This endpoint enables the MCP connection between the agent and knowledge base
    "isSharedToAll": true,
    "audience": "https://search.azure.com/",
    "metadata": {
      "ApiType": "Azure"
    }
  }
}

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, MCPTool
from azure.identity import DefaultAzureCredential

# Provide agent configuration details
credential = DefaultAzureCredential()
mcp_endpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2026-08-01-preview"
project_endpoint = "{project_endpoint}" # e.g. https://your-foundry-resource.services.ai.azure.com/api/projects/your-foundry-project
project_connection_name = "{project_connection_name}"
agent_name = "{agent_name}"
agent_model = "{deployed_LLM}" # e.g. gpt-4.1-mini

# Create project client
project_client = AIProjectClient(endpoint = project_endpoint, credential = credential)

# Define agent instructions (see "Optimize agent instructions" section for guidance)
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".
"""

# Create MCP tool with knowledge base connection
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
)

# Create agent with MCP tool
agent = project_client.agents.create_version(
    agent_name = agent_name,
    definition = PromptAgentDefinition(
        model = agent_model,
        instructions = instructions,
        tools = [mcp_kb_tool]
    )
)

print(f"Agent '{agent_name}' created or updated successfully.")

Ottenere un token di accesso per Microsoft Foundry:

az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv

Creare l'agente inviando una POST richiesta al servizio agente Foundry:

POST {project_endpoint}/agents?api-version=v1
Authorization: Bearer {foundry_access_token}
Content-Type: application/json

{
  "name": "{agent_name}",
  "definition": {
    "model": "{deployed_llm}",
    "instructions": "\nYou 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.\nEvery answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`\nIf you cannot find the answer in the provided knowledge base you must respond with \"I don't know\".\n",
    "tools": [
      {
        "server_label": "knowledge-base",
        "server_url": "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2026-08-01-preview",
        "require_approval": "never",
        "allowed_tools": [
          "knowledge_base_retrieve"
        ],
        "project_connection_id": "{project_connection_name}",
        "type": "mcp"
      }
    ],
    "kind": "prompt"
  }
}

Aggiornare 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"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,
    input = "{user_query}",
    extra_body = {
        "agent_reference": {"name": agent.name, "type": "agent_reference"},
        "structured_inputs": {"search_auth_token": search_token},
    },
)

Aggiornare la richiesta di creazione dell'agente in modo che lo strumento MCP legga l'intestazione di autorizzazione da un input strutturato:

POST {project_endpoint}/agents?api-version=v1
Authorization: Bearer {foundry_access_token}
Content-Type: application/json

{
  "name": "{agent_name}",
  "definition": {
    "model": "{deployed_llm}",
    "instructions": "\nYou 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.\nEvery answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`\nIf you cannot find the answer in the provided knowledge base you must respond with \"I don't know\".\n",
    "tools": [
      {
        "server_label": "knowledge-base",
        "server_url": "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2026-08-01-preview",
        "require_approval": "never",
        "allowed_tools": [
          "knowledge_base_retrieve"
        ],
        "project_connection_id": "{project_connection_name}",
        "type": "mcp",
        "headers": {
          "x-ms-query-source-authorization": "{{search_auth_token}}"
        }
      }
    ],
    "structured_inputs": {
      "search_auth_token": {
        "description": "Per-user Azure AI Search bearer token",
        "required": true,
        "schema": { "type": "string" }
      }
    },
    "kind": "prompt"
  }
}

Ottenere il token di accesso dell'utente connesso per Azure AI Search:

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

Specificare il token in structured_inputs quando si invia la POST richiesta per richiamare l'agente:

POST {project_endpoint}/openai/v1/responses
Authorization: Bearer {foundry_access_token}
Content-Type: application/json

{
  "conversation": "{conversation_id}",
  "input": "{user_query}",
  "agent_reference": {
    "type": "agent_reference",
    "name": "{agent_name}"
  },
  "structured_inputs": {
    "search_auth_token": "{search_bearer_token}"
  }
}

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

# Create conversation
conversation = openai_client.conversations.create()

# Send request to trigger the MCP tool
response = openai_client.responses.create(
    conversation = conversation.id,
    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}")

L'output dovrebbe essere simile al seguente (troncato per brevità):

Response: Suburban belts display larger December brightening than urban cores, even 
though absolute light levels are higher downtown, primarily because holiday lights 
increase most dramatically in the suburbs and outskirts of major cities. This is due 
to more yard space and a prevalence of single-family homes in suburban areas...

The Phoenix nighttime street grid is sharply visible from space due to the city's 
layout along a regular grid of city blocks and streets with extensive street lighting...

References:
- earth_at_night_508_page_174, earth_at_night_508_page_176 (Holiday lighting)
- earth_at_night_508_page_104, earth_at_night_508_page_105 (Phoenix grid visibility)

Inviare una richiesta vuota POST per creare una sessione di conversazione:

### Create conversation
POST {project_endpoint}/openai/v1/conversations
Authorization: Bearer {foundry_access_token}
Content-Type: application/json

{}

La risposta include una conversazione id, che è possibile usare per inviare una query all'agente:

### Send request to trigger the MCP tool
POST {project_endpoint}/openai/v1/responses
Authorization: Bearer {foundry_access_token}
Content-Type: application/json

{
    "conversation": "{conversation_id}",
    "input": "\nWhy do suburban belts display larger December brightening than urban cores even though absolute light levels are higher downtown?\nWhy is the Phoenix nighttime street grid is so sharply visible from space, whereas large stretches of the interstate between midwestern cities remain comparatively dim?\n",
    "agent_reference": {
        "type": "agent_reference",
        "name": "{agent_name}"
    }
}

La risposta include i metadati relativi all'esecuzione dell'agente, alle chiamate degli strumenti e all'output generato. La parte più rilevante della risposta è nel text nel campo content, che dovrebbe essere simile al seguente (troncata per brevità):

Suburban belts display larger December brightening in nighttime lights than urban 
cores, primarily because suburban areas have more yard space and single-family homes 
where holiday lighting decorations are more commonly used...

The Phoenix nighttime street grid is sharply visible due to the regular, planned 
layout of city blocks with extensive street lighting, shopping centers, and 
commercial properties along major streets...

References:
- earth_at_night_508_page_174_verbalized, earth_at_night_508_page_176_verbalized
- earth_at_night_508_page_104_verbalized, earth_at_night_508_page_105_verbalized

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

# Delete the project connection (Azure Resource Manager)
import requests
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

credential = DefaultAzureCredential()
project_resource_id = "{project_resource_id}"
project_connection_name = "{project_connection_name}"

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

response = requests.delete(
  f"https://management.azure.com{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview",
  headers=headers,
)
response.raise_for_status()
print(f"Project connection '{project_connection_name}' deleted successfully.")

### Delete the agent
DELETE {project_endpoint}/agents/{agent_name}?api-version=v1
Authorization: Bearer {foundry_access_token}

### Delete the project connection
DELETE https://management.azure.com/{project_resource_id}/connections/{project_connection_name}?api-version=2025-10-01-preview
Authorization: Bearer {management_access_token}