Python: Document ChatKit frontend requirements and air-gapped limitations (#2587)

- Add "Requirements and Limitations" section to chatkit package README
- Add "Network Requirements" and "Limitations" sections to chatkit-integration sample README
- Add explanatory comments in frontend code for CDN dependency and domain key configuration

Fixes #2347

python/samples/demos/chatkit-integration/README.md

@@ -138,6 +138,31 @@ async for event in stream_widget(thread_id=thread.id, widget=widget):
 - Azure OpenAI service configured
 - Azure CLI for authentication (`az login`)
 
+### Network Requirements
+
+> **Important:** This sample uses the OpenAI ChatKit frontend, which requires internet connectivity to OpenAI services.
+
+The frontend makes outbound requests to:
+
+- `cdn.platform.openai.com` - ChatKit UI library (required)
+- `chatgpt.com` - Configuration endpoint
+- `api-js.mixpanel.com` - Telemetry
+
+**This sample is not suitable for air-gapped or network-restricted environments.** The ChatKit frontend library cannot be self-hosted. See [Limitations](#limitations) for details.
+
+### Domain Key Configuration
+
+For **local development**, the sample uses a default domain key (`domain_pk_localhost_dev`).
+
+For **production deployment**:
+
+1. Register your domain at [platform.openai.com](https://platform.openai.com/settings/organization/security/domain-allowlist)
+2. Create a `.env` file in the `frontend` directory:
+
+   ```
+   VITE_CHATKIT_API_DOMAIN_KEY=your_domain_key_here
+   ```
+
 ### Backend Setup
 
 1. **Install Python packages:**
@@ -261,6 +286,31 @@ Try these example queries:
 - "What's the current time?"
 - Upload an image and ask "What do you see in this image?"
 
+## Limitations
+
+### Air-Gapped / Regulated Environments
+
+The ChatKit frontend (`chatkit.js`) is loaded from OpenAI's CDN and cannot be self-hosted. This means:
+
+- **Not suitable for air-gapped environments** where `*.openai.com` is blocked
+- **Not suitable for regulated environments** that prohibit external telemetry
+- **Requires domain registration** with OpenAI for production use
+
+**What you CAN self-host:**
+
+- The Python backend (FastAPI server, `ChatKitServer`, stores)
+- The `agent-framework-chatkit` integration layer
+- Your LLM infrastructure (Azure OpenAI, local models, etc.)
+
+**What you CANNOT self-host:**
+
+- The ChatKit frontend UI library
+
+For more details, see:
+
+- [openai/chatkit-js#57](https://github.com/openai/chatkit-js/issues/57) - Self-hosting feature request
+- [openai/chatkit-js#76](https://github.com/openai/chatkit-js/issues/76) - Domain key requirements
+
 ## Learn More
 
 - [Agent Framework Documentation](https://aka.ms/agent-framework)

python/samples/demos/chatkit-integration/frontend/index.html

@@ -4,6 +4,11 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>ChatKit + Agent Framework Demo</title>
+    <!--
+      IMPORTANT: The ChatKit UI library is loaded from OpenAI's CDN and cannot be self-hosted.
+      This requires internet connectivity and is not suitable for air-gapped environments.
+      See: https://github.com/openai/chatkit-js/issues/57
+    -->
     <script src="https://cdn.platform.openai.com/deployments/chatkit/chatkit.js"></script>
     <style>
       * {

python/samples/demos/chatkit-integration/frontend/src/App.tsx

@@ -1,6 +1,12 @@
 import { ChatKit, useChatKit } from "@openai/chatkit-react";
 
 const CHATKIT_API_URL = "/chatkit";
+
+// Domain key for ChatKit integration
+// - Local development: Uses default "domain_pk_localhost_dev"
+// - Production: Register your domain at https://platform.openai.com/settings/organization/security/domain-allowlist
+//   and set VITE_CHATKIT_API_DOMAIN_KEY in your .env file
+// See: https://github.com/openai/chatkit-js/issues/76
 const CHATKIT_API_DOMAIN_KEY =
   import.meta.env.VITE_CHATKIT_API_DOMAIN_KEY ?? "domain_pk_localhost_dev";