如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

保管庫

儲存 MCP 連線或沙盒發出請求時所需的機密值。

保管庫會將憑證儲存在智慧體的指示和設定之外。使用 vault_ids 將保管庫附加至工作階段,該工作階段即可使用其中的憑證。

請依發出請求的位置選擇憑證類型:

請求 憑證類型 工作階段如何使用憑證
OpenAI 發起的 MCP 連線 static_bearer 或 mcp_oauth OpenAI 使用憑證向指定的 MCP 伺服器驗證身分。
OpenAI 託管的沙盒發出的 API 請求 environment_variable 程式碼使用含有預留位置的環境變數。當請求送往已核准的主機時,網路代理伺服器會將預留位置替換為機密值。

例如,沙盒可以使用保管庫中的機密值呼叫 GitHub REST API。請依照使用保管庫中的機密值從沙盒發出 API 請求一節的步驟操作。

擷取保管庫或憑證時,API 不會傳回其中的機密值。如需瞭解其他 MCP 連線的驗證方式,請參閱 MCP 驗證選項。

權限

如果使用權限受限的應用程式金鑰,請授予下列權限:

  • api.vaults.read 可列出及擷取保管庫和憑證。
  • api.vaults.write 可建立、更新或刪除保管庫和憑證。

建立並使用保管庫來管理 MCP 機密值

請準備 API 用戶端、MCP 伺服器的 URL(mcp_url),以及該伺服器的存取權杖(access_token)。以下範例使用 GitHub 工具。

首先,建立保管庫:

建立保管庫
const vault = await client.beta.agents.vaults.create({
  name: "GitHub credentials",
  metadata: {
    external_user_id: "user_123",
  },
});

將保管庫的 ID 儲存為 vault_id,然後新增權杖。mcp_server_url 會將憑證繫結至該伺服器:

儲存 Bearer 權杖
// Replace the illustrative IDs and URLs below with your own resource values.
const vaultId = "vault_123";
const mcpUrl = "https://api.githubcopilot.com/mcp/";
const accessToken = process.env.GITHUB_TOKEN;

if (!accessToken) {
  throw new Error("Set GITHUB_TOKEN");
}

const credential = await client.beta.agents.vaults.credentials.create(vaultId, {
  name: "GitHub access token",
  auth: {
    type: "static_bearer",
    mcp_server_url: mcpUrl,
    token: accessToken,
  },
});

將憑證 ID 儲存為 credential_id,以便日後更新憑證。

建立工作階段時,在 vault_ids 中傳入先前儲存的保管庫 ID,並在 MCP 設定中使用相同的伺服器 URL:

將保管庫附加至工作階段
// Replace the illustrative IDs and URLs below with your own resource values.
const mcpUrl = "https://api.githubcopilot.com/mcp/";
const vaultId = "vault_123";

const session = await client.beta.agents.sessions.create({
  agent: {
    model: "gpt-6-astra",
    tools: [
      {
        type: "mcp",
        server_label: "github",
        transport: {
          type: "http",
          server_url: mcpUrl,
        },
        allowed_tools: ["search_issues", "issue_read"],
        required: true,
        connection_origin: "service",
      },
    ],
  },
  environment: {
    type: "none",
  },
  input: "Find open bugs reported in the last week.",
  vault_ids: [vaultId],
});

Agents API 會選取與伺服器 URL 相符的憑證。如果有多個已附加的憑證相符,請設定 MCP 工具的 credential_id 來指定其中一個。

使用保管庫中的機密值從沙盒發出 API 請求

使用 environment_variable 憑證,為 OpenAI 託管的沙盒所發出的 API 請求提供機密值。沙盒會從指定的環境變數取得預留位置,實際的機密值則保留在沙盒之外。

此流程需要 openai_hosted 環境,無法為自行託管的環境或由應用程式執行的函式工具提供憑證。

儲存 API 權杖

依照上述步驟建立保管庫,然後向 POST /v1/vaults/{vault_id}/credentials 傳送包含下列欄位的請求,以建立憑證:

欄位 GitHub API 權杖的設定值
name GitHub API token
auth.type environment_variable
auth.secret_name GITHUB_TOKEN
auth.secret_value 從應用程式中存放機密值的環境變數讀取的權杖。
auth.networking.type limited
auth.networking.allowed_hosts ["api.github.com"]

secret_name 指定沙盒程式碼要讀取的環境變數名稱。secret_value 是實際的憑證值。請勿將此值寫入提示詞、原始碼檔案或記錄中。

在 allowed_hosts 中填入確切的主機名稱,不要包含通訊協定、路徑、連接埠或萬用字元。代理伺服器只會將機密值提供給使用連接埠 443 或 8443 的 HTTPS 目的地。

將保管庫附加至託管的工作階段

請將下列欄位與 agent 放在同一層級,一併用於建立工作階段。將 vault_123 替換為 API 傳回的保管庫 ID:

{
  "vault_ids": ["vault_123"],
  "environment": {
    "type": "openai_hosted",
    "network": {
      "access": "restricted",
      "allowed_domains": ["api.github.com"]
    }
  }
}

這兩份主機清單各有用途。allowed_domains 指定沙盒可連線的主機。憑證的 allowed_hosts 指定代理伺服器可向哪些主機提供該憑證的機密值。

如果網路存取受限,請將每個憑證所指定的所有主機都列入 allowed_domains。如果工作階段使用環境變數憑證,請勿將 network.access 設為 disabled。

每個附加的環境變數憑證都必須使用不同的 secret_name。請勿在 environment.env 中重複定義該名稱。

從沙盒呼叫 API

傳送訊息給智慧體,要求它在沙盒中執行下列指令:

curl https://api.github.com/user \
  -H "Authorization: Bearer $GITHUB_TOKEN"

此指令會從 GITHUB_TOKEN 讀取預留位置。代理伺服器會先將預留位置替換為實際權杖,再將請求送至 api.github.com。請求成功時,GitHub 會以 JSON 格式傳回通過驗證的使用者帳戶詳細資料。在沙盒內印出該變數時,只會看到預留位置,不會看到權杖。

請在 HTTPS 請求標頭中原樣傳入預留位置。沙盒內的程式無法透過預留位置取得實際的機密值來執行本機運算,例如為請求簽章。如需執行這類作業,請將憑證保留在應用程式中,並透過函式工具提供該作業。

使用 OAuth 憑證

由應用程式處理提供者的授權與使用者同意流程。使用 auth.type: "mcp_oauth" 儲存取得的授權資料。如果知道存取權杖的到期時間,請將 expires_at 設為該時間,格式為 RFC 3339 時間戳記。

下列範例使用從提供者的 OAuth 流程取得的值。加入 refresh 即可讓 Agents API 更新權杖:

儲存 OAuth 授權資料
// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
const vaultId = "vault_123";
const mcpUrl = "https://mcp.example.com/mcp";
const accessToken = process.env.OAUTH_ACCESS_TOKEN;
const expiresAt = "2030-01-01T00:00:00Z";
const tokenEndpoint = "https://auth.example.com/oauth/token";
const clientId = "example-client-id";
const refreshToken = process.env.OAUTH_REFRESH_TOKEN;

if (!accessToken || !refreshToken) {
  throw new Error("Set OAUTH_ACCESS_TOKEN and OAUTH_REFRESH_TOKEN");
}

const credential = await client.beta.agents.vaults.credentials.create(vaultId, {
  name: "Example MCP OAuth credential",
  auth: {
    type: "mcp_oauth",
    mcp_server_url: mcpUrl,
    access_token: accessToken,
    expires_at: expiresAt,
    refresh: {
      token_endpoint: tokenEndpoint,
      client_id: clientId,
      refresh_token: refreshToken,
      token_endpoint_auth: {
        type: "none",
      },
    },
  },
});

請使用提供者要求的權杖端點驗證方式。範例使用 none,Agents API 也支援 client_secret_basic 和 client_secret_post。如需瞭解各欄位,請參閱建立憑證的 API 參考文件。

如果無法更新已到期的權杖,請提供有效的新權杖。權杖到期時,系統不會刪除憑證或其所屬的保管庫。

輪替或移除憑證

更新憑證即可替換其機密值,並保留原有的 ID 和驗證類型。如果是 MCP 憑證,伺服器 URL 也會維持不變。如果是 OAuth 憑證,請使用先前儲存的 vault_id 和 credential_id,並提供新權杖及其到期時間:

輪替 OAuth 權杖
// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
const credentialId = "cred_123";
const vaultId = "vault_123";
const accessToken = process.env.OAUTH_ACCESS_TOKEN;
const expiresAt = "2030-01-01T00:00:00Z";

const credential = await client.beta.agents.vaults.credentials.update(
  credentialId,
  {
    vault_id: vaultId,
    ...{
      auth: {
        type: "mcp_oauth",
        access_token: accessToken,
        expires_at: expiresAt,
      },
    },
  }
);

如果新權杖有到期時間,請一併提供 expires_at。提供新的存取權杖但省略到期時間,會清除已儲存的到期時間。明確指定 null 也會將其清除。

如果是環境變數憑證,請將 auth.type: "environment_variable" 和新的 auth.secret_value 傳送至 POST /v1/vaults/{vault_id}/credentials/{credential_id}。請建立新的工作階段以使用新值。更新保管庫不會變更現有沙盒中已設定的憑證。

如需變更 secret_name 或 networking,請建立新的憑證。

刪除憑證可移除不再需要的憑證。刪除保管庫會一併移除保管庫及其中的所有憑證。

刪除已儲存的憑證不會撤銷提供者核發的原始權杖,也不會停止執行中的工作階段。應用程式負責向提供者撤銷權杖,以及取消工作階段。