Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

Tresore

Speichere Secrets für MCP-Verbindungen oder für Anfragen aus der Sandbox.

In einem Tresor speicherst du Zugangsdaten getrennt von den Anweisungen und der Konfiguration deines Agenten. Verknüpfe den Tresor über vault_ids mit einer Sitzung, damit die Sitzung diese Zugangsdaten verwenden kann.

Wähle den Typ der Zugangsdaten danach aus, wo die Anfrage ausgeführt wird.

Anfrage Typ der Zugangsdaten So verwendet die Sitzung die Zugangsdaten
MCP-Verbindung von OpenAI static_bearer oder mcp_oauth OpenAI authentifiziert sich beim konfigurierten MCP-Server.
API-Anfrage aus einer von OpenAI gehosteten Sandbox environment_variable Der Code verwendet eine Umgebungsvariable, die einen Platzhalter enthält. Bei Anfragen an zugelassene Hosts ersetzt ein Netzwerkproxy den Platzhalter durch das Secret.

Eine Sandbox kann beispielsweise mit einem Secret aus einem Tresor die REST-API von GitHub aufrufen. Folge dazu der Anleitung Secrets aus einem Tresor für API-Anfragen aus einer Sandbox verwenden.

Wenn du einen Tresor oder einen Zugangsdaten-Eintrag abrufst, gibt die API die darin gespeicherten Secrets nicht zurück. Weitere Informationen zu anderen MCP-Verbindungen findest du im Abschnitt Authentifizierungsoptionen für MCP.

Berechtigungen

Erteile einem Anwendungsschlüssel mit eingeschränkten Berechtigungen die folgenden Rechte.

  • api.vaults.read zum Auflisten und Abrufen von Tresoren und Zugangsdaten.
  • api.vaults.write zum Erstellen, Aktualisieren oder Löschen von Tresoren und Zugangsdaten.

Einen Tresor für MCP-Secrets erstellen und verwenden

Du benötigst deinen API-Client, die URL des MCP-Servers (mcp_url) und ein Zugriffstoken für diesen Server (access_token). Die Beispiele verwenden GitHub-Tools.

Erstelle zuerst einen Tresor.

Tresor erstellen
const vault = await client.beta.agents.vaults.create({
  name: "GitHub credentials",
  metadata: {
    external_user_id: "user_123",
  },
});

Speichere die ID des Tresors als vault_id und füge dann das Token hinzu. Über mcp_server_url bindest du die Zugangsdaten an diesen Server.

Bearer-Token speichern
// 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,
  },
});

Speichere die ID des Zugangsdaten-Eintrags als credential_id, damit du ihn später aktualisieren kannst.

Übergib die gespeicherte Tresor-ID beim Erstellen einer Sitzung in vault_ids. Verwende in der MCP-Konfiguration dieselbe Server-URL.

Tresor mit einer Sitzung verknüpfen
// 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],
});

Die Agents API wählt einen Zugangsdaten-Eintrag aus, der zur Server-URL passt. Wenn mehrere mit der Sitzung verknüpfte Einträge passen, lege über credential_id in der Konfiguration des MCP-Tools fest, welchen Eintrag es verwenden soll.

Secrets aus einem Tresor für API-Anfragen aus einer Sandbox verwenden

Verwende Zugangsdaten vom Typ environment_variable, um ein Secret für API-Anfragen aus einer von OpenAI gehosteten Sandbox bereitzustellen. Die Sandbox erhält in der angegebenen Umgebungsvariablen einen Platzhalter. Das eigentliche Secret bleibt außerhalb der Sandbox.

Dafür ist eine Umgebung vom Typ openai_hosted erforderlich. Selbst gehostete Umgebungen und Funktionstools, die deine Anwendung ausführt, erhalten auf diesem Weg keine Zugangsdaten.

API-Token speichern

Erstelle wie oben beschrieben einen Tresor. Sende dann eine Anfrage zum Erstellen eines Zugangsdaten-Eintrags an POST /v1/vaults/{vault_id}/credentials. Gib die folgenden Felder an.

Feld Wert für ein GitHub-API-Token
name GitHub API token
auth.type environment_variable
auth.secret_name GITHUB_TOKEN
auth.secret_value Das Token, das deine Anwendung aus einer geheimen Umgebungsvariablen liest.
auth.networking.type limited
auth.networking.allowed_hosts ["api.github.com"]

secret_name bezeichnet die Umgebungsvariable, die der Code in der Sandbox ausliest. secret_value enthält das tatsächliche Token. Achte darauf, dass dieser Wert weder in Prompts noch in Quelldateien oder Protokollen auftaucht.

Gib in allowed_hosts die exakten Hostnamen ohne Schema, Pfad, Port oder Platzhalterzeichen an. Der Proxy übermittelt Secrets ausschließlich an HTTPS-Ziele auf Port 443 oder 8443.

Tresor mit einer gehosteten Sitzung verknüpfen

Gib zusätzlich zu agent die folgenden Felder an, wenn du eine Sitzung erstellst. Ersetze vault_123 durch die Tresor-ID, die die API zurückgegeben hat.

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

Die beiden Hostlisten haben unterschiedliche Aufgaben. allowed_domains legt fest, zu welchen Hosts die Sandbox eine Verbindung herstellen darf. Mit allowed_hosts im Zugangsdaten-Eintrag legst du fest, an welche Hosts der Proxy das Secret übermitteln darf.

Bei eingeschränktem Netzwerkzugriff muss allowed_domains jeden Host aus den Hostlisten der verknüpften Zugangsdaten-Einträge enthalten. Setze network.access für eine Sitzung mit Zugangsdaten für Umgebungsvariablen nicht auf disabled.

Jeder mit der Sitzung verknüpfte Zugangsdaten-Eintrag für eine Umgebungsvariable muss einen eindeutigen Wert für secret_name haben. Definiere diesen Namen nicht zusätzlich in environment.env.

API aus der Sandbox aufrufen

Sende dem Agenten eine Nachricht und bitte ihn, den folgenden Befehl in der Sandbox auszuführen.

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

Der Befehl liest den Platzhalter aus GITHUB_TOKEN. Der Proxy ersetzt ihn durch das tatsächliche Token, bevor er die Anfrage an api.github.com sendet. Bei Erfolg enthält die Antwort die Daten des authentifizierten GitHub-Kontos im JSON-Format. Wenn du den Wert der Variablen in der Sandbox ausgibst, siehst du nur den Platzhalter.

Übergib den Platzhalter unverändert im Header der HTTPS-Anfrage. Für lokale Berechnungen, etwa zum Signieren einer Anfrage, lässt sich das tatsächliche Secret über den Platzhalter nicht abrufen. Bewahre die Zugangsdaten für solche Aufgaben in deiner Anwendung auf und stelle den Vorgang über ein Funktionstool bereit.

OAuth-Zugangsdaten verwenden

Deine Anwendung übernimmt den Autorisierungs- und Zustimmungsprozess des Anbieters. Speichere die erteilte Zugriffsberechtigung mit auth.type: "mcp_oauth". Wenn du den Ablaufzeitpunkt des Zugriffstokens kennst, gib ihn in expires_at als Zeitstempel gemäß RFC 3339 an.

Das folgende Beispiel verwendet Werte aus dem OAuth-Ablauf deines Anbieters. Gib refresh an, damit die Agents API das Token erneuern kann.

OAuth-Zugriffsberechtigung speichern
// 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",
      },
    },
  },
});

Verwende am Token-Endpunkt die Authentifizierungsmethode, die dein Anbieter vorgibt. Das Beispiel verwendet none. Die API unterstützt auch client_secret_basic und client_secret_post. Die Felder sind in der API-Referenz zum Erstellen von Zugangsdaten beschrieben.

Wenn sich ein abgelaufenes Token nicht erneuern lässt, ersetze es durch ein gültiges Token. Der Zugangsdaten-Eintrag und sein Tresor bleiben nach Ablauf des Tokens erhalten.

Zugangsdaten austauschen oder entfernen

Aktualisiere einen Zugangsdaten-Eintrag, um sein Secret auszutauschen. Dabei bleiben die ID und der Authentifizierungstyp erhalten. Bei MCP-Zugangsdaten bleibt auch die Server-URL gleich. Gib bei OAuth die gespeicherten Werte für vault_id und credential_id zusammen mit dem neuen Token und dessen Ablaufzeitpunkt an.

OAuth-Token austauschen
// 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,
      },
    },
  }
);

Wenn das neue Token einen Ablaufzeitpunkt hat, gib expires_at an. Übergibst du ein neues Zugriffstoken ohne Ablaufzeitpunkt, löscht die API den gespeicherten Ablaufzeitpunkt. Dasselbe gilt, wenn du ausdrücklich null angibst.

Bei Zugangsdaten für eine Umgebungsvariable sendest du auth.type: "environment_variable" und den neuen Wert für auth.secret_value an POST /v1/vaults/{vault_id}/credentials/{credential_id}. Erstelle eine neue Sitzung, um die neuen Zugangsdaten zu verwenden. Bereits in einer bestehenden Sandbox konfigurierte Zugangsdaten ändern sich durch die Aktualisierung des Tresors nicht.

Um secret_name oder networking zu ändern, erstelle einen neuen Zugangsdaten-Eintrag.

Lösche einen Zugangsdaten-Eintrag, wenn du ihn nicht mehr benötigst. Lösche einen Tresor, um ihn zusammen mit allen darin gespeicherten Zugangsdaten zu entfernen.

Wenn du gespeicherte Zugangsdaten löschst, bleiben die ursprünglichen Tokens beim jeweiligen Anbieter gültig, bis sie ablaufen oder widerrufen werden. Laufende Sitzungen werden durch das Löschen nicht beendet. Deine Anwendung ist dafür zuständig, Tokens beim Anbieter zu widerrufen und Sitzungen abzubrechen.