diff --git a/python/packages/chatkit/README.md b/python/packages/chatkit/README.md index 5997ec49b5..afdb6f237f 100644 --- a/python/packages/chatkit/README.md +++ b/python/packages/chatkit/README.md @@ -20,6 +20,37 @@ pip install agent-framework-chatkit --pre This will install `agent-framework-core` and `openai-chatkit` as dependencies. +## Requirements and Limitations + +### Frontend Requirements + +The ChatKit integration requires the OpenAI ChatKit frontend library, which has the following requirements: + +1. **Internet Connectivity Required**: The ChatKit UI is loaded from OpenAI's CDN (`cdn.platform.openai.com`). This library cannot be self-hosted or bundled locally. + +2. **External Network Requests**: The ChatKit frontend makes requests to: + - `cdn.platform.openai.com` - UI library (required) + - `chatgpt.com/ces/v1/projects/oai/settings` - Configuration + - `api-js.mixpanel.com` - Telemetry (metadata only, not user messages) + +3. **Domain Registration for Production**: Production deployments require registering your domain at [platform.openai.com](https://platform.openai.com/settings/organization/security/domain-allowlist) and configuring a domain key. + +### Air-Gapped / Regulated Environments + +**The ChatKit frontend is not suitable for air-gapped or highly-regulated environments** where outbound connections to OpenAI domains are restricted. + +**What IS self-hostable:** + +- The backend components (`chatkit-python`, `agent-framework-chatkit`) are fully open source and have no external dependencies + +**What is NOT self-hostable:** + +- The frontend UI (`chatkit.js`) requires connectivity to OpenAI's CDN + +For environments with network restrictions, consider building a custom frontend that consumes the ChatKit server protocol, or using alternative UI libraries like `ai-sdk`. + +See [openai/chatkit-js#57](https://github.com/openai/chatkit-js/issues/57) for tracking self-hosting feature requests. + ## Example Usage Here's a minimal example showing how to integrate Agent Framework with ChatKit: diff --git a/python/samples/demos/chatkit-integration/README.md b/python/samples/demos/chatkit-integration/README.md index 28dfef398e..3d47925bdd 100644 --- a/python/samples/demos/chatkit-integration/README.md +++ b/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) diff --git a/python/samples/demos/chatkit-integration/frontend/index.html b/python/samples/demos/chatkit-integration/frontend/index.html index 82837ef519..e0607df1ae 100644 --- a/python/samples/demos/chatkit-integration/frontend/index.html +++ b/python/samples/demos/chatkit-integration/frontend/index.html @@ -4,6 +4,11 @@ ChatKit + Agent Framework Demo +