google-antigravity-sdk

Google Antigravity SDK

安装与设置

在继续执行任何 Google Antigravity 任务之前，请确保环境已准备就绪：

• 确认适用性：如果正在现有代码库中操作，请确认该项目可以且适合使用此 Python SDK。
• 检查依赖项：检查 google-antigravity 是否已列在项目的依赖项中（例如 requirements.txt、pyproject.toml）。
• 安装软件包：确保已安装 google-antigravity Python 软件包。
• 身份验证设置：
  • SDK 默认使用带 API 密钥的托管 Gemini 模型（LocalAgentConfig）。如果需要在设备上运行或不连接云端，可以使用本地模型（LiteRTAgentConfig 或 LocalOpenAIAgentConfig）作为替代方案，无需 API 密钥或云凭据。
  • 托管模型（Gemini - 默认）：检查是否设置了有效的 GEMINI_API_KEY 环境变量或 .env 文件（访问 Gemini 模型时需要）。
    • 如果缺少凭据，必须主动协助用户获取 API 密钥，并提供以下链接：
      • 默认使用 Google AI Studio： https://aistudio.google.com/app/api-keys
    • 说明可以在代码中显式传入 API 密钥作为简写（例如 LocalAgentConfig(api_key="...")），也可以从环境中自动读取。
    • 对于 Gemini Enterprise Agent Platform（原 Vertex AI）身份验证，SDK 同时支持 Standard Mode 和 Express Mode：
      • Standard Mode（ADC）：指导用户运行 gcloud auth application-default login，并在 LocalAgentConfig 中配置 vertex=True、project 和 location。
      • Express Mode（API 密钥）：在 LocalAgentConfig 中配置 vertex=True 和 api_key="your-express-api-key"（无需 ADC 或区域项目/位置）。
  • 本地模型（替代方案）：对于本地模型（LiteRTAgentConfig 或 LocalOpenAIAgentConfig），无需 API 密钥或云凭据。LiteRT 是受支持的本地模型设备端运行时（例如 Gemma 4 26B）。有关设置详情，请参阅 references/local_models.md 和 examples/getting_started/local_models.md。

路由表

根据用户请求，使用以下信息深入了解特定主题。阅读所引用的文件或浏览相关目录，以查找相关信息。

参考资料

• 如果用户需要了解 Google Antigravity SDK（Agent、Conversation、Connection）的高层概述和核心概念，请阅读 references/architecture.md。
• 如果用户需要进行高级 Agent 配置（例如选择合适的模型、通过 agent_behavior 配置执行行为——默认为自主模式还是交互模式——或配置连接可靠性），或者了解模型标识符的关键规则以避免想当然，请阅读 references/agent_configuration.md。
• 如果用户需要通过集成 Model Context Protocol（MCP）服务来扩展 Agent 的能力，或配置 Agent 的工具权限，请阅读 references/mcp_integration.md。
• 如果用户需要定义安全策略、确定执行顺序、使用谓词限制 Agent 的操作，或在操作系统级沙箱内运行终端命令，请阅读 references/safety_policies.md。
• 如果用户需要调试运行失败的 Agent、流式传输日志，或使用钩子实现错误恢复以提高 Agent 的可靠性，请阅读 references/error_handling.md。
• 如果用户需要监控成本、跟踪 Token 用量（包括思考 Token），或构建自定义审计日志以进行高级监控，请阅读 references/observability.md。
• 如果用户需要查看内置工具列表并了解其默认状态，请阅读 references/built_in_tools.md。
• 如果用户需要使用设备端模型在本地运行 Agent（受支持的设备端运行时使用 LiteRTAgentConfig，外部兼容 OpenAI 的服务端（如 Ollama/LM Studio）使用 LocalOpenAIAgentConfig），了解硬件要求，或配置本地 执行，请阅读 references/local_models.md。

示例

• 如果用户需要实现基本的 Agent 行为、流式响应或公开内部思考，请阅读 examples/getting_started/hello_world.md。
• 如果用户需要自定义或覆盖 API 错误或架构验证的默认重试行为和指数退避，请阅读 examples/getting_started/customizing_retries.md。
• 如果用户需要为 Agent 配备基于 Python 函数的自定义能力（工具），或在工具执行期间保持 Agent 状态，请阅读 examples/getting_started/custom_tool.md。
• 如果用户需要塑造 Agent 的角色设定、定义其系统指令或动态调整其行为，请阅读 examples/getting_started/persona_config.md。
• 如果用户需要构建能够处理图像和 PDF 或生成视觉内容的多模态 Agent，请阅读 examples/getting_started/multimodal.md。
• 如果用户需要实现多 Agent 委派，让主 Agent 能够启动并协调子 Agent，或配置多层嵌套的子 Agent 层级结构（使用 max_subagent_depth 和 allowed_subagents），请阅读 examples/getting_started/subagents.md。
• 如果用户需要使用 @beta.workflows.define（phase、log、agent、parallel、pipeline）和 await agent.beta.run_workflow(...) 编写并执行确定性的多 Agent 工作流，请阅读 examples/getting_started/workflows.md。
• 如果用户需要通过 MCP（Stdio 或 SSE）将 Agent 连接到外部服务，请阅读 examples/getting_started/mcp_tools.md。
• 如果用户需要创建能够在后台响应定时事件或文件系统触发器的主动式 Agent，请阅读 examples/getting_started/periodic_trigger.md。
• 如果用户需要拦截 Agent 生命周期事件（例如轮次开始前/结束后、停止、工具执行、错误）来自定义执行流程，请阅读 examples/getting_started/hooks.md。
• 如果用户需要实现轮次级取消或通过编程方式中止流，请阅读 examples/getting_started/cancellation.md。
• 如果用户需要实现能够跨会话记住过去交互的持久化 Agent，请阅读 examples/getting_started/persistence.md。
• 如果用户需要覆盖 Agent 产物、临时文件和媒体存储的默认应用数据目录，请阅读 examples/getting_started/app_data_dir_override.md。
• 如果用户需要让 Agent 输出结构化数据（例如符合 Pydantic 架构的 JSON），以便可靠集成，请阅读 examples/getting_started/structured_output.md。
• 如果用户需要向 Google Antigravity SDK Agent 添加、配置或加载技能，请阅读 examples/getting_started/agent_skills.md。
• 如果用户需要启用并使用内置网页工具（如 Google Search 或 URL 抓取），请阅读 examples/getting_started/web_tools.md。（注意：抓取大型网页或文章时，结合使用 read_url_content 和 view_file 来检查缓存的磁盘文件。）
• 如果用户需要设置会话运行限制（模型或工具调用次数）或主动控制 Token 预算（输入、输出或总 Token 数），并处理 StopReason，请阅读 examples/getting_started/budget_limits.md。
• 如果用户需要设置并运行本地模型 Agent（LiteRT 或 Ollama 等兼容 OpenAI 的服务端），包括模型下载、硬件要求和上下文压缩配置，请阅读 examples/getting_started/local_models.md。
• 如果用户需要配置对话上下文限制和压缩阈值，以处理长时间运行的会话，请阅读 examples/getting_started/compaction.md。