详细记录Google A2UI 本地调试问题解决方案：

如果你还没装 uv，在 macOS 上推荐用 Homebrew：

安装完成后验证：

默认部署会报错： 

× Failed to download google-genai==1.55.0

  ├─▶ Failed to fetch:

  │   https://files.pythonhosted.org/packages/3e/86/a5a8e32b2d40b30b5fb20e7b8113fafd1e38befa4d1801abd5ce6991065a/google_genai-1.55.0-py3-none-any.whl

  ├─▶ Request failed after 3 retries

  ├─▶ error sending request for url

  │   (https://files.pythonhosted.org/packages/3e/86/a5a8e32b2d40b30b5fb20e7b8113fafd1e38befa4d1801abd5ce6991065a/google_genai-1.55.0-py3-none-any.whl)

  ╰─▶ operation timed out

这个错误本质很清楚了：网络连不上 PyPI 的文件站点，不是环境或 uv 的问题。

operation timed out

files.pythonhosted.org

在 国内网络 / 公司网络 下，这个地址经常超时。

下面给你 几种稳妥解法，从「最快见效」到「长期方案」。

写入你的 ~/.zshrc：

echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.zshrc
source ~/.zshrc

guoqingzhou@guoqingzhoudeMacBook-Pro A2UI % echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple'
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
guoqingzhou@guoqingzhoudeMacBook-Pro A2UI % uv --version
uv 0.9.18 (Homebrew 2025-12-16)
guoqingzhou@guoqingzhoudeMacBook-Pro A2UI % cd samples
guoqingzhou@guoqingzhoudeMacBook-Pro samples % cd agent/adk/restaurant_finder
guoqingzhou@guoqingzhoudeMacBook-Pro restaurant_finder % uv run .
Built a2ui @ file:///Users/guoqingzhou/Projects/A2UI/A2UI/a2a_agents/python/a2ui_extension
Built a2ui-restaurant-finder @ file:///Users/guoqingzhou/Projects/A2UI/A2UI/samples/agent/adk/restaurant_finder
Updated https://github.com/google/adk-python.git (143ad44f8c5d1c56fc92dd691589aaa0b788e485)
Built watchdog==6.0.0
Built google-adk @ git+https://github.com/google/adk-python.git@143ad44f8c5d1c56fc92dd691589aaa0b788e485
Installed 134 packages in 224ms
ERROR:__main__:Error: GEMINI_API_KEY environment variable not set and GOOGLE_GENAI_USE_VERTEXAI is not TRUE.
guoqingzhou@guoqingzhoudeMacBook-Pro restaurant_finder % export GEMINI_API_KEY="A************nc0"
guoqingzhou@guoqingzhoudeMacBook-Pro restaurant_finder % uv run .
/Users/guoqingzhou/Projects/A2UI/A2UI/samples/agent/adk/restaurant_finder/agent.py:107: UserWarning: [GEMINI_VIA_LITELLM] gemini/gemini-2.5-flash: You are using Gemini via LiteLLM. For better performance, reliability, and access to latest features, consider using Gemini directly through ADK's native Gemini integration. Replace LiteLlm(model='gemini/gemini-2.5-flash') with Gemini(model='gemini-2.5-flash'). Set ADK_SUPPRESS_GEMINI_LITELLM_WARNINGS=true to suppress this warning.
model=LiteLlm(model=LITELLM_MODEL),
INFO:agent:A2UI_SCHEMA successfully loaded and wrapped in an array validator.
INFO:agent:A2UI_SCHEMA successfully loaded and wrapped in an array validator.
INFO: Started server process [1789]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://localhost:10002 (Press CTRL+C to quit)