Gemini 中文指南
获取 API 密钥 ↗

托管智能体的凭据

↓ 下载 MarkdownInteractions API

凭证是服务器管理的机密,可让您的智能体访问第三方服务,而无需机密进入智能体的环境。您存储凭证一次,通过 ID 引用它,然后出口代理会在请求时解析并注入它。

秘密值是只写的。一旦存储,它们就不会被任何端点返回,因此受损的智能体无法读回它正在使用的 token。

您使用凭据的主要位置是网络白名单 environment.network。首先存储秘密:

py
from google import genai

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

credential = client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

print(f"Credential ID: {credential.id}, Status: {credential.status}")

然后将其附加到它验证的域:

py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Triage the open issues in my-org/my-repo.",
    environment={
        "type": "remote",
        "network": {
            "allowlist": [
                {"domain": "api.github.com", "credential": "github-production"},
                {"domain": "*"},
            ]
        },
    },
)

智能体现在发出经过身份验证的请求 api.github.com,并且 token 永远不会存在于沙箱内。

凭证类型 #

每个凭证都有一个 type 这决定了它接受哪些字段以及代理如何应用它。

类型使用案例行为
bearer_token个人访问 token、机器人 token、静态 API 密钥代理注入 token 作为请求标头。没有刷新逻辑。
oauth2OAuth 应用程序和用户委托流代理将刷新 token 交换为访问 token,并在它们过期时刷新它们。
environment_variable从流程环境读取机密的客户端 SDK智能体的环境接收一个占位符。代理替换出站请求上的真实机密。

使用网络白名单中的凭据 #

添加 credential 到允许列表规则,并且代理验证对该域的每个出站请求。这是授予智能体访问私有 API、私有存储库或私有存储桶的推荐方法。

您可以在同一允许列表中混合经过身份验证和未经身份验证的规则:

py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Sync the open Jira issues into the tracking sheet in my repo.",
    environment={
        "type": "remote",
        "sources": [
            {
                "type": "repository",
                "source": "https://github.com/your-org/backend",
                "target": "/backend-app",
            }
        ],
        "network": {
            "allowlist": [
                {"domain": "github.com", "credential": "github-production"},
                {"domain": "api.atlassian.com", "credential": "jira-oauth"},
                {"domain": "*.googleapis.com"},
            ]
        },
    },
)

由于代理会解析每个请求的凭据,因此 oauth2 凭证透明地刷新其访问 token。当访问 token 过期时,长时间运行的交互不会中断。

组合 credential 和 transform #

允许列表规则也接受内联 transform 直接在规则上设置标题的对象。这两种机制均由线路上的出口代理应用,因此在这两种情况下,标头值永远不会存在于沙箱内。这两个字段可以出现在同一条规则中。

规则配置行为
credential 仅代理解析凭据并将其标头注入到域的每个请求中。
transform 仅静态标头注入。您编写的标头将按原样发送。
两者都首先应用凭证,然后 transform 合并在顶部。明确的 transform 如果两者设置相同的密钥,则 header 获胜。
两者都没有允许该域,并且不会注入任何标头。

当您想要存储一次机密并从项目中的每个环境、智能体和触发器引用它时,以及当您想要访问为您处理的 token 刷新和旋转时,值得使用凭证。内联 transform 当该值属于单个调用时适合,例如您在创建交互之前自己生成的 token。

将两者结合起来是很常见的。凭证携带身份验证标头和 transform 添加上游服务对同一请求期望的其他内容:

json
{
    "domain": "api.atlassian.com",
    "credential": "jira-oauth",
    "transform": {
        "X-Atlassian-Workspace": "my-workspace-id"
    }
}

将秘密移出内联 transform 并存入凭证,将其存储为 POST /credentials,替换 auth 标头 transform 使用 "credential": "<id>",并留下其余的 transform 单独对象。

将凭证与 MCP 服务器一起使用 #

远程MCP服务器采取相同的 credential 场。将其设置在 mcp_server 工具和代理将 auth 标头注入到对该服务器的每个请求中:

py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Create a new issue in my-org/my-repo",
    environment="remote",
    tools=[{
        "type": "mcp_server",
        "name": "github",
        "url": "https://api.githubcopilot.com/mcp",
        "credential": "github-production",
    }],
)

credential 和 headers 遵循与白名单相同的优先规则。首先应用凭证,然后 headers 合并在顶部,因此如果两者设置相同的键,则显式标头获胜:

json
{
    "type": "mcp_server",
    "name": "jira",
    "url": "https://jira.atlassian.com/mcp",
    "credential": "jira-oauth",
    "headers": {
        "X-Atlassian-Workspace": "my-workspace-id"
    }
}

将秘密移出内联 headers 并存入凭证,将其存储为 POST /credentials 并替换 auth 条目 headers 使用 credential。将其他标题保留在原来的位置。

使用凭据作为环境变量 #

某些客户端库从进程环境中读取机密,而不是接受它们作为请求标头。套接字模式和长轮询客户端是常见情况。

绑定一个 environment_variable 下变量名的凭证 environment.env:

py
interaction = client.interactions.create(
    agent="antigravity-preview-09-2026",
    input="Run the sync script and check notifications.",
    environment={
        "type": "remote",
        "env": {
            "NODE_ENV": "production",
            "SLACK_BOT_TOKEN": {"credential": "slack-bot-token"},
        },
    },
)

env 并排接受文字字符串和凭据引用。文字字符串作为普通的明文变量注入到容器中。

凭证参考则不然。变量接收占位符 __GEMINI_CRED_<credential-id>__,并且代理仅针对前往凭证中的域的出站请求交换真正的秘密 trusted_domains。对任何其他域的请求都会被拒绝,因此秘密永远不会离开边界,并且占位符也不会发送到其位置。

注意:文字值以纯文本形式注入,并且可由沙箱中运行的任何内容读取,包括智能体本身。使用它们进行配置,例如 NODE_ENV,不是为了秘密。秘密属于凭证,这是获得占位符和在线替换的唯一形式。

套装 trusted_domains 在每一个 environment_variable 凭证。它是对可以使用秘密的范围的控制。

创建凭证 #

每个创建请求都需要一个 type,加上该类型所需的任何字段。

直接调用REST时,所有字段名称都使用snake_case。发送驼峰命名法字段返回 400.

承载token #

只需持有token凭证 token:

py
credential = client.credentials.create(
    id="github-production",
    type="bearer_token",
    token="ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
)

响应仅返回元数据,从不返回 token:

json
{
  "id": "github-production",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-07-15T10:00:00.000000000Z"
}

默认情况下,代理发送 Authorization: Bearer <token>。覆盖 header_name 和 prefix 以期望其他内容的服务为目标:

py
credential = client.credentials.create(
    id="my-api-key",
    type="bearer_token",
    token="key_xxxxxxxxxxxx",
    header_name="x-goog-api-key",
    prefix="",
)

此配置生成标头 x-goog-api-key: key_xxxxxxxxxxxx.

下表显示了如何 header_name 和 prefix 结合:

配置注入头
{"token": "ghp_xxx"}Authorization: Bearer ghp_xxx
{"token": "sk_live_xxx"}Authorization: Bearer sk_live_xxx
{"token": "key_xxx", "header_name": "x-goog-api-key", "prefix": ""}x-goog-api-key: key_xxx
{"token": "mytoken", "header_name": "X-API-Token", "prefix": ""}X-API-Token: mytoken

OAuth2 #

OAuth2 凭证需要 client_id, client_secret, refresh_token, 和 token_url。的 scopes 字段是可选的:

py
credential = client.credentials.create(
    id="jira-oauth",
    type="oauth2",
    client_id="my-client-id",
    client_secret="my-client-secret",
    token_url="https://auth.atlassian.com/oauth/token",
    refresh_token="rt_xxxxxxxxxxxxxxxxxxxx",
    scopes=["read:jira-work", "write:jira-work"],
)

创建 OAuth2 凭证执行实时 token 交换 token_url 确认配置有效。仅当提供者返回包含以下内容的成功 token 响应时,才会存储凭证 access_token。 JSON 和表单 urlencoded 响应均被接受。

这意味着您在创建时需要有效的、未过期的刷新 token。如果提供商拒绝交换,则会向您返回错误:

json
{
  "error": {
    "message": "OAuth token validation failed with HTTP 403: {\"error\":\"unauthorized_client\",\"error_description\":\"refresh_token is invalid\"}",
    "code": "invalid_request"
  }
}

存储后,代理刷新访问权限token当它们过期时。如果提供商轮换刷新token并在刷新期间返回一个新的,新的token自动替换已存储的。

环境变量 #

安 environment_variable 凭证要求 value 和 injection_location:

py
credential = client.credentials.create(
    id="slack-bot-token",
    type="environment_variable",
    value="xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    trusted_domains=["*.slack.com", "slack.com"],
    injection_location="header",
)

该 injection_location 字段告诉代理在出站请求中的何处替换秘密。它接受 header, query, 或 body,当服务需要多个字符串时,可以作为单个字符串,也可以作为数组:

json
"injection_location": ["header", "query"]

替换仅发生在您列出的位置。在其他地方携带占位符的请求将被拒绝而不是继续发送。

要将凭证绑定到变量名称,请参阅 使用凭据作为环境变量.

生成的 ID #

该 id 字段是可选的。省略它,服务会生成一个 UUID:

json
{
  "id": "9e545973-4330-49bb-9a44-930cea9fbe3c",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-07-15T10:00:00.000000000Z"
}

当您想要在交互中使用稳定、可读的参考时,请提供您自己的 ID。由于 ID 出现在资源路径中,因此最好使用带有连字符或下划线的小写字母数字。

列出凭据 #

列出属于您的项目的凭据。使用分页参数来控制响应批量大小。

py
response = client.credentials.list(page_size=10)
for credential in response.credentials:
    print(f"Credential ID: {credential.id}, Type: {credential.type}")

响应仅包含元数据:

json
{
  "credentials": [
    {
      "id": "github-production",
      "type": "bearer_token",
      "status": "active",
      "create_time": "2026-07-15T10:00:00.000000000Z",
      "update_time": "2026-07-15T10:00:00.000000000Z"
    },
    {
      "id": "jira-oauth",
      "type": "oauth2",
      "status": "active",
      "create_time": "2026-07-15T10:05:00.000000000Z",
      "update_time": "2026-07-15T10:05:00.000000000Z"
    }
  ],
  "next_page_token": "Cj...5aE="
}

通行证 next_page_token 返回为 page_token 获取下一页。当没有进一步结果时,该字段将被省略。

参数类型说明
page_size整数每页的最大凭据数。
page_token字符串token来自 next_page_token 之前的回复。

获取凭证 #

通过 ID 检索特定凭证的元数据。

py
credential = client.credentials.get(id="github-production")
print(f"Credential ID: {credential.id}, Status: {credential.status}")

响应类似于以下内容:

json
{
  "id": "github-production",
  "type": "bearer_token",
  "status": "active",
  "create_time": "2026-07-15T10:00:00.000000000Z",
  "update_time": "2026-08-01T14:30:00.000000000Z"
}

请求不存在的凭证返回 404:

json
{
  "error": {
    "message": "Result not found.; GetCredential call failed",
    "code": "not_found"
  }
}

轮换凭证 #

替换机密而不触及引用它的任何许可名单规则、工具定义或环境变量。轮换在下一个代理解析时生效。

请求必须包括 type,加上您要更改的字段。您省略的字段保留其当前值。

旋转承载token:

py
credential = client.credentials.update(
    id="github-production",
    type="bearer_token",
    token="ghp_new_xxxxxxxxxxxxxxxxxxxx",
)

轮换 OAuth2 刷新 token:

py
credential = client.credentials.update(
    id="jira-oauth",
    type="oauth2",
    refresh_token="rt_new_xxxxxxxxxxxxxxxxxxxx",
)

响应反映了新的 update_time:

json
{
  "id": "jira-oauth",
  "type": "oauth2",
  "status": "active",
  "create_time": "2026-07-15T10:05:00.000000000Z",
  "update_time": "2026-08-01T14:30:00.000000000Z"
}

一个凭证的 type 被固定在创建时。要更改它,请删除凭据并创建一个新凭据。

删除凭证 #

当不再需要凭证及其存储的机密时,将其删除。

py
client.credentials.delete(id="github-production")

成功删除返回一个空对象:

json
{}

任何仍引用 ID 的白名单规则、工具或环境变量都将无法解析,因此请先更新它们。

现场参考 #

每个证书共有的字段:

领域类型必填说明
id字符串否唯一标识符。省略时生成为 UUID。
type字符串是的其中之一 bearer_token, oauth2, environment_variable.
status字符串只读凭证的当前状态。
create_time字符串只读RFC 3339 创建时间戳。
update_time字符串只读RFC 3339 上次更新的时间戳。

字段用于 bearer_token:

领域类型必填说明
token字符串是的只写。 token 值。
header_name字符串否要注入的标头。默认为 Authorization.
prefix字符串否值前缀。默认为 Bearer。设置为 "" 没有一个。

字段用于 oauth2:

领域类型必填说明
client_id字符串是的OAuth2 客户端 ID。
client_secret字符串是的只写。 OAuth2 客户端密钥。
refresh_token字符串是的只写。刷新token用于获取token的访问权限。
token_url字符串是的提供者 token 端点。
scopes数组否OAuth 请求范围。

字段用于 environment_variable:

领域类型必填说明
value字符串是的只写。秘密值。
injection_location字符串或数组是的哪里可以替代秘密。一项或多项 header, query, body.
trusted_domains数组否授权替换的域模式。

错误 #

错误返回一个 JSON 对象,其中包含 message 和一个 code:

json
{
  "error": {
    "message": "Credential 'github-production' already exists.; CreateCredential call failed",
    "code": "aborted"
  }
}
HTTP状态code原因
400invalid_request缺少必填字段、未知字段、不受支持 type,或 OAuth2 验证失败。
404not_found没有该 ID 的凭证。
409aborted具有该 ID 的凭证已存在。

未知字段被拒绝而不是被忽略,并且错误命名该字段:

json
{
  "error": {
    "message": "Unknown parameter 'headerName'. Did you mean 'header_name'?",
    "code": "invalid_request"
  }
}

后续步骤 #

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