Interactions API hiện đã được phát hành rộng rãi. Bạn nên sử dụng API này để truy cập vào tất cả các tính năng và mô hình mới nhất.

Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Thông tin đăng nhập trong các tác nhân được quản lý

Thông tin đăng nhập là các khoá bí mật do máy chủ quản lý, cho phép các tác nhân của bạn truy cập vào các dịch vụ của bên thứ ba mà không cần khoá bí mật truy cập vào môi trường của tác nhân. Bạn lưu trữ thông tin đăng nhập một lần, tham chiếu thông tin đó theo mã nhận dạng và proxy truyền dữ liệu sẽ phân giải và chèn thông tin đó tại thời điểm yêu cầu.

Giá trị bí mật chỉ ghi. Sau khi được lưu trữ, các mã thông báo này sẽ không bao giờ được trả về bởi bất kỳ điểm cuối nào, vì vậy, một tác nhân bị xâm nhập không thể đọc lại các mã thông báo mà tác nhân đó đang sử dụng.

Nơi chính mà bạn sử dụng thông tin đăng nhập là danh sách cho phép mạng trên environment.network. Trước tiên, hãy lưu trữ khoá bí mật:

Python

from google import genai

client = genai.Client()

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

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

JavaScript

import { GoogleGenAI } from "@google/genai";

const client = new GoogleGenAI({});

const credential = await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

Sau đó, hãy đính kèm khoá này vào miền mà khoá xác thực:

Python

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": "*"},
            ]
        },
    },
)

JavaScript

const interaction = await 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: "*" },
            ],
        },
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "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": "*" }
            ]
        }
    }
}'

Giờ đây, tác nhân sẽ đưa ra các yêu cầu đã xác thực đối với api.github.com và mã thông báo sẽ không bao giờ tồn tại trong hộp cát.

Loại thông tin xác thực

Mỗi thông tin đăng nhập đều có một type để xác định những trường mà thông tin đăng nhập đó chấp nhận và cách proxy áp dụng thông tin đăng nhập đó.

Loại	Trường hợp sử dụng	Hành vi
`bearer_token`	Mã truy cập cá nhân, mã thông báo bot, khoá API tĩnh	Proxy chèn mã thông báo dưới dạng tiêu đề của yêu cầu. Không có logic làm mới.
`oauth2`	Ứng dụng OAuth và quy trình do người dùng uỷ quyền	Proxy sẽ trao đổi mã làm mới để lấy mã truy cập và làm mới các mã này khi chúng hết hạn.
`environment_variable`	Các SDK ứng dụng đọc các khoá bí mật từ môi trường quy trình	Môi trường của nhân viên hỗ trợ sẽ nhận được một phần giữ chỗ. Proxy thay thế khoá bí mật thực trong các yêu cầu đi ra.

Sử dụng thông tin đăng nhập trong danh sách cho phép mạng

Thêm credential vào một quy tắc trong danh sách cho phép và proxy sẽ xác thực mọi yêu cầu gửi đi đến miền đó. Đây là cách được đề xuất để cấp cho một tác nhân quyền truy cập vào một API riêng tư, kho lưu trữ riêng tư hoặc vùng lưu trữ riêng tư.

Bạn có thể kết hợp các quy tắc đã xác thực và chưa xác thực trong cùng một danh sách cho phép:

Python

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"},
            ]
        },
    },
)

JavaScript

const interaction = await 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" },
            ],
        },
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "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" }
            ]
        }
    }
}'

Vì proxy phân giải thông tin đăng nhập theo từng yêu cầu, nên thông tin đăng nhập oauth2 sẽ làm mới mã truy cập một cách minh bạch. Tương tác diễn ra trong thời gian dài sẽ không bị gián đoạn khi mã truy cập hết hạn.

Kết hợp `credential` và `transform`

Các quy tắc trong danh sách cho phép cũng chấp nhận một đối tượng transform nội tuyến đặt trực tiếp các tiêu đề trên quy tắc. Cả hai cơ chế này đều được áp dụng bởi proxy truyền dữ liệu ra bên ngoài trên đường truyền, vì vậy trong cả hai trường hợp, giá trị tiêu đề không bao giờ tồn tại bên trong hộp cát. Cả hai trường đều có thể xuất hiện trên cùng một quy tắc.

Cấu hình quy tắc	Hành vi
Chỉ `credential`	Proxy sẽ phân giải thông tin đăng nhập và chèn tiêu đề của thông tin đăng nhập đó vào mọi yêu cầu gửi đến miền.
Chỉ `transform`	Chèn tiêu đề tĩnh. Các tiêu đề bạn viết sẽ được gửi nguyên trạng.
Cả hai	Thông tin đăng nhập được áp dụng trước, sau đó `transform` hợp nhất ở trên cùng. Tiêu đề `transform` rõ ràng sẽ thắng nếu cả hai đều đặt cùng một khoá.
Cả hai đều không	Miền được cho phép và không có tiêu đề nào được chèn.

Bạn nên sử dụng thông tin đăng nhập khi muốn lưu trữ một bí mật một lần và tham chiếu bí mật đó từ mọi môi trường, tác nhân và điều kiện kích hoạt trong dự án của mình, cũng như khi bạn muốn hệ thống xử lý việc làm mới và xoay vòng mã truy cập cho bạn. transform nội tuyến sẽ phù hợp khi giá trị thuộc về một lệnh gọi duy nhất, ví dụ: mã thông báo mà bạn tự tạo ngay trước khi tạo lượt tương tác.

Việc kết hợp cả hai là điều thường thấy. Thông tin đăng nhập mang theo tiêu đề xác thực và transform sẽ thêm mọi thứ khác mà dịch vụ nguồn mong đợi vào cùng một yêu cầu:

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

Để di chuyển một khoá bí mật ra khỏi transform cùng dòng và vào một thông tin đăng nhập, hãy lưu trữ khoá bí mật đó bằng POST /credentials, thay thế tiêu đề uỷ quyền trong transform bằng "credential": "<id>" và giữ nguyên phần còn lại của đối tượng transform.

Sử dụng thông tin đăng nhập với máy chủ MCP

Máy chủ MCP từ xa có cùng trường credential. Đặt trên một công cụ mcp_server và proxy sẽ chèn tiêu đề uỷ quyền vào mọi yêu cầu gửi đến máy chủ đó:

Python

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",
    }],
)

JavaScript

const interaction = await 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",
    }],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "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 và headers tuân theo cùng quy tắc ưu tiên như danh sách cho phép. Thông tin xác thực được áp dụng trước và headers hợp nhất ở trên cùng, vì vậy, tiêu đề rõ ràng sẽ thắng nếu cả hai đặt cùng một khoá:

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

Để di chuyển một khoá bí mật ra khỏi headers nội tuyến và vào một thông tin xác thực, hãy lưu trữ khoá bí mật đó bằng POST /credentials và thay thế mục nhập uỷ quyền trong headers bằng credential. Giữ nguyên các tiêu đề khác.

Sử dụng thông tin đăng nhập làm biến môi trường

Một số thư viện ứng dụng đọc các khoá bí mật từ môi trường xử lý thay vì chấp nhận các khoá đó dưới dạng tiêu đề yêu cầu. Các ứng dụng chế độ ổ cắm và ứng dụng thăm dò ý kiến trong thời gian dài là trường hợp phổ biến.

Liên kết thông tin đăng nhập environment_variable với tên biến trong environment.env:

Python

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"},
        },
    },
)

JavaScript

const interaction = await 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" },
        },
    },
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "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 chấp nhận các chuỗi ký tự và thông tin tham chiếu về thông tin đăng nhập song song. Một chuỗi ký tự được chèn vào vùng chứa dưới dạng một biến văn bản thuần tuý thông thường.

Giá trị tham chiếu thông tin đăng nhập không phải là. Biến này nhận được phần giữ chỗ __GEMINI_CRED_<credential-id>__ và chỉ khi có các yêu cầu đi đến một miền trong trusted_domains của thông tin đăng nhập thì proxy mới thay thế bằng khoá bí mật thực. Yêu cầu đến bất kỳ miền nào khác đều bị từ chối, vì vậy, khoá bí mật sẽ không bao giờ rời khỏi phạm vi và phần giữ chỗ sẽ không được gửi thay thế.

Đặt trusted_domains cho mọi thông tin đăng nhập environment_variable. Đây là chế độ kiểm soát phạm vi sử dụng bí mật.

Tạo thông tin đăng nhập

Mọi yêu cầu tạo đều cần có một type, cộng với bất kỳ trường nào mà loại đó yêu cầu.

Khi gọi REST trực tiếp, tất cả tên trường đều sử dụng snake_case. Việc gửi một trường camelCase sẽ trả về 400.

Mã thông báo truy cập

Thông tin đăng nhập bằng mã thông báo chỉ cần token:

Python

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

JavaScript

const credential = await client.credentials.create({
    id: "github-production",
    type: "bearer_token",
    token: "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "github-production",
    "type": "bearer_token",
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}'

Phản hồi chỉ trả về siêu dữ liệu, không bao giờ trả về mã thông báo:

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

Theo mặc định, proxy sẽ gửi Authorization: Bearer <token>. Ghi đè header_name và prefix để nhắm đến một dịch vụ mong đợi một điều gì đó khác:

Python

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

JavaScript

const credential = await client.credentials.create({
    id: "my-api-key",
    type: "bearer_token",
    token: "key_xxxxxxxxxxxx",
    header_name: "x-goog-api-key",
    prefix: "",
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "my-api-key",
    "type": "bearer_token",
    "token": "key_xxxxxxxxxxxx",
    "header_name": "x-goog-api-key",
    "prefix": ""
}'

Cấu hình này tạo ra tiêu đề x-goog-api-key: key_xxxxxxxxxxxx.

Bảng sau đây cho thấy cách kết hợp header_name và prefix:

Cấu hình	Tiêu đề được chèn
`{"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

Thông tin đăng nhập OAuth2 yêu cầu client_id, client_secret, refresh_token và token_url. Trường scopes là không bắt buộc:

Python

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"],
)

JavaScript

const credential = await 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"],
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "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"]
}'

Việc tạo thông tin đăng nhập OAuth2 sẽ thực hiện một hoạt động trao đổi mã thông báo trực tiếp với token_url để xác nhận rằng cấu hình hoạt động. Thông tin đăng nhập chỉ được lưu trữ nếu trình cung cấp trả về một phản hồi mã thông báo thành công có chứa access_token. Cả phản hồi JSON và phản hồi form-urlencoded đều được chấp nhận.

Điều này có nghĩa là bạn cần có một mã làm mới hợp lệ và chưa hết hạn tại thời điểm tạo. Nếu nhà cung cấp từ chối trao đổi, thì lỗi sẽ được trả về cho bạn:

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

Sau khi được lưu trữ, proxy sẽ làm mới mã truy cập khi chúng hết hạn. Nếu nhà cung cấp xoay vòng mã làm mới và trả về một mã mới trong quá trình làm mới, thì mã mới sẽ tự động thay thế mã đã lưu trữ.

Biến môi trường

Thông tin đăng nhập environment_variable yêu cầu value và injection_location:

Python

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

JavaScript

const credential = await client.credentials.create({
    id: "slack-bot-token",
    type: "environment_variable",
    value: "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    trusted_domains: ["*.slack.com", "slack.com"],
    injection_location: "header",
});

REST

curl -X POST "https://generativelanguage.googleapis.com/v1beta/credentials" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "id": "slack-bot-token",
    "type": "environment_variable",
    "value": "xoxb-xxxxxxxxxxxx-xxxxxxxxxxxx",
    "trusted_domains": ["*.slack.com", "slack.com"],
    "injection_location": "header"
}'

Trường injection_location cho biết proxy nên thay thế bí mật ở đâu trong yêu cầu đi. Thành phần này chấp nhận header, query hoặc body, dưới dạng một chuỗi duy nhất hoặc dưới dạng một mảng khi một dịch vụ cần nhiều hơn một:

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

Việc thay thế chỉ diễn ra ở những vị trí mà bạn liệt kê. Yêu cầu mang giá trị giữ chỗ ở bất kỳ nơi nào khác sẽ bị từ chối thay vì được gửi đi.

Để liên kết thông tin đăng nhập với tên biến, hãy xem phần Sử dụng thông tin đăng nhập làm biến môi trường.

Mã nhận dạng được tạo

Trường id là không bắt buộc. Bỏ qua mã này và dịch vụ sẽ tạo một mã UUID:

{
  "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"
}

Cung cấp mã nhận dạng của riêng bạn khi bạn muốn có một thông tin tham chiếu ổn định, dễ đọc để sử dụng trong các lượt tương tác. Vì mã nhận dạng xuất hiện trong đường dẫn tài nguyên, hãy ưu tiên các ký tự chữ và số viết thường có dấu gạch nối hoặc dấu gạch dưới.

Liệt kê thông tin đăng nhập

Liệt kê thông tin xác thực thuộc dự án của bạn. Sử dụng các tham số phân trang để kiểm soát kích thước lô phản hồi.

Python

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

JavaScript

const response = await client.credentials.list({ page_size: 10 });
for (const credential of response.credentials) {
    console.log(`Credential ID: ${credential.id}, Type: ${credential.type}`);
}

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials?page_size=10" \
-H "x-goog-api-key: $GEMINI_API_KEY"

Phản hồi chỉ chứa siêu dữ liệu:

{
  "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="
}

Truyền next_page_token trở lại dưới dạng page_token để tìm nạp trang tiếp theo. Trường này sẽ bị bỏ qua khi không có kết quả nào khác.

Tham số	Loại	Mô tả
`page_size`	số nguyên	Số lượng thông tin xác thực tối đa trên mỗi trang.
`page_token`	chuỗi	Mã thông báo từ `next_page_token` của một phản hồi trước đó.

Lấy thông tin đăng nhập

Truy xuất siêu dữ liệu cho một thông tin xác thực cụ thể theo mã nhận dạng của thông tin đó.

Python

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

JavaScript

const credential = await client.credentials.get("github-production");
console.log(`Credential ID: ${credential.id}, Status: ${credential.status}`);

REST

curl -X GET "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"

Phản hồi sẽ có dạng như sau:

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

Yêu cầu một thông tin đăng nhập không tồn tại sẽ trả về 404:

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

Thay đổi thông tin xác thực

Thay thế một khoá bí mật mà không ảnh hưởng đến bất kỳ quy tắc danh sách cho phép, định nghĩa công cụ hoặc biến môi trường nào tham chiếu đến khoá bí mật đó. Hướng xoay sẽ có hiệu lực vào lần phân giải proxy tiếp theo.

Yêu cầu phải có type, cộng với các trường bạn muốn thay đổi. Các trường mà bạn bỏ qua sẽ giữ nguyên giá trị hiện tại.

Xoay vòng mã thông báo của người mang:

Python

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

JavaScript

const credential = await client.credentials.update("github-production", {
    type: "bearer_token",
    token: "ghp_new_xxxxxxxxxxxxxxxxxxxx",
});

REST

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "type": "bearer_token",
    "token": "ghp_new_xxxxxxxxxxxxxxxxxxxx"
}'

Xoay vòng mã làm mới OAuth2:

Python

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

JavaScript

const credential = await client.credentials.update("jira-oauth", {
    type: "oauth2",
    refresh_token: "rt_new_xxxxxxxxxxxxxxxxxxxx",
});

REST

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/credentials/jira-oauth" \
-H "Content-Type: application/json" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-d '{
    "type": "oauth2",
    "refresh_token": "rt_new_xxxxxxxxxxxxxxxxxxxx"
}'

Phản hồi này phản ánh update_time mới:

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

type của thông tin đăng nhập được cố định khi tạo. Để thay đổi, hãy xoá thông tin đăng nhập đó rồi tạo một thông tin đăng nhập mới.

Xoá thông tin đăng nhập

Xoá thông tin đăng nhập và bí mật đã lưu trữ của thông tin đăng nhập đó khi không cần thiết nữa.

Python

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

JavaScript

await client.credentials.delete("github-production");

REST

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/credentials/github-production" \
-H "x-goog-api-key: $GEMINI_API_KEY"

Thao tác xoá thành công sẽ trả về một đối tượng trống:

{}

Mọi quy tắc, công cụ hoặc biến môi trường trong danh sách cho phép vẫn tham chiếu đến mã nhận dạng này sẽ không phân giải được, vì vậy, trước tiên hãy cập nhật những quy tắc, công cụ hoặc biến môi trường đó.

Tài liệu tham khảo về trường

Các trường chung cho mọi thông tin đăng nhập:

Trường	Loại	Bắt buộc	Mô tả
`id`	chuỗi	Không	Giá trị nhận dạng riêng biệt. Được tạo dưới dạng UUID khi bị bỏ qua.
`type`	chuỗi	Có	Một trong các giá trị `bearer_token`, `oauth2`, `environment_variable`.
`status`	chuỗi	Chỉ đọc	Trạng thái hiện tại của thông tin đăng nhập.
`create_time`	chuỗi	Chỉ đọc	Dấu thời gian tạo RFC 3339.
`update_time`	chuỗi	Chỉ đọc	Dấu thời gian RFC 3339 của lần cập nhật gần đây nhất.

Các trường cho bearer_token:

Trường	Loại	Bắt buộc	Mô tả
`token`	chuỗi	Có	Chỉ ghi. Giá trị mã thông báo.
`header_name`	chuỗi	Không	Tiêu đề cần chèn. Giá trị mặc định là `Authorization`.
`prefix`	chuỗi	Không	Tiền tố giá trị. Giá trị mặc định là `Bearer`. Đặt thành `""` nếu không có.

Các trường cho oauth2:

Trường	Loại	Bắt buộc	Mô tả
`client_id`	chuỗi	Có	Mã ứng dụng OAuth2.
`client_secret`	chuỗi	Có	Chỉ ghi. Khoá bí mật của ứng dụng OAuth2.
`refresh_token`	chuỗi	Có	Chỉ ghi. Mã làm mới dùng để lấy mã truy cập.
`token_url`	chuỗi	Có	Điểm cuối mã thông báo của nhà cung cấp.
`scopes`	mảng	Không	Các phạm vi OAuth cần yêu cầu.

Các trường cho environment_variable:

Trường	Loại	Bắt buộc	Mô tả
`value`	chuỗi	Có	Chỉ ghi. Giá trị bí mật.
`injection_location`	chuỗi hoặc mảng	Có	Vị trí thay thế khoá bí mật. Một hoặc nhiều trong số `header`, `query`, `body`.
`trusted_domains`	mảng	Không	Các mẫu miền được phép thay thế.

Lỗi

Lỗi trả về một đối tượng JSON có message và code:

{
  "error": {
    "message": "Credential 'github-production' already exists.; CreateCredential call failed",
    "code": "aborted"
  }
}

Trạng thái HTTP	`code`	Nguyên nhân
400	`invalid_request`	Thiếu trường bắt buộc, trường không xác định, `type` không được hỗ trợ hoặc xác thực OAuth2 không thành công.
404	`not_found`	Không có thông tin xác thực nào có mã nhận dạng đó.
409	`aborted`	Đã có một thông tin đăng nhập sử dụng mã nhận dạng đó.

Các trường không xác định sẽ bị từ chối thay vì bị bỏ qua và lỗi sẽ đặt tên cho trường:

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

Bước tiếp theo

Môi trường: Tìm hiểu cách các tác nhân chạy mã và duy trì tệp.
Tổng quan về tác nhân: Tìm hiểu về các khái niệm cốt lõi của tác nhân được quản lý.
Tạo tác nhân tuỳ chỉnh: Xác định tác nhân của riêng bạn bằng cách sử dụng AGENTS.md và SKILL.md.

Thông tin đăng nhập trong các tác nhân được quản lý

Python

JavaScript

REST

Python

JavaScript

REST

Loại thông tin xác thực

Sử dụng thông tin đăng nhập trong danh sách cho phép mạng

Python

JavaScript

REST

Kết hợp credential và transform

Sử dụng thông tin đăng nhập với máy chủ MCP

Python

JavaScript

REST

Sử dụng thông tin đăng nhập làm biến môi trường

Python

JavaScript

REST

Tạo thông tin đăng nhập

Mã thông báo truy cập

Python

JavaScript

REST

Python

JavaScript

REST

OAuth2

Python

JavaScript

REST

Biến môi trường

Python

JavaScript

REST

Mã nhận dạng được tạo

Liệt kê thông tin đăng nhập

Python

JavaScript

REST

Lấy thông tin đăng nhập

Python

JavaScript

REST

Thay đổi thông tin xác thực

Python

JavaScript

REST

Python

JavaScript

REST

Xoá thông tin đăng nhập

Python

JavaScript

REST

Tài liệu tham khảo về trường

Lỗi

Bước tiếp theo

Kết hợp `credential` và `transform`