microsoft-foundry

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Microsoft Foundry Skill

This skill helps developers work with Microsoft Foundry resources, covering model discovery and deployment, RAG (Retrieval-Augmented Generation) applications, AI agent creation, evaluation workflows, and troubleshooting.

本Skill帮助开发者操作Microsoft Foundry资源，涵盖模型发现与部署、RAG（检索增强生成）应用构建、AI Agent创建、评估工作流以及故障排查等内容。

When to Use This Skill

何时使用本Skill

Use this skill when the user wants to:

Discover and deploy AI models from the Microsoft Foundry catalog
Build RAG applications using knowledge indexes and vector search
Create AI agents with tools like Azure AI Search, web search, or custom functions
Evaluate agent performance using built-in evaluators
Set up monitoring and continuous evaluation for production agents
Troubleshoot issues with deployments, agents, or evaluations

当用户需要完成以下操作时，可使用本Skill：

从Microsoft Foundry目录中发现并部署AI模型
借助知识索引和向量搜索构建RAG应用
结合Azure AI Search、网页搜索或自定义工具创建AI Agent
使用内置评估器评估Agent性能
为生产环境中的Agent设置监控与持续评估
排查部署、Agent或评估环节中的常见问题

Prerequisites

前提条件

Azure Resources

Azure资源

An Azure subscription with an active account
Appropriate permissions to create Microsoft Foundry resources (e.g., Azure AI Owner role)
Resource group for organizing Foundry resources

拥有有效账户的Azure订阅
具备创建Microsoft Foundry资源的适当权限（例如Azure AI Owner角色）
用于管理Foundry资源的资源组

Tools

工具

Azure CLI installed and authenticated (
```
az login
```
)
Azure Developer CLI (azd) for deployment workflows (optional but recommended)

已安装并完成身份验证的Azure CLI（执行
```
az login
```
）
用于部署工作流的Azure Developer CLI (azd)（可选但推荐）

Language-Specific Requirements

语言特定要求

For SDK examples and implementation details in specific programming languages, refer to:

Python: See language/python.md for Python SDK setup, authentication, and examples

如需特定编程语言的SDK示例和实现细节，请参考：

Python：查看language/python.md获取Python SDK的设置、身份验证及示例代码

Core Workflows

核心工作流

1. Getting Started - Model Discovery and Deployment

1. 入门指南 - 模型发现与部署

Use Case

使用场景

A developer new to Microsoft Foundry wants to explore available models and deploy their first one.

刚接触Microsoft Foundry的开发者想要探索可用模型并部署首个模型。

Step 1: List Available Resources

步骤1：列出可用资源

First, help the user discover their Microsoft Foundry resources.

Using Azure CLI:

首先，帮助用户发现其Microsoft Foundry资源。

使用Azure CLI：

Bash

bash

undefined

bash

undefined

List all Microsoft Foundry resources in subscription

列出订阅中所有Microsoft Foundry资源

az resource list
--resource-type "Microsoft.CognitiveServices/accounts"
--query "[?kind=='AIServices'].{Name:name, ResourceGroup:resourceGroup, Location:location}"
--output table

List resources in a specific resource group

列出特定资源组中的资源

az resource list
--resource-group <resource-group-name>
--resource-type "Microsoft.CognitiveServices/accounts"
--output table


**Using MCP Tools:**

Use the `foundry_resource_get` MCP tool to get detailed information about a specific Foundry resource, or to list all resources if no name is provided.

az resource list
--resource-group <resource-group-name>
--resource-type "Microsoft.CognitiveServices/accounts"
--output table


**使用MCP工具：**

使用`foundry_resource_get` MCP工具获取特定Foundry资源的详细信息，若未指定名称则列出所有资源。

Step 2: Browse Model Catalog

步骤2：浏览模型目录

Help users discover available models, including information about free playground support.

Key Points to Explain:

Some models support free playground for prototyping without costs
Models can be filtered by publisher (e.g., OpenAI, Meta, Microsoft)
Models can be filtered by license type
Model availability varies by region

Using MCP Tools:

Use the

foundry_models_list

MCP tool:

List all models:
```
foundry_models_list()
```

List free playground models:

foundry_models_list(search-for-free-playground=true)

Filter by publisher:
```
foundry_models_list(publisher="OpenAI")
```
Filter by license:
```
foundry_models_list(license="MIT")
```

Example Output Explanation: When listing models, explain to users:

Models with free playground support can be used for prototyping at no cost
Some models support GitHub token authentication for easy access
Check model capabilities and pricing before production deployment

帮助用户发现可用模型，包括支持免费试用的相关信息。

需说明的关键点：

部分模型支持免费试用环境，可零成本进行原型开发
可按发布方筛选模型（例如OpenAI、Meta、Microsoft）
可按许可证类型筛选模型
模型的可用区域因地区而异

使用MCP工具：

使用

foundry_models_list

MCP工具：

列出所有模型：
```
foundry_models_list()
```

列出支持免费试用的模型：

foundry_models_list(search-for-free-playground=true)

按发布方筛选：
```
foundry_models_list(publisher="OpenAI")
```
按许可证筛选：
```
foundry_models_list(license="MIT")
```

示例输出说明： 列出模型时，需向用户说明：

支持免费试用环境的模型可用于零成本原型开发
部分模型支持GitHub令牌身份验证，便于访问
生产部署前需确认模型的功能与定价

Step 3: Deploy a Model

步骤3：部署模型

Guide users through deploying a model to their Foundry resource.

Using Azure CLI:

引导用户将模型部署到其Foundry资源中。

使用Azure CLI：

Bash

bash

undefined

bash

undefined

Deploy a model (e.g., gpt-4o)

部署模型（例如gpt-4o）

az cognitiveservices account deployment create
--name <foundry-resource-name>
--resource-group <resource-group-name>
--deployment-name gpt-4o-deployment
--model-name gpt-4o
--model-version "2024-05-13"
--model-format OpenAI
--sku-capacity 10
--sku-name Standard

Verify deployment status

验证部署状态

az cognitiveservices account deployment show
--name <foundry-resource-name>
--resource-group <resource-group-name>
--deployment-name gpt-4o-deployment


**Using MCP Tools:**

Use the `foundry_models_deploy` MCP tool with parameters:
- `resource-group`: Resource group name
- `deployment`: Deployment name
- `model-name`: Model to deploy (e.g., "gpt-4o")
- `model-format`: Format (e.g., "OpenAI")
- `azure-ai-services`: Foundry resource name
- `model-version`: Specific version
- `sku-capacity`: Capacity units
- `scale-type`: Scaling type

**Deployment Verification:**
Explain that when deployment completes, `provisioningState` should be `Succeeded`. If it fails, common issues include:
- Insufficient quota
- Region capacity limitations
- Permission issues

az cognitiveservices account deployment show
--name <foundry-resource-name>
--resource-group <resource-group-name>
--deployment-name gpt-4o-deployment


**使用MCP工具：**

使用`foundry_models_deploy` MCP工具，参数包括：
- `resource-group`：资源组名称
- `deployment`：部署名称
- `model-name`：待部署的模型（例如"gpt-4o"）
- `model-format`：模型格式（例如"OpenAI"）
- `azure-ai-services`：Foundry资源名称
- `model-version`：特定版本
- `sku-capacity`：容量单位
- `scale-type`：缩放类型

**部署验证：**
说明部署完成后，`provisioningState`应显示为`Succeeded`。若部署失败，常见原因包括：
- 配额不足
- 区域容量限制
- 权限问题

Step 4: Get Resource Endpoint

步骤4：获取资源端点

Users need the project endpoint to connect their code to Foundry.

Using MCP Tools:

Use the

foundry_resource_get

MCP tool to retrieve resource details including the endpoint.

Expected Output: The endpoint will be in format:

https://<resource>.services.ai.azure.com/api/projects/<project-name>

Save this endpoint as it's needed for subsequent API and SDK calls.

用户需要项目端点来将代码连接到Foundry。

使用MCP工具：

使用

foundry_resource_get

MCP工具检索包含端点在内的资源详细信息。

预期输出： 端点格式为：

https://<resource>.services.ai.azure.com/api/projects/<project-name>

请保存此端点，后续API和SDK调用均会用到。

2. Building RAG Applications with Knowledge Indexes

2. 借助知识索引构建RAG应用

Use Case

使用场景

A developer wants to build a Retrieval-Augmented Generation (RAG) application using their own documents.

开发者想要利用自有文档构建检索增强生成（RAG）应用。

Understanding RAG and Knowledge Indexes

理解RAG与知识索引

Explain the Concept: RAG enhances AI responses by:

Retrieving relevant documents from a knowledge base
Augmenting the AI prompt with retrieved context
Generating responses grounded in factual information

Knowledge Index Benefits:

Supports keyword, semantic, vector, and hybrid search
Enables efficient retrieval of relevant content
Stores metadata for better citations (document titles, URLs, file names)
Integrates with Azure AI Search for production scenarios

概念说明： RAG通过以下步骤增强AI响应能力：

从知识库中检索相关文档
用检索到的上下文增强AI提示词
基于事实信息生成响应

知识索引的优势：

支持关键词、语义、向量及混合搜索
可高效检索相关内容
存储元数据以优化引用（文档标题、URL、文件名）
与Azure AI Search集成以适配生产场景

Step 1: List Existing Knowledge Indexes

步骤1：列出现有知识索引

Using MCP Tools:

Use

foundry_knowledge_index_list

with your project endpoint to list knowledge indexes.

使用MCP工具：

结合项目端点，使用

foundry_knowledge_index_list

列出知识索引。

Step 2: Inspect Index Schema

步骤2：查看索引架构

Understanding the index structure helps optimize queries.

Using MCP Tools:

Use the

foundry_knowledge_index_schema

MCP tool with your project endpoint and index name to get detailed schema information.

Schema Information Includes:

Field definitions and data types
Searchable attributes
Vectorization configuration
Retrieval mode support (keyword, semantic, vector, hybrid)

了解索引结构有助于优化查询。

使用MCP工具：

结合项目端点和索引名称，使用

foundry_knowledge_index_schema

MCP工具获取详细的架构信息。

架构信息包括：

字段定义与数据类型
可搜索属性
向量化配置
支持的检索模式（关键词、语义、向量、混合）

Step 3: Create an Agent with Azure AI Search Tool

步骤3：创建集成Azure AI Search工具的Agent

Implementation:

To create a RAG agent with Azure AI Search tool integration:

Initialize the AI Project Client with your project endpoint and credentials
Get the Azure AI Search connection from your project
Create the agent with:
- Agent name
- Model deployment
- Clear instructions (see best practices below)
- Azure AI Search tool configuration with:
  - Connection ID
  - Index name
  - Query type (HYBRID recommended)

For SDK Implementation: See language/python.md

Key Best Practices:

Always request citations in agent instructions
Use hybrid search (AzureAISearchQueryType.HYBRID) for best results
Instruct the agent to say "I don't know" when information isn't in the index
Format citations consistently for easy parsing

实现步骤：

要创建集成Azure AI Search工具的RAG Agent：

使用项目端点和凭据初始化AI项目客户端
从项目中获取Azure AI Search连接
创建Agent，配置：
- Agent名称
- 模型部署
- 清晰的指令（参考下方最佳实践）
- Azure AI Search工具配置，包括：
  - 连接ID
  - 索引名称
  - 查询类型（推荐使用HYBRID）

SDK实现参考： 查看language/python.md

关键最佳实践：

始终在Agent指令中要求提供引用
使用混合搜索（AzureAISearchQueryType.HYBRID）以获得最佳结果
指令Agent在索引中无对应信息时回复"我不知道"
统一引用格式以便于解析

Step 4: Test the RAG Agent

步骤4：测试RAG Agent

Testing Process:

Query the agent with a test question
Stream the response to get real-time output
Capture citations from the response annotations
Validate that citations are properly formatted and included

For SDK Implementation: See language/python.md

Troubleshooting RAG Issues:

Issue	Possible Cause	Resolution
No citations in response	Agent instructions don't request citations	Update instructions to explicitly request citation format
"Index not found" error	Wrong index name or connection	Verify `AI_SEARCH_INDEX_NAME` matches index in Azure AI Search
401/403 authentication error	Missing RBAC permissions	Assign project managed identity Search Index Data Contributor role
Poor retrieval quality	Query type not optimal	Try HYBRID query type for better results

测试流程：

向Agent提出测试问题
流式获取响应以查看实时输出
从响应注释中捕获引用
验证引用格式是否正确且已包含在内

SDK实现参考： 查看language/python.md

RAG问题排查：

问题	可能原因	解决方法
响应中无引用	Agent指令未要求提供引用	更新指令，明确要求引用格式
"索引未找到"错误	索引名称或连接错误	验证 `AI_SEARCH_INDEX_NAME` 与Azure AI Search中的索引名称匹配
401/403身份验证错误	缺少RBAC权限	为项目托管标识分配Search Index Data Contributor角色
检索质量不佳	查询类型非最优	尝试使用HYBRID查询类型以获得更好的结果

3. Creating Your First AI Agent

3. 创建首个AI Agent

Use Case

使用场景

A developer wants to create an AI agent with tools (web search, function calling, file search).

开发者想要创建具备工具（网页搜索、函数调用、文件搜索）的AI Agent。

Step 1: List Existing Agents

步骤1：列出现有Agent

Using MCP Tools:

Use

foundry_agents_list

with your project endpoint to list existing agents.

使用MCP工具：

结合项目端点，使用

foundry_agents_list

列出现有Agent。

Step 2: Create a Basic Agent

步骤2：创建基础Agent

Implementation:

Create an agent with:

Model deployment name: The model to use
Agent name: Unique identifier
Instructions: Clear, specific guidance for the agent's behavior

For SDK Implementation: See language/python.md

实现步骤：

创建Agent时需配置：

模型部署名称：使用的模型
Agent名称：唯一标识符
指令：针对Agent行为的清晰、具体指导

SDK实现参考： 查看language/python.md

Step 3: Create an Agent with Custom Function Tools

步骤3：创建集成自定义函数工具的Agent

Agents can call custom functions to perform actions like querying databases, calling APIs, or performing calculations.

Implementation Steps:

Define custom functions with clear docstrings describing their purpose and parameters
Create a function toolset with your custom functions
Create the agent with the toolset and instructions on when to use the tools

For SDK Implementation: See language/python.md

Agent可调用自定义函数来执行数据库查询、API调用或计算等操作。

实现步骤：

定义自定义函数，并添加清晰的文档字符串说明其用途和参数
创建函数工具集，包含自定义函数
创建Agent，配置工具集及工具使用时机的指令

SDK实现参考： 查看language/python.md

Step 4: Create an Agent with Web Search

步骤4：创建集成网页搜索的Agent

Implementation:

Create an agent with web search capabilities by adding a Web Search tool:

Optionally specify user location for localized results
Provide instructions to always cite web sources

For SDK Implementation: See language/python.md

实现步骤：

通过添加网页搜索工具，创建具备网页搜索能力的Agent：

可选择性指定用户位置以获取本地化结果
指令Agent始终引用网页来源

SDK实现参考： 查看language/python.md

Step 5: Interact with the Agent

步骤5：与Agent交互

Interaction Process:

Create a conversation thread for the agent interaction
Add user messages to the thread
Run the agent to process the messages and generate responses
Check run status for success or failure
Retrieve messages to see the agent's responses
Cleanup by deleting the agent when done

For SDK Implementation: See language/python.md

Agent Best Practices:

Clear Instructions: Provide specific, actionable instructions
Tool Selection: Only include tools the agent needs
Error Handling: Always check
```
run.status
```
for failures
Cleanup: Delete agents/threads when done to manage costs
Rate Limits: Handle rate limit errors gracefully (status code 429)

交互流程：

为Agent交互创建对话线程
向线程中添加用户消息
运行Agent以处理消息并生成响应
检查运行状态以确认成功或失败
检索消息以查看Agent的响应
完成后清理，删除Agent

SDK实现参考： 查看language/python.md

Agent最佳实践：

清晰指令：提供具体、可执行的指令
工具选择：仅包含Agent所需的工具
错误处理：始终检查
```
run.status
```
以排查失败情况
清理资源：完成后删除Agent/线程以控制成本
速率限制：优雅处理速率限制错误（状态码429）

4. Evaluating Agent Performance

4. 评估Agent性能

Use Case

使用场景

A developer has built an agent and wants to evaluate its quality, safety, and performance.

开发者已构建Agent，想要评估其质量、安全性和性能。

Understanding Agent Evaluators

理解Agent评估器

Built-in Evaluators:

IntentResolutionEvaluator: Measures how well the agent identifies and understands user requests (score 1-5)
TaskAdherenceEvaluator: Evaluates whether responses adhere to assigned tasks and system instructions (score 1-5)
ToolCallAccuracyEvaluator: Assesses whether the agent makes correct function tool calls (score 1-5)

Evaluation Output: Each evaluator returns:

```
{metric_name}
```
: Numerical score (1-5, higher is better)
```
{metric_name}_result
```
: "pass" or "fail" based on threshold
```
{metric_name}_threshold
```
: Binarization threshold (default or user-set)
```
{metric_name}_reason
```
: Explanation of the score

内置评估器：

IntentResolutionEvaluator：衡量Agent识别和理解用户请求的能力（评分1-5）
TaskAdherenceEvaluator：评估响应是否符合分配的任务和系统指令（评分1-5）
ToolCallAccuracyEvaluator：评估Agent调用函数工具的正确性（评分1-5）

评估输出： 每个评估器返回：

```
{metric_name}
```
：数值评分（1-5，越高越好）
```
{metric_name}_result
```
：基于阈值的"通过"或"失败"
```
{metric_name}_threshold
```
：二值化阈值（默认或用户设置）
```
{metric_name}_reason
```
：评分说明

Step 1: Single Agent Run Evaluation

步骤1：单次Agent运行评估

Using MCP Tools:

Use the

foundry_agents_query_and_evaluate

MCP tool to query an agent and evaluate the response in one call. Provide:

Agent ID
Query text
Project endpoint
Azure OpenAI endpoint and deployment for evaluation
Comma-separated list of evaluators to use

Example Output:

json

{
  "response": "The weather in Seattle is currently sunny and 22°C.",
  "evaluation": {
    "intent_resolution": 5.0,
    "intent_resolution_result": "pass",
    "intent_resolution_threshold": 3,
    "intent_resolution_reason": "The agent correctly identified the user's intent to get weather information and provided a relevant response.",
    "task_adherence": 4.0,
    "task_adherence_result": "pass",
    "tool_call_accuracy": 5.0,
    "tool_call_accuracy_result": "pass"
  }
}

使用MCP工具：

使用

foundry_agents_query_and_evaluate

MCP工具，可在一次调用中完成Agent查询和响应评估。需提供：

Agent ID
查询文本
项目端点
用于评估的Azure OpenAI端点和部署
逗号分隔的评估器列表

示例输出：

json

{
  "response": "The weather in Seattle is currently sunny and 22°C.",
  "evaluation": {
    "intent_resolution": 5.0,
    "intent_resolution_result": "pass",
    "intent_resolution_threshold": 3,
    "intent_resolution_reason": "The agent correctly identified the user's intent to get weather information and provided a relevant response.",
    "task_adherence": 4.0,
    "task_adherence_result": "pass",
    "tool_call_accuracy": 5.0,
    "tool_call_accuracy_result": "pass"
  }
}

Step 2: Evaluate Existing Response

步骤2：评估现有响应

If you already have the agent's response, you can evaluate it directly.

Using MCP Tools:

Use the

foundry_agents_evaluate

MCP tool to evaluate a specific query/response pair with a single evaluator.

For SDK Implementation: See language/python.md

若已获取Agent的响应，可直接对其进行评估。

使用MCP工具：

使用

foundry_agents_evaluate

MCP工具，针对特定的查询/响应对使用单个评估器进行评估。

SDK实现参考： 查看language/python.md

Step 3: Batch Evaluation

步骤3：批量评估

For evaluating multiple agent runs across multiple conversation threads:

Convert agent thread data to evaluation format
Prepare evaluation data from multiple thread IDs
Set up evaluators with appropriate configuration
Run batch evaluation and view results in the Foundry portal

For SDK Implementation: See language/python.md

要评估多个对话线程中的多组Agent运行：

将Agent线程数据转换为评估格式
从多个线程ID中准备评估数据
配置评估器并设置合适的参数
运行批量评估，并在Foundry门户中查看结果

SDK实现参考： 查看language/python.md

Interpreting Evaluation Results

评估结果解读

Score Ranges (1-5 scale):

5: Excellent - Agent perfectly understood and executed the task
4: Good - Minor issues, but overall successful
3: Acceptable - Threshold for passing (default)
2: Poor - Significant issues with understanding or execution
1: Failed - Agent completely misunderstood or failed the task

Common Evaluation Issues:

Issue	Cause	Resolution
Job stuck in "Running"	Insufficient model capacity	Increase model quota/capacity and rerun
All metrics zero	Wrong evaluator or unsupported model	Verify evaluator compatibility with your model
Groundedness unexpectedly low	Incomplete context/retrieval	Verify RAG retrieval includes sufficient context
Evaluation missing	Not selected during setup	Rerun evaluation with required metrics

评分范围（1-5分制）：

5分：优秀 - Agent完全理解并执行任务
4分：良好 - 存在小问题，但整体成功
3分：可接受 - 默认通过阈值
2分：较差 - 在理解或执行方面存在显著问题
1分：失败 - Agent完全误解或未完成任务

常见评估问题：

问题	原因	解决方法
任务卡在"运行中"	模型容量不足	增加模型配额/容量并重试
所有指标为0	评估器错误或模型不支持	验证评估器与模型的兼容性
事实性评分意外偏低	上下文/检索不完整	验证RAG检索包含足够的上下文
缺少评估结果	设置时未选择对应指标	重新运行评估并勾选所需指标

5. Troubleshooting Common Issues

5. 常见问题排查

Deployment Issues

部署问题

Problem: Deployment Stays Pending or Fails

问题：部署处于挂起状态或失败

Bash

bash

undefined

bash

undefined

Check deployment status and details

检查部署状态和详细信息

az cognitiveservices account deployment show
--name <resource-name>
--resource-group <resource-group>
--deployment-name <deployment-name>
--output json

Check account quota

检查账户配额

az cognitiveservices account show
--name <resource-name>
--resource-group <resource-group>
--query "properties.quotaLimit"


**Common Causes:**
- Insufficient quota in the region
- Region at capacity for the model
- Permission issues

**Resolution:**
1. Check quota limits in Azure Portal
2. Request quota increase if needed
3. Try deploying to a different region
4. Verify you have appropriate RBAC permissions

az cognitiveservices account show
--name <resource-name>
--resource-group <resource-group>
--query "properties.quotaLimit"


**常见原因：**
- 所在区域配额不足
- 模型在该区域的容量已满
- 权限问题

**解决方法：**
1. 在Azure门户中检查配额限制
2. 如需，申请增加配额
3. 尝试部署到其他区域
4. 验证是否具备适当的RBAC权限

Agent Response Issues

Agent响应问题

Problem: Agent Doesn't Return Citations (RAG)

Diagnostics:

Check agent instructions explicitly request citations
Verify the tool choice is set to "required" or "auto"
Confirm the Azure AI Search connection is configured correctly

Resolution:

Update the agent's instructions to explicitly request citations in the format

[message_idx:search_idx†source]

and to only use the knowledge base, never the agent's own knowledge.

For SDK Implementation: See language/python.md

Problem: "Index Not Found" Error

Using MCP Tools:

Use the

foundry_knowledge_index_list

MCP tool to verify the index exists and get the correct name.

Resolution:

Verify
```
AI_SEARCH_INDEX_NAME
```
environment variable matches actual index name
Check the connection points to correct Azure AI Search resource
Ensure index has been created and populated

Problem: 401/403 Authentication Errors

Common Cause: Missing RBAC permissions

Resolution:

问题：Agent未返回引用（RAG场景）

诊断：

检查Agent指令是否明确要求提供引用
验证工具选择是否设置为"required"或"auto"
确认Azure AI Search连接配置正确

解决方法：

更新Agent指令，明确要求以

[message_idx:search_idx†source]

格式提供引用，并指令Agent仅使用知识库内容，不得依赖自身知识。

SDK实现参考： 查看language/python.md

问题："索引未找到"错误

使用MCP工具：

使用

foundry_knowledge_index_list

MCP工具验证索引是否存在并获取正确名称。

解决方法：

验证环境变量
```
AI_SEARCH_INDEX_NAME
```
与实际索引名称匹配
检查连接指向的Azure AI Search资源是否正确
确认索引已创建并完成数据填充

问题：401/403身份验证错误

常见原因： 缺少RBAC权限

解决方法：

Bash

bash

undefined

bash

undefined

Assign Search Index Data Contributor role to managed identity

为托管标识分配Search Index Data Contributor角色

az role assignment create
--assignee <managed-identity-principal-id>
--role "Search Index Data Contributor"
--scope /subscriptions/<subscription-id>/resourceGroups/<rg>/providers/Microsoft.Search/searchServices/<search-service>

Verify role assignment

验证角色分配

az role assignment list
--assignee <managed-identity-principal-id>
--output table

undefined

az role assignment list
--assignee <managed-identity-principal-id>
--output table

undefined

Evaluation Issues

评估问题

Problem: Evaluation Dashboard Shows No Data

Common Causes:

No recent agent traffic
Time range excludes the data
Ingestion delay

Resolution:

Generate new agent traffic (test queries)
Expand the time range filter in the dashboard
Wait a few minutes for data ingestion
Refresh the dashboard

Problem: Continuous Evaluation Not Running

Diagnostics:

Check evaluation run status to identify issues. For SDK implementation, see language/python.md.

Resolution:

Verify the evaluation rule is enabled
Confirm agent traffic is flowing
Check project managed identity has Azure AI User role
Verify OpenAI endpoint and deployment are accessible

问题：评估仪表板无数据显示

常见原因：

近期无Agent流量
时间范围未包含对应数据
数据摄入延迟

解决方法：

生成新的Agent流量（测试查询）
扩大仪表板中的时间范围筛选器
等待几分钟以完成数据摄入
刷新仪表板

问题：持续评估未运行

诊断：

检查评估运行状态以排查问题。SDK实现参考：language/python.md。

解决方法：

验证评估规则已启用
确认Agent流量正常
检查项目托管标识是否具备Azure AI User角色
验证OpenAI端点和部署可正常访问

Rate Limiting and Capacity Issues

速率限制与容量问题

Problem: Agent Run Fails with Rate Limit Error

Error Message:

Rate limit is exceeded

or HTTP 429

Resolution:

问题：Agent运行因速率限制错误失败

错误信息：

Rate limit is exceeded

或 HTTP 429

解决方法：

Bash

bash

undefined

bash

undefined

Check current quota usage

检查当前配额使用情况

az cognitiveservices usage list
--name <resource-name>
--resource-group <resource-group>

Request quota increase (manual process in portal)

申请配额增加（需在门户中手动操作）

echo "Request quota increase in Azure Portal under Quotas section"

undefined

echo "Request quota increase in Azure Portal under Quotas section"

undefined

Request quota increase (manual process in portal)

申请配额增加（需在门户中手动操作）

Write-Output "Request quota increase in Azure Portal under Quotas section"


**Best Practices:**
- Implement exponential backoff retry logic
- Use Dynamic Quota when available
- Monitor quota usage proactively
- Consider multiple deployments across regions

Write-Output "Request quota increase in Azure Portal under Quotas section"


**最佳实践：**
- 实现指数退避重试逻辑
- 若可用，使用动态配额
- 主动监控配额使用情况
- 考虑在多区域部署多个实例

Quick Reference

快速参考

Common Environment Variables

常见环境变量

bash

undefined

bash

undefined

Foundry Project

Foundry项目

PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project> MODEL_DEPLOYMENT_NAME=gpt-4o

Azure AI Search (for RAG)

Azure AI Search（用于RAG）

AZURE_AI_SEARCH_CONNECTION_NAME=my-search-connection AI_SEARCH_INDEX_NAME=my-index

Evaluation

评估

AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com AZURE_OPENAI_DEPLOYMENT=gpt-4o

undefined

AZURE_OPENAI_ENDPOINT=https://<resource>.openai.azure.com AZURE_OPENAI_DEPLOYMENT=gpt-4o

undefined

Useful MCP Tools Quick Reference

常用MCP工具快速参考

Resource Management

```
foundry_resource_get
```
- Get resource details and endpoint

Models

```
foundry_models_list
```
- Browse model catalog
```
foundry_models_deploy
```
- Deploy a model
```
foundry_models_deployments_list
```
- List deployed models

Knowledge & RAG

```
foundry_knowledge_index_list
```
- List knowledge indexes
```
foundry_knowledge_index_schema
```
- Get index schema

Agents

```
foundry_agents_list
```
- List agents
```
foundry_agents_connect
```
- Query an agent
```
foundry_agents_query_and_evaluate
```
- Query and evaluate

OpenAI Operations

```
foundry_openai_chat_completions_create
```
- Create chat completions
```
foundry_openai_embeddings_create
```
- Create embeddings

资源管理

```
foundry_resource_get
```
- 获取资源详细信息和端点

模型相关

```
foundry_models_list
```
- 浏览模型目录
```
foundry_models_deploy
```
- 部署模型
```
foundry_models_deployments_list
```
- 列出已部署模型

知识与RAG

```
foundry_knowledge_index_list
```
- 列出知识索引
```
foundry_knowledge_index_schema
```
- 获取索引架构

Agent相关

```
foundry_agents_list
```
- 列出Agent
```
foundry_agents_connect
```
- 查询Agent
```
foundry_agents_query_and_evaluate
```
- 查询并评估Agent

OpenAI操作

```
foundry_openai_chat_completions_create
```
- 创建聊天补全
```
foundry_openai_embeddings_create
```
- 创建嵌入向量

Language-Specific Quick References

语言特定快速参考

For SDK-specific details, authentication, and code examples:

Python: See language/python.md

如需SDK特定的详细信息、身份验证及代码示例：

Python：查看language/python.md