[hosted-agents]docs: add troubleshooting section for ARM64 local Docker builds (#416)

Author: iuiaoin

samples/csharp/hosted-agents/AgentWithHostedMCP/README.md

@@ -1,16 +1,16 @@
 **IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
- 
+
 Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
- 
+
 Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
- 
+
 Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
 
 # What this sample demonstrates
 
-This sample demonstrates how to use a Hosted Model Context Protocol (MCP) server with a 
+This sample demonstrates how to use a Hosted Model Context Protocol (MCP) server with a
 [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview#ai-agents) AI agent and
-host it using [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and 
+host it using [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and
 deploy it to Microsoft Foundry using the Azure Developer CLI [ai agent](https://aka.ms/azdaiagent/docs) extension.
 
 ## How It Works
@@ -56,6 +56,7 @@ Set the following environment variables:
 - `AZURE_OPENAI_DEPLOYMENT_NAME` - The deployment name for your chat model (optional, defaults to `gpt-4o-mini`)
 
 **PowerShell:**
+
 ```powershell
 # Replace with your Azure OpenAI endpoint
 $env:AZURE_OPENAI_ENDPOINT="https://your-openai-resource.openai.azure.com/"
@@ -86,3 +87,21 @@ Try asking questions about Microsoft documentation and technologies to see the M
 ### Deploying the Agent to Microsoft Foundry
 
 To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Add this line at the top of your `Dockerfile`:
+
+```dockerfile
+FROM --platform=linux/amd64 python:3.12-slim
+```
+
+This forces the image to be built for the required `amd64` architecture.

samples/csharp/hosted-agents/AgentWithTextSearchRag/README.md

@@ -1,16 +1,16 @@
 **IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
- 
+
 Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
- 
+
 Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
- 
+
 Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
 
 # What this sample demonstrates
 
-This sample demonstrates how to use the TextSearchProvider to add retrieval augmented generation (RAG) capabilities to a 
+This sample demonstrates how to use the TextSearchProvider to add retrieval augmented generation (RAG) capabilities to a
 [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview#ai-agents) AI agent and
-host it using [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and 
+host it using [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and
 deploy it to Microsoft Foundry using the Azure Developer CLI [ai agent](https://aka.ms/azdaiagent/docs) extension.
 
 ## How It Works
@@ -56,6 +56,7 @@ Set the following environment variables:
 - `AZURE_OPENAI_DEPLOYMENT_NAME` - The deployment name for your chat model (optional, defaults to `gpt-4o-mini`)
 
 **PowerShell:**
+
 ```powershell
 # Replace with your Azure OpenAI endpoint
 $env:AZURE_OPENAI_ENDPOINT="https://your-openai-resource.openai.azure.com/"
@@ -82,10 +83,29 @@ You can interact with the agent using:
 - Any OpenAI Responses compatible client by sending requests to `http://localhost:8080/`
 
 Try asking questions about:
+
 - Contoso return policy
 - Shipping information
 - Product care instructions
 
 ### Deploying the Agent to Microsoft Foundry
 
-To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Add this line at the top of your `Dockerfile`:
+
+```dockerfile
+FROM --platform=linux/amd64 python:3.12-slim
+```
+
+This forces the image to be built for the required `amd64` architecture.

samples/csharp/hosted-agents/AgentsInWorkflows/README.md

@@ -1,15 +1,15 @@
 **IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
- 
+
 Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
- 
+
 Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
- 
+
 Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
 
 # What this sample demonstrates
 
-This sample demonstrates how to use AI agents as executors within a workflow, hosted using 
-[Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and 
+This sample demonstrates how to use AI agents as executors within a workflow, hosted using
+[Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and
 deploy it to Microsoft Foundry using the Azure Developer CLI [ai agent](https://aka.ms/azdaiagent/docs) extension.
 
 ## How It Works
@@ -23,6 +23,7 @@ This sample demonstrates the integration of AI agents within a workflow pipeline
 3. **English Agent** - Takes the Spanish translation and translates it back to English
 
 The agents are connected sequentially in a workflow, creating a translation chain that demonstrates:
+
 - How AI-powered agents can be seamlessly integrated into workflow pipelines
 - Sequential execution patterns where each agent's output becomes the next agent's input
 - Composable agent architectures for multi-step processing
@@ -56,6 +57,7 @@ Set the following environment variables:
 - `AZURE_OPENAI_DEPLOYMENT_NAME` - The deployment name for your chat model (optional, defaults to `gpt-4o-mini`)
 
 **PowerShell:**
+
 ```powershell
 # Replace with your Azure OpenAI endpoint
 $env:AZURE_OPENAI_ENDPOINT="https://your-openai-resource.openai.azure.com/"
@@ -85,4 +87,22 @@ Try providing text in English to see it translated through the workflow chain (E
 
 ### Deploying the Agent to Microsoft Foundry
 
-To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Add this line at the top of your `Dockerfile`:
+
+```dockerfile
+FROM --platform=linux/amd64 python:3.12-slim
+```
+
+This forces the image to be built for the required `amd64` architecture.

samples/python/hosted-agents/agent_with_hosted_mcp/README.md

@@ -1,14 +1,14 @@
 **IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
- 
+
 Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
- 
+
 Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
- 
+
 Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
 
 # What this sample demonstrates
 
-This sample demonstrates how to use a Hosted Model Context Protocol (MCP) server with a 
+This sample demonstrates how to use a Hosted Model Context Protocol (MCP) server with a
 [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview#ai-agents) AI agent and
 host it using [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and
 deploy it to Microsoft Foundry using the Azure Developer CLI [ai agent](https://aka.ms/azdaiagent/docs) extension.
@@ -91,4 +91,22 @@ curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/respo
 
 ### Deploying the Agent to Microsoft Foundry
 
-To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Add this line at the top of your `Dockerfile`:
+
+```dockerfile
+FROM --platform=linux/amd64 python:3.12-slim
+```
+
+This forces the image to be built for the required `amd64` architecture.

samples/python/hosted-agents/agent_with_text_search_rag/README.md

@@ -1,9 +1,9 @@
 **IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
- 
+
 Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
- 
+
 Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
- 
+
 Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
 
 # What this sample demonstrates
@@ -91,4 +91,22 @@ curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/respo
 
 ### Deploying the Agent to Microsoft Foundry
 
-To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Add this line at the top of your `Dockerfile`:
+
+```dockerfile
+FROM --platform=linux/amd64 python:3.12-slim
+```
+
+This forces the image to be built for the required `amd64` architecture.

samples/python/hosted-agents/agents_in_workflow/README.md

@@ -1,14 +1,14 @@
 **IMPORTANT!** All samples and other resources made available in this GitHub repository ("samples") are designed to assist in accelerating development of agents, solutions, and agent workflows for various scenarios. Review all provided resources and carefully test output behavior in the context of your use case. AI responses may be inaccurate and AI actions should be monitored with human oversight. Learn more in the transparency documents for [Agent Service](https://learn.microsoft.com/en-us/azure/ai-foundry/responsible-ai/agents/transparency-note) and [Agent Framework](https://github.com/microsoft/agent-framework/blob/main/TRANSPARENCY_FAQ.md).
- 
+
 Agents, solutions, or other output you create may be subject to legal and regulatory requirements, may require licenses, or may not be suitable for all industries, scenarios, or use cases. By using any sample, you are acknowledging that any output created using those samples are solely your responsibility, and that you will comply with all applicable laws, regulations, and relevant safety standards, terms of service, and codes of conduct.
- 
+
 Third-party samples contained in this folder are subject to their own designated terms, and they have not been tested or verified by Microsoft or its affiliates.
- 
+
 Microsoft has no responsibility to you or others with respect to any of these samples or any resulting output.
 
 # What this sample demonstrates
 
-This sample demonstrates how to use AI agents as executors within a workflow, hosted using 
+This sample demonstrates how to use AI agents as executors within a workflow, hosted using
 [Azure AI AgentServer SDK](https://learn.microsoft.com/en-us/dotnet/api/overview/azure/ai.agentserver.agentframework-readme) and
 deploy it to Microsoft Foundry using the Azure Developer CLI [ai agent](https://aka.ms/azdaiagent/docs) extension.
 
@@ -89,4 +89,22 @@ curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/respo
 
 ### Deploying the Agent to Microsoft Foundry
 
-To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+To deploy your agent to Microsoft Foundry, follow the comprehensive deployment guide at https://aka.ms/azdaiagent/docs
+
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Add this line at the top of your `Dockerfile`:
+
+```dockerfile
+FROM --platform=linux/amd64 python:3.12-slim
+```
+
+This forces the image to be built for the required `amd64` architecture.

samples/python/hosted-agents/calculator-agent/README.md

@@ -0,0 +1,17 @@
+## Troubleshooting
+
+### Images built on Apple Silicon or other ARM64 machines do not work on our service
+
+We **recommend using `azd` cloud build**, which always builds images with the correct architecture.
+
+If you choose to **build locally**, and your machine is **not `linux/amd64`** (for example, an Apple Silicon Mac), the image will **not be compatible with our service**, causing runtime failures.
+
+**Fix for local builds**
+
+Add this line at the top of your `Dockerfile`:
+
+```dockerfile
+FROM --platform=linux/amd64 python:3.12-slim
+```
+
+This forces the image to be built for the required `amd64` architecture.