Gemini 中文指南
获取 API 密钥 ↗

构建托管智能体

↓ 下载 MarkdownInteractions API

Gemini API 上的托管智能体允许您使用自己的指令、技能和数据扩展 Antigravity 智能体。你可以 定制智能体内联 在交互时,或者 保存配置 作为您通过 ID 调用的托管智能体。

定制Antigravity 智能体 #

构建自定义智能体的最快方法是内联传递您的配置,同时创建新的交互,无需注册步骤。您可以通过多种关键方式扩展智能体:

  • 选型:通过选择底层 Gemini 型号 agent_config (默认为 Gemini 4 Hydrogen).
  • 系统指令:通过内嵌文本传递 system_instruction 塑造行为。
  • 工具:覆盖默认工具(代码执行、搜索、URL 上下文)、注册远程 MCP 服务器或定义自定义函数(函数调用)。
  • 文件和技能: 挂载文件如 AGENTS.md 和 SKILL.md 进入环境。

下面是传递所有三个内联的示例:

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the Q1 revenue data and create a slide deck.",
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
        ],
    },
)

print(interaction.output_text)

工具和系统说明#

您可以使用以下命令自定义智能体的行为和功能以进行特定交互 system_instruction 和 tools 参数。

  • 系统指令:使用 system_instruction 参数来传递塑造智能体行为的内联文本。这对于您想要在每次调用时进行更改的快速调整来说是理想的选择。的 system_instruction 和 AGENTS.md 是附加的;两者均在存在时适用。
  • 工具:默认情况下,Antigravity 智能体可以访问 code_execution, google_search, 和 url_context。您可以通过传递来覆盖此列表 tools 交互时的参数。您还可以注册 远程 MCP 服务器 或定义 自定义函数(函数调用) 将智能体连接到您自己的 API 和数据库。有关可用工具的完整详细信息,请参阅 Antigravity 智能体:支持的工具.

基于文件的定制#

智能体目录结构#

虽然您可以内联传递配置,但我们建议您将智能体的文件组织在结构化目录中。这使得管理、版本控制和安装到智能体的环境变得更加容易。

典型的智能体项目目录如下所示:

text
my-agent/
├── AGENTS.md        # Instructions on how the agent should operate
├── skills/          # Custom skills (subfolders and SKILL.md files)
│   └── slide-maker/
│       └── SKILL.md
└── workspace/       # Initial data files and knowledge

Antigravity 运行时扫描 .agents/ (以及环境的根目录)这些文件。

代理.md#

智能体自动加载 .agents/AGENTS.md (或 /.agents/AGENTS.md)从环境中作为启动时的系统指令。使用 AGENTS.md 对于长格式的角色定义、详细指南以及您想要与代码一起进行版本控制的说明。

安装一个 AGENTS.md 使用内联源:

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Analyze the Q1 revenue data and create a report.",
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report.",
            },
        ],
    },
)

print(interaction.output_text)

技能:技能.md#

技能是扩展智能体功能的文件。将它们放在下面 .agents/skills/<skill-name>/SKILL.md 线束会自动发现并注册它们。

text
.agents/
├── AGENTS.md
└── skills/
    └── slide-maker/
        └── SKILL.md

使用内联源安装技能:

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Create a presentation about our Q1 results.",
    system_instruction="You create presentations from data.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\ndescription: Create HTML slide decks\n---\n# Slide Maker\n\nWhen asked to create a presentation:\n1. Analyze the input data\n2. Create an HTML slide deck with reveal.js\n3. Save to /workspace/output/slides.html",
            },
        ],
    },
)

print(interaction.output_text)

创建托管智能体 #

迭代配置后,您可以将其创建为托管智能体 agents.create。这样您就可以通过 ID 调用智能体,而无需每次都重复配置。

该 id 您在创建托管智能体时指定的值对于您的项目必须是唯一的,并且不能以保留前缀开头(例如, google-, gemini-)。参见 智能体 ID限制 查看受限前缀的完整列表。

来自消息来源#

指定 base_agent, id, agent_config, system_instruction 和 base_environment 与来源。该平台在每次调用时都会为您的文件提供一个新的沙箱。参见 环境 适用于可用的源类型(Git、GCS、内联)。

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

agent = client.agents.create(
    id="data-analyst",
    base_agent="antigravity-preview-09-2026",
    agent_config={
        "type": "antigravity",
        "model": "gemini-4-hydrogen",
    },
    system_instruction="You are a data analyst. Always include visualizations and export results as PDF.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "inline",
                "target": ".agents/AGENTS.md",
                "content": "Always use matplotlib for charts. Include a summary table in every report.",
            },
            {
                "type": "inline",
                "target": ".agents/skills/slide-maker/SKILL.md",
                "content": "---\nname: slide-maker\n---\n# Slide Maker\nCreate HTML slide decks from data analysis results.",
            },
            {
                "type": "repository",
                "source": "https://github.com/my-org/analysis-templates",
                "target": "/workspace/templates",
            },
        ],
    },
)

print(f"Created agent: {agent.id}")

来自现有环境(fork)#

使用基础 Antigravity 智能体进行迭代,直到环境合适(已安装软件包、文件就位),然后将其分叉为托管智能体。

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

# Step 1: set up the environment interactively
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Install pandas, matplotlib, and seaborn. Create an analysis template at /workspace/template.py.",
    environment="remote",
)

# Step 2: fork that environment into a managed agent

agent = client.agents.create(
    id="my-data-analyst",
    base_agent="antigravity-preview-09-2026",
    system_instruction="You are a data analyst. Use the template at /workspace/template.py for all reports.",
    base_environment=interaction.environment_id,
)

print(f"Forked agent successfully: {agent.id}")

有网络规则 #

您可以在保存托管智能体时锁定出站访问或注入凭据。有关完整的白名单架构、凭证模式和通配符,请参阅 环境:网络配置.

引用存储的 凭证 按允许名单规则上的 ID ("credential": "github-production")并且出口代理在请求时注入秘密,因此它永远不会落在您的智能体定义中。此示例将标头设置为内联 transform 反而。代理以相同的方式应用这两种形式,凭证还允许您在智能体上重复使用秘密并将其轮换到一个地方。

以下示例创建一个 issue-resolver 智能体只能访问 GitHub 和 PyPI,并为 GitHub 注入凭据:

python
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

agent = client.agents.create(
    id="issue-resolver",
    base_agent="antigravity-preview-09-2026",
    system_instruction="You resolve GitHub issues. Clone the repo, find the bug, write the fix, run the tests, and open a PR.",
    base_environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/my-org/backend",
                "target": "/workspace/repo",
            }
        ],
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Basic YOUR_BASE64_TOKEN"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

print(f"Created issue-resolver agent successfully: {agent.id}")

调用智能体#

通过创建新的交互,使用您的智能体 ID 呼叫您的托管智能体。每次调用都会分叉基本环境,因此每次运行都是干净的。

python
result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data from /workspace/templates/sample.csv and create a slide deck.",
    environment="remote",
)

print(result.output_text)

覆盖调用时的配置#

您可以覆盖智能体的默认值 system_instruction, tools, 和 environment 创建交互时的网络配置。这可以让您修改智能体特定运行的行为、功能或凭据,而不更改存储的智能体定义。

覆盖系统指令和工具#

python
result = client.interactions.create(
    agent="data-analyst",
    input="Analyze Q1 revenue data, but do not create a slide deck. Just output a summary table.",
    system_instruction="You are a data analyst. Focus ONLY on summary tables. Ignore default instructions about slides.",
    tools=[{"type": "code_execution"}], # Override to only use code execution
    environment="remote",
)
print(result.output_text)

覆盖网络配置(刷新凭据) #

如果您的托管智能体中包含网络凭据 base_environment,您可以在调用时覆盖它们以刷新过期的 token 或轮换 API 密钥。通过一个 environment 对象有一个新的 network 配置。新的网络规则完全取代了之前的交互规则。保留基础环境的源(文件、存储库)。

如果 base_environment 引用存储的 凭证 您无需覆盖任何内容,而不是内联 token。使用 a 轮换凭证 PATCH 每个引用它的智能体都会在下一次运行时获取新的秘密。

python
# Invoke the agent with a fresh token, overriding the base_environment credentials
result = client.interactions.create(
    agent="issue-resolver",
    input="Fix issue #42 and open a PR.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {
                    "domain": "api.github.com",
                    "transform": {
                        "Authorization": "Bearer ghp_REFRESHED_TOKEN"
                    },
                },
                {"domain": "pypi.org"},
            ]
        },
    },
)

print(result.output_text)

管理智能体#

您可以列出、获取和删除智能体。

列表智能体#

python
agents = client.agents.list()
for a in agents.agents:
    print(f"{a.id}: {a.description}")

获取智能体#

python
agent = client.agents.get(id="data-analyst")
print(agent)

删除智能体#

删除会删除配置。 智能体创建的现有环境和交互不受影响。

python
client.agents.delete(id="data-analyst")

智能体定义参考#

领域类型必填说明
id字符串是的Google Cloud 项目中唯一的智能体标识符。用于调用智能体。不得使用保留前缀。看 智能体 ID限制.
description字符串否智能体的人类可读描述。
base_agent字符串是的基本智能体 ID(例如, antigravity-preview-09-2026).
agent_config对象否基础智能体的配置,包括型号选择({"type": "antigravity", "model": "gemini-4-hydrogen"})。默认为 gemini-4-hydrogen 如果省略。无法在名为智能体的交互时被覆盖。
system_instruction字符串否系统提示定义行为和角色。
tools数组否智能体可以使用的工具。如果省略,则默认为 code_execution, google_search, 和 url_context。支持的工具包括 code_execution, google_search, url_context, mcp_server,和定制 function 定义。
base_environment字符串或对象否"remote", 一个 environment_id,或者一个配置对象 sources 和 network。请参阅环境。

智能体 ID限制 #

创建托管智能体时, id 您指定必须遵循以下规则:

  • 它对于您的 Google Cloud 项目必须是唯一的。
  • 它必须 不 以以下任意保留前缀开头(不区分大小写),否则创建将失败:* antigravity-
    • veo-
    • omni-
    • lyria-
    • imagen-
    • gemma-
    • gemini-
    • google-
    • youtube-
    • android-
    • chrome-
    • pixel-
    • waze-
    • fitbit-
    • nest-
    • kaggle-

迭代工作流程 #

  1. 原型 与底座 Antigravity 智能体。内联传递系统指令和环境源。以交互方式测试说明、技能和环境设置。
  2. 稳定 环境。安装软件包,安装源,验证一切正常。
  3. 坚持 通过从源或分叉环境创建新的智能体作为托管智能体。
  4. 更新 智能体定义。更改系统指令、交换技能或添加来源。下一次调用将采用新配置。

限制 #

  • 预览状态:托管智能体处于预览状态。功能和架构可能会发生变化。
  • 基础智能体和型号:仅 antigravity-preview-09-2026 支持为 base_agent。支持的型号选项 agent_config 是 gemini-4-hydrogen (默认), gemini-4-carbon, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash, 和 gemini-3.5-flash-lite。对于名为智能体的模型,无法在交互时覆盖该模型。
  • 无版本控制:智能体版本控制和回滚尚不可用。
  • 无子智能体嵌套:尚不支持子智能体委托。
  • 您最多可以拥有 1000 托管智能体。

后续步骤 #

搜索标题、API 名称或正文内容