Подключение базы знаний Foundry IQ к службе агента Foundry

• Для родительского ресурса вашего проекта вам потребуется роль Azure AI User для доступа к развертываниям моделей и создания агентов. Владельцы автоматически получают эту роль при создании ресурса. Другие пользователи нуждаются в назначении определенной роли. Дополнительные сведения см. в разделе "Управление доступом на основе ролей" на портале Foundry.

• На родительском ресурсе вашего проекта вам нужна роль Azure AI Project Manager для создания подключения проекта для аутентификации MCP и Azure AI User или Azure AI Project Manager для использования средства MCP в агентах.

• В проекте создайте управляемое удостоверение, назначаемое системой, для взаимодействия с Поиск с использованием ИИ Azure.

• В вашей службе поиска назначьте управляему удостоверению проекта роль Читателя данных индекса поиска для доступа к индексам поиска только для чтения.

• Если агенту нужно записывать документы в индексы поиска, также назначьте роль вкладчика данных индекса поиска.

• Для индексированного содержимого со списками управления доступом (ACL) включите поля метаданных разрешений в индекс поиска и передайте маркеры пользователей через x-ms-query-source-authorization заголовок во время запроса, чтобы отфильтровать результаты на основе удостоверения пользователя. Дополнительные сведения см. в статье ACL во время запроса и принудительное применение RBAC.

• Для удалённых источников данных SharePoint заголовок x-ms-query-source-authorization передает идентификацию пользователя, что позволяет SharePoint применять разрешения к документу при выполнении запроса. Содержимое не индексируется. Вместо этого SharePoint применяет разрешения непосредственно через API извлечения Copilot. Дополнительные сведения см. в разделе Создание удаленного источника знаний SharePoint.

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.MachineLearningServices/workspaces/{account_name}/projects/{project_name}
project_connection_name = "{project_connection_name}"
mcp_endpoint = "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2025-11-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.")

Используйте Azure CLI для получения маркера доступа для Azure Resource Manager:

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

Создайте подключение проекта, выполнив запрос PUT для 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=2025-11-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=2025-11-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.")

Получите маркер доступа для Microsoft Foundry:

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

Создайте агента, отправив запрос в службу агентов Foundry POST.

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=2025-11-01-preview",
        "require_approval": "never",
        "allowed_tools": [
          "knowledge_base_retrieve"
        ],
        "project_connection_id": "{project_connection_name}",
        "type": "mcp"
      }
    ],
    "kind": "prompt"
  }
}

from azure.identity import get_bearer_token_provider

# Create MCP tool with SharePoint authorization 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": get_bearer_token_provider(credential, "https://search.azure.com/.default")()
    }
)

Получение токена доступа для Поиск с использованием ИИ Azure:

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

Укажите заголовок и маркер в конфигурации средства MCP:

    "tools": [
      {
        "server_label": "knowledge-base",
        "server_url": "{search_service_endpoint}/knowledgebases/{knowledge_base_name}/mcp?api-version=2025-11-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-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}")

Выходные данные должны быть похожи на следующие (усеченные для краткости):

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)

Отправьте пустой POST запрос для создания сеанса беседы:

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

{}

Ответ включает беседу id, которую можно использовать для отправки запроса агенту:

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

Ответ содержит метаданные о выполнении агента, вызовах инструментов и созданных выходных данных. Наиболее важной частью ответа является элемент text в поле content, которое должно быть похоже на следующее (усечено для краткости):

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}