Verbinden einer Foundry IQ Knowledge Base mit dem Foundry Agent Service

• In der übergeordneten Ressource Ihres Projekts benötigen Sie die Rolle " Foundry User ", um auf Modellbereitstellungen zuzugreifen und Agents zu erstellen. Besitzer erhalten diese Rolle automatisch, wenn sie die Ressource erstellen. Andere Benutzer benötigen eine bestimmte Rollenzuweisung. Weitere Informationen finden Sie unter Rollenbasierte Zugriffssteuerung im Foundry-Portal.

  Wichtig

  Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

• Für die übergeordnete Ressource Ihres Projekts benötigen Sie die Rolle Foundry Project Manager, um eine Projektverbindung für die MCP-Authentifizierung zu erstellen, und entweder Foundry User oder Foundry Project Manager, um das MCP-Tool in Agenten zu verwenden.

• (Bedingt) Weisen Sie der übergeordneten Ressource Ihres Projekts die Rolle " Cognitive Services User " der vom System zugewiesenen verwalteten Identität Ihres Suchdiensts zu. Dieser Schritt ist nur erforderlich, wenn Ihre Wissensdatenbank eine LLM angibt. Je nach Konfiguration verwendet die Wissensbasis diese Identität, um die LLM für die Abfrageplanung, Antwortsynthese oder beides aufzurufen. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe einer verwalteten Identität.

• Erstellen Sie in Ihrem Projekt eine vom System zugewiesene verwaltete Identität für Interaktionen mit Azure KI-Suche.

• Weisen Sie in Ihrem Suchdienst der verwalteten Identität Ihres Projekts die Rolle „Suchindexdatenleser“ zu, um schreibgeschützten Zugriff auf Suchindizes zu erhalten. Wenn Ihr Agent Dokumente in Suchindizes schreiben muss, weisen Sie auch die Rolle " Mitwirkender von Suchindexdaten " zu.

• Fügen Sie für indizierte Inhalte mit Zugriffssteuerungslisten (ACCESS Control Lists, ACLs) Berechtigungsmetadatenfelder in Den Suchindex ein und übergeben Sie Benutzertoken über den x-ms-query-source-authorization Header zur Abfragezeit, um Ergebnisse basierend auf der Identität des Benutzers zu filtern. Weitere Informationen finden Sie unter Abfragezeitpunkt-ACL- und RBAC-Implementierung.

• Bei SharePoint-Remote-Wissensquellen übergibt der x-ms-query-source-authorization-Header die Identität des Benutzers, was SharePoint die Durchsetzung von Dokumentberechtigungen zur Abfragezeit ermöglicht. Inhalt wird nicht indexiert. Stattdessen wendet SharePoint Berechtigungen direkt über die Copilot-Abruf-API an. Weitere Informationen finden Sie unter Erstellen einer Remote-SharePoint-Wissensquelle.

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

Verwenden Sie die Azure CLI, um ein Zugriffstoken für Azure Resource Manager abzurufen:

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

Erstellen Sie die Projektverbindung, indem Sie eine PUTAnforderung an Azure Resource Manager erstellen:

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

Rufen Sie ein Zugriffstoken für Microsoft Foundry ab:

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

Erstellen Sie den Agent, indem Sie eine POST Anforderung an den Foundry Agent Service senden:

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

Aktualisieren Sie den Agent aus dem vorherigen Schritt, damit das MCP-Tool seinen Autorisierungsheader aus einer strukturierten Eingabe liest:

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

Wenn Sie den Agent aufrufen, geben Sie ein Azure KI-Suche Token in structured_inputs. In diesem Beispiel wird ein Token aus dem aktuellen credential aufgelöst. Übergeben Sie für eine Mehrbenutzer-App stattdessen das Token jedes angemeldeten Benutzers. Verwenden Sie z. B. ein Token, das über einen On-Behalf-Of-Flow bezogen wurde, damit die Abruf-Engine die Ergebnisse für diesen Benutzer filtern kann.

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

Aktualisieren Sie die Agent-Erstellungsanforderung so, dass das MCP-Tool seinen Autorisierungsheader aus einer strukturierten Eingabe liest:

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

Rufen Sie das Zugriffstoken des angemeldeten Benutzers für Azure KI-Suche ab:

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

Geben Sie das Token structured_inputs an, wenn Sie die POST Anforderung senden, um den Agent aufzurufen:

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

Die Ausgabe sollte der folgenden ähneln (aus Platzgründen abgeschnitten):

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)

Senden Sie eine leere POST Anforderung, um eine Konversationssitzung zu erstellen:

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

{}

Die Antwort enthält eine Unterhaltung id, mit der Sie eine Abfrage an den Agent senden können:

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

Die Antwort enthält Metadaten über die Agentausführung, Toolaufrufe und die generierte Ausgabe. Der relevanteste Teil der Antwort ist das text im content-Feld, das ähnlich wie folgt sein sollte (aus Platzgründen abgeschnitten):

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}