Clarify endpoint requirements for Azure AI Foundry and Azure OpenAI providers (#927)

* Clarify endpoint requirements for Azure AI Foundry and Azure OpenAI providers

Source issue: microsoft/agent-framework#3361

* Address review feedback for #927: review comment fixes

* Address review feedback for #927: review comment fixes

---------

Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>
Co-authored-by: MAF Dashboard Bot <maf-dashboard-bot@users.noreply.github.com>

Author: 4 people

agent-framework/agents/providers/azure-openai.md

@@ -148,6 +148,9 @@ pip install agent-framework --pre
 
 ## Configuration
 
+> [!IMPORTANT]
+> The `AzureOpenAIChatClient` and `AzureOpenAIAssistantsClient` require an **Azure OpenAI resource** endpoint (format: `https://<myresource>.openai.azure.com`). The `AzureOpenAIResponsesClient` can use either an Azure OpenAI resource endpoint **or** a [Microsoft Foundry project](/azure/ai-foundry/what-is-ai-foundry) endpoint (format: `https://<your-project>.services.ai.azure.com/api/projects/<project-id>`). If you need to use the Foundry Agent Service instead, see the [Foundry Agents provider page](./azure-ai-foundry.md).
+
 Each client type uses different environment variables:
 
 # [Chat Completion](#tab/aoai-chat-completion)
@@ -228,7 +231,7 @@ asyncio.run(main())
 
 ### Responses Client with Microsoft Foundry project endpoint
 
-`AzureOpenAIResponsesClient` can also be created from a Foundry project endpoint:
+Instead of an Azure OpenAI resource endpoint, `AzureOpenAIResponsesClient` can also be created from a [Microsoft Foundry project](/azure/ai-foundry/what-is-ai-foundry) endpoint. Use a Foundry project endpoint when you want to access models deployed through a Microsoft Foundry project rather than a standalone Azure OpenAI resource:
 
 ```python
 from agent_framework.azure import AzureOpenAIResponsesClient

agent-framework/agents/providers/microsoft-foundry.md

@@ -98,6 +98,9 @@ For more information on how to run and interact with agents, see the [Agent gett
 
 ### Environment Variables
 
+> [!IMPORTANT]
+> `AzureAIAgentClient` (Foundry Agent Service v1) and `AzureAIClient` (Foundry Agent Service v2) both require an **Azure AI Foundry project** endpoint (format: `https://<your-project>.services.ai.azure.com/api/projects/<project-id>`), **not** an Azure OpenAI resource endpoint. You must have an [Azure AI Foundry project](/azure/ai-foundry/what-is-ai-foundry) to use this provider. If you have a standalone Azure OpenAI resource instead, see the [Azure OpenAI provider page](./azure-openai.md).
+
 Before using Foundry Agents, you need to set up these environment variables:
 
 ```bash