保管庫會將憑證儲存在智慧體的指示和設定之外。使用 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 可建立、更新或刪除保管庫和憑證。
請準備 API 用戶端、MCP 伺服器的 URL(mcp_url),以及該伺服器的存取權杖(access_token)。以下範例使用 GitHub 工具。
首先,建立保管庫:
1
2
3
4
5
6const vault = await client.beta.agents.vaults.create({
name: "GitHub credentials",
metadata: {
external_user_id: "user_123",
},
});
1
2
3vault = client.beta.agents.vaults.create(
name="GitHub credentials", metadata={"external_user_id": "user_123"}
)
1
2
3
4
5
6
7
8vault, err := client.Beta.Agents.Vaults.New(ctx,
openai.BetaAgentVaultNewParams{
Name: openai.String("GitHub credentials"),
Metadata: map[string]string{"external_user_id": "user_123"},
})
if err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13var vault =
client
.beta()
.agents()
.vaults()
.create(
VaultCreateParams.builder()
.name("GitHub credentials")
.metadata(
VaultCreateParams.Metadata.builder()
.putAdditionalProperty("external_user_id", JsonValue.from("user_123"))
.build())
.build());
1
2
3
4vault = client.beta.agents.vaults.create(
name: "GitHub credentials",
metadata: { external_user_id: "user_123" }
)
將保管庫的 ID 儲存為 vault_id,然後新增權杖。mcp_server_url 會將憑證繫結至該伺服器:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17// 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,
},
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://api.githubcopilot.com/mcp/"
access_token = os.environ["GITHUB_TOKEN"]
credential = client.beta.agents.vaults.credentials.create(
vault_id,
name="GitHub access token",
auth={
"type": "static_bearer",
"mcp_server_url": mcp_url,
"token": access_token,
},
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19// Replace the illustrative IDs and URLs below with your own resource values.
vaultId := "vault_123"
mcpUrl := "https://api.githubcopilot.com/mcp/"
accessToken := os.Getenv("GITHUB_TOKEN")
credential, err := client.Beta.Agents.Vaults.Credentials.New(ctx,
vaultId,
openai.BetaAgentVaultCredentialNewParams{
Name: "GitHub access token",
Auth: openai.CredentialAuthCreateParamUnion{
OfParamStaticBearer: &openai.CredentialAuthCreateParamStaticBearer{
McpServerURL: mcpUrl,
Token: accessToken,
},
},
})
if err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Replace the illustrative IDs and URLs below with your own resource values.
String vaultId = "vault_123";
String mcpUrl = "https://api.githubcopilot.com/mcp/";
String accessToken = System.getenv("GITHUB_TOKEN");
var credential =
client
.beta()
.agents()
.vaults()
.credentials()
.create(
CredentialCreateParams.builder()
.vaultId(vaultId)
.name("GitHub access token")
.auth(
CredentialAuthCreateParam.StaticBearer.builder()
.mcpServerUrl(mcpUrl)
.token(accessToken)
.build())
.build());
1
2
3
4
5
6
7
8
9
10
11
12
13
14# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://api.githubcopilot.com/mcp/"
access_token = ENV.fetch("GITHUB_TOKEN")
credential = client.beta.agents.vaults.credentials.create(
vault_id,
name: "GitHub access token",
auth: {
type: "static_bearer",
mcp_server_url: mcp_url,
token: access_token
}
)
將憑證 ID 儲存為 credential_id,以便日後更新憑證。
建立工作階段時,在 vault_ids 中傳入先前儲存的保管庫 ID,並在 MCP 設定中使用相同的伺服器 URL:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// 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],
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25# Replace the illustrative IDs and URLs below with your own resource values.
mcp_url = "https://api.githubcopilot.com/mcp/"
vault_id = "vault_123"
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"tools": [
{
"type": "mcp",
"server_label": "github",
"transport": {
"type": "http",
"server_url": mcp_url,
},
"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=[vault_id],
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27// Replace the illustrative IDs and URLs below with your own resource values.
mcpUrl := "https://api.githubcopilot.com/mcp/"
vaultId := "vault_123"
session, err := client.Beta.Agents.Sessions.New(ctx,
openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Tools: []openai.AgentToolParamUnion{
{
OfParamMcp: &openai.AgentToolParamMcp{
ServerLabel: "github",
Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: mcpUrl}},
AllowedTools: []string{"search_issues", "issue_read"},
Required: openai.Bool(true),
ConnectionOrigin: "service",
},
},
},
},
Environment: openai.EnvironmentParamUnion{OfParamNone: &openai.EnvironmentParamNone{}},
Input: openai.BetaAgentSessionNewParamsInputUnion{OfString: openai.String("Find open bugs reported in the last week.")},
VaultIDs: []string{vaultId},
})
if err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29// Replace the illustrative IDs and URLs below with your own resource values.
String mcpUrl = "https://api.githubcopilot.com/mcp/";
String vaultId = "vault_123";
var session =
client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.addTool(
AgentToolParam.Mcp.builder()
.serverLabel("github")
.transport(
McpTransportParam.Http.builder().serverUrl(mcpUrl).build())
.allowedTools(List.of("search_issues", "issue_read"))
.required(true)
.connectionOrigin(
AgentToolParam.Mcp.ConnectionOrigin.of("service"))
.build())
.build())
.environmentNone()
.input("Find open bugs reported in the last week.")
.vaultIds(List.of(vaultId))
.build());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28# Replace the illustrative IDs and URLs below with your own resource values.
mcp_url = "https://api.githubcopilot.com/mcp/"
vault_id = "vault_123"
session = client.beta.agents.sessions.create(
agent: {
model: "gpt-6-astra",
tools: [
{
type: "mcp",
server_label: "github",
transport: {
type: "http",
server_url: mcp_url
},
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: [vault_id]
)
Agents API 會選取與伺服器 URL 相符的憑證。如果有多個已附加的憑證相符,請設定 MCP 工具的 credential_id 來指定其中一個。
使用 environment_variable 憑證,為 OpenAI 託管的沙盒所發出的 API 請求提供機密值。沙盒會從指定的環境變數取得預留位置,實際的機密值則保留在沙盒之外。
此流程需要 openai_hosted 環境,無法為自行託管的環境或由應用程式執行的函式工具提供憑證。
依照上述步驟建立保管庫,然後向 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:
12345678910{
"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 中重複定義該名稱。
傳送訊息給智慧體,要求它在沙盒中執行下列指令:
curl https://api.github.com/user \
-H "Authorization: Bearer $GITHUB_TOKEN"
此指令會從 GITHUB_TOKEN 讀取預留位置。代理伺服器會先將預留位置替換為實際權杖,再將請求送至 api.github.com。請求成功時,GitHub 會以 JSON 格式傳回通過驗證的使用者帳戶詳細資料。在沙盒內印出該變數時,只會看到預留位置,不會看到權杖。
請在 HTTPS 請求標頭中原樣傳入預留位置。沙盒內的程式無法透過預留位置取得實際的機密值來執行本機運算,例如為請求簽章。如需執行這類作業,請將憑證保留在應用程式中,並透過函式工具提供該作業。
由應用程式處理提供者的授權與使用者同意流程。使用 auth.type: "mcp_oauth" 儲存取得的授權資料。如果知道存取權杖的到期時間,請將 expires_at 設為該時間,格式為 RFC 3339 時間戳記。
下列範例使用從提供者的 OAuth 流程取得的值。加入 refresh 即可讓 Agents API 更新權杖:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31// 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",
},
},
},
});
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://mcp.example.com/mcp"
access_token = os.environ["OAUTH_ACCESS_TOKEN"]
expires_at = "2030-01-01T00:00:00Z"
token_endpoint = "https://auth.example.com/oauth/token"
client_id = "example-client-id"
refresh_token = os.environ["OAUTH_REFRESH_TOKEN"]
credential = client.beta.agents.vaults.credentials.create(
vault_id,
name="Example MCP OAuth credential",
auth={
"type": "mcp_oauth",
"mcp_server_url": mcp_url,
"access_token": access_token,
"expires_at": expires_at,
"refresh": {
"token_endpoint": token_endpoint,
"client_id": client_id,
"refresh_token": refresh_token,
"token_endpoint_auth": {"type": "none"},
},
},
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
vaultId := "vault_123"
mcpUrl := "https://mcp.example.com/mcp"
accessToken := os.Getenv("OAUTH_ACCESS_TOKEN")
expiresAt := "2030-01-01T00:00:00Z"
tokenEndpoint := "https://auth.example.com/oauth/token"
clientId := "example-client-id"
refreshToken := os.Getenv("OAUTH_REFRESH_TOKEN")
credential, err := client.Beta.Agents.Vaults.Credentials.New(ctx,
vaultId,
openai.BetaAgentVaultCredentialNewParams{
Name: "Example MCP OAuth credential",
Auth: openai.CredentialAuthCreateParamUnion{
OfParamMcpOAuth: &openai.CredentialAuthCreateParamMcpOAuth{
McpServerURL: mcpUrl,
AccessToken: accessToken,
ExpiresAt: openai.String(expiresAt),
Refresh: openai.CredentialAuthCreateParamMcpOAuthRefresh{
TokenEndpoint: tokenEndpoint,
ClientID: clientId,
RefreshToken: refreshToken,
TokenEndpointAuth: openai.McpOAuthTokenEndpointAuthCreateParamUnion{OfParamNone: &openai.McpOAuthTokenEndpointAuthCreateParamNone{}},
},
},
},
})
if err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
String vaultId = "vault_123";
String mcpUrl = "https://mcp.example.com/mcp";
String accessToken = System.getenv("OAUTH_ACCESS_TOKEN");
String expiresAt = "2030-01-01T00:00:00Z";
String tokenEndpoint = "https://auth.example.com/oauth/token";
String clientId = "example-client-id";
String refreshToken = System.getenv("OAUTH_REFRESH_TOKEN");
var credential =
client
.beta()
.agents()
.vaults()
.credentials()
.create(
CredentialCreateParams.builder()
.vaultId(vaultId)
.name("Example MCP OAuth credential")
.auth(
CredentialAuthCreateParam.McpOAuth.builder()
.mcpServerUrl(mcpUrl)
.accessToken(accessToken)
.expiresAt(expiresAt)
.refresh(
CredentialAuthCreateParam.McpOAuth.Refresh.builder()
.tokenEndpoint(tokenEndpoint)
.clientId(clientId)
.refreshToken(refreshToken)
.tokenEndpointAuthNone()
.build())
.build())
.build());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
vault_id = "vault_123"
mcp_url = "https://mcp.example.com/mcp"
access_token = ENV.fetch("OAUTH_ACCESS_TOKEN")
expires_at = "2030-01-01T00:00:00Z"
token_endpoint = "https://auth.example.com/oauth/token"
client_id = "example-client-id"
refresh_token = ENV.fetch("OAUTH_REFRESH_TOKEN")
credential = client.beta.agents.vaults.credentials.create(
vault_id,
name: "Example MCP OAuth credential",
auth: {
type: "mcp_oauth",
mcp_server_url: mcp_url,
access_token: access_token,
expires_at: expires_at,
refresh: {
token_endpoint: token_endpoint,
client_id: client_id,
refresh_token: refresh_token,
token_endpoint_auth: { type: "none" }
}
}
)
請使用提供者要求的權杖端點驗證方式。範例使用 none,Agents API 也支援 client_secret_basic 和 client_secret_post。如需瞭解各欄位,請參閱建立憑證的 API 參考文件。
如果無法更新已到期的權杖,請提供有效的新權杖。權杖到期時,系統不會刪除憑證或其所屬的保管庫。
更新憑證即可替換其機密值,並保留原有的 ID 和驗證類型。如果是 MCP 憑證,伺服器 URL 也會維持不變。如果是 OAuth 憑證,請使用先前儲存的 vault_id 和 credential_id,並提供新權杖及其到期時間:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20// 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,
},
},
}
);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
credential_id = "cred_123"
vault_id = "vault_123"
access_token = os.environ["OAUTH_ACCESS_TOKEN"]
expires_at = "2030-01-01T00:00:00Z"
credential = client.beta.agents.vaults.credentials.update(
credential_id,
vault_id=vault_id,
auth={
"type": "mcp_oauth",
"access_token": access_token,
"expires_at": expires_at,
},
)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
vaultId := "vault_123"
credentialId := "cred_123"
accessToken := os.Getenv("OAUTH_ACCESS_TOKEN")
expiresAt := "2030-01-01T00:00:00Z"
credential, err := client.Beta.Agents.Vaults.Credentials.Update(ctx,
vaultId,
credentialId,
openai.BetaAgentVaultCredentialUpdateParams{
Auth: openai.CredentialAuthRotateParamUnion{
OfParamMcpOAuth: &openai.CredentialAuthRotateParamMcpOAuth{
AccessToken: openai.String(accessToken),
ExpiresAt: openai.String(expiresAt),
},
},
})
if err != nil {
panic(err)
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23// Replace the illustrative expiry with your access token's actual expiry.
// Replace the illustrative IDs and URLs below with your own resource values.
String credentialId = "cred_123";
String vaultId = "vault_123";
String accessToken = System.getenv("OAUTH_ACCESS_TOKEN");
String expiresAt = "2030-01-01T00:00:00Z";
var credential =
client
.beta()
.agents()
.vaults()
.credentials()
.update(
CredentialUpdateParams.builder()
.credentialId(credentialId)
.vaultId(vaultId)
.auth(
CredentialAuthRotateParam.McpOAuth.builder()
.accessToken(accessToken)
.expiresAt(expiresAt)
.build())
.build());
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16# Replace the illustrative expiry with your access token's actual expiry.
# Replace the illustrative IDs and URLs below with your own resource values.
credential_id = "cred_123"
vault_id = "vault_123"
access_token = ENV.fetch("OAUTH_ACCESS_TOKEN")
expires_at = "2030-01-01T00:00:00Z"
credential = client.beta.agents.vaults.credentials.update(
credential_id,
vault_id: vault_id,
auth: {
type: "mcp_oauth",
access_token: access_token,
expires_at: expires_at
}
)
如果新權杖有到期時間,請一併提供 expires_at。提供新的存取權杖但省略到期時間,會清除已儲存的到期時間。明確指定 null 也會將其清除。
如果是環境變數憑證,請將 auth.type: "environment_variable" 和新的 auth.secret_value 傳送至 POST /v1/vaults/{vault_id}/credentials/{credential_id}。請建立新的工作階段以使用新值。更新保管庫不會變更現有沙盒中已設定的憑證。
如需變更 secret_name 或 networking,請建立新的憑證。
刪除憑證可移除不再需要的憑證。刪除保管庫會一併移除保管庫及其中的所有憑證。
刪除已儲存的憑證不會撤銷提供者核發的原始權杖,也不會停止執行中的工作階段。應用程式負責向提供者撤銷權杖,以及取消工作階段。