Referenz

Komponenten-Bridge window.openai

ChatGPT stellt window.openai für Kompatibilitätsaliase und optionale ChatGPT-Erweiterungen bereit. Neue Benutzeroberflächen sollten die MCP Apps-Bridge verwenden, wenn die gemeinsame Spezifikation eine entsprechende Funktion bietet. Verwende window.openai dann nur für ChatGPT-spezifische Funktionen.

Schritt-für-Schritt-Anleitungen zur Implementierung findest du unter Eine ChatGPT-Benutzeroberfläche entwickeln.

Wenn dein Tool eine Bestätigung erfordert, ist es normal, dass toolInput anfangs fehlt. ChatGPT lädt genehmigungspflichtige Argumente erst nach der Genehmigung in die Widget-Werte. Der Host übermittelt sie über ui/notifications/tool-input, sobald die nutzende Person den Aufruf genehmigt.

Funktionen

Hilfsfunktion useOpenAiGlobal

Viele Projekte für ChatGPT-Benutzeroberflächen kapseln den Zugriff auf window.openai in kleinen Hilfsfunktionen, damit die Ansichten testbar bleiben. Die Hilfsfunktion in diesem Beispiel reagiert auf openai:set_globals-Ereignisse des Hosts und ermöglicht React-Komponenten, einen einzelnen globalen Wert zu abonnieren:

export function useOpenAiGlobal<K extends keyof WebplusGlobals>(
  key: K
): WebplusGlobals[K] {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event: SetGlobalsEvent) => {
        const value = event.detail.globals[key];
        if (value === undefined) {
          return;
        }

        onChange();
      };

      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
        passive: true,
      });

      return () => {
        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
      };
    },
    () => window.openai[key]
  );
}

Benutzeroberfläche schließen

Rufe window.openai.requestClose() auf, um ChatGPT aufzufordern, die aktuelle Benutzeroberfläche zu schließen.

Einen anderen Darstellungsmodus anfordern

Verwende window.openai.requestDisplayMode, um eine Inline-, Bild-in-Bild- oder Vollbilddarstellung anzufordern:

await window.openai?.requestDisplayMode({ mode: "fullscreen" });
// On mobile, picture-in-picture may be presented as fullscreen.

Einen modalen Dialog öffnen

Verwende window.openai.requestModal, um einen vom Host gesteuerten modalen Dialog zu öffnen. Gib die URI einer anderen UI-Vorlage an, die auf demselben MCP-Server registriert ist, oder lass template weg, um die aktuelle Vorlage zu öffnen:

await window.openai.requestModal({
  template: "ui://widget/checkout.html",
});

Datei-APIs

ChatGPT unterstützt Hilfsfunktionen zum Hoch- und Herunterladen von Dateien als optionale Erweiterungen von window.openai.

Die ChatGPT-Dateibibliothek ist optional und steht möglicherweise nicht allen zur Verfügung. Wenn die Hilfsfunktion verfügbar ist, sind die von window.openai.selectFiles() zurückgegebenen Dateien bereits für das aktuelle Plug-in autorisiert. Verwende die zurückgegebene fileId mit window.openai.getFileDownloadUrl({ fileId }) oder in einer Werkzeugeingabe, die Dateiparameter verwendet.

Eine von der nutzenden Person ausgewählte Datei hochladen:

const { fileId } = await window.openai.uploadFile(file, {
  library: true,
});

Dateien auswählen, die die nutzende Person bereits in ChatGPT hochgeladen hat:

if (window.openai?.selectFiles) {
  const files = await window.openai.selectFiles();
  // [{ fileId, fileName, mimeType }]
}

Prüfe, ob window.openai.selectFiles verfügbar ist, und greife auf window.openai.uploadFile zurück, wenn die Dateibibliothek nicht verfügbar ist.

Eine temporäre Download-URL anfordern:

const { downloadUrl } = await window.openai.getFileDownloadUrl({ fileId });

Dateieingaben definieren

Damit ChatGPT Dateien an ein Werkzeug übergeben kann, liste jede Dateieingabe auf oberster Ebene in _meta["openai/fileParams"] auf. Jedes aufgeführte Feld muss ein Dateiobjekt oder ein Array von Dateiobjekten ergeben.

Jedes Schema für Dateiobjekte muss alle vier unterstützten Eigenschaften deklarieren:

mime_type und file_name sind optionale Werte, aber du musst ihre Eigenschaften im Schema deklarieren. Beim Schritt Werkzeuge scannen und beim Einreichen des Plug-ins wird ein Dateischema abgelehnt, wenn eine der vier Eigenschaften fehlt, wenn download_url und file_id nicht beide als erforderlich markiert sind, wenn eine der beiden optionalen Eigenschaften als erforderlich markiert ist oder wenn eine andere Eigenschaft als download_url oder file_id erforderlich ist. Du kannst zusätzliche optionale Eigenschaften deklarieren.

Dieser vollständige Werkzeugdeskriptor akzeptiert eine erforderliche Dateieingabe:

{
  "name": "analyze_file",
  "title": "Analyze file",
  "description": "Analyzes a user-provided file without modifying it.",
  "inputSchema": {
    "type": "object",
    "$defs": {
      "OpenAIFile": {
        "type": "object",
        "properties": {
          "download_url": { "type": "string" },
          "file_id": { "type": "string" },
          "mime_type": { "type": "string" },
          "file_name": { "type": "string" }
        },
        "required": ["download_url", "file_id"],
        "additionalProperties": false
      }
    },
    "properties": {
      "file": { "$ref": "#/$defs/OpenAIFile" }
    },
    "required": ["file"]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false,
    "destructiveHint": false
  },
  "_meta": {
    "openai/fileParams": ["file"]
  }
}

Um mehrere Dateien zu akzeptieren, definiere das Feld auf oberster Ebene als Array und verwende dasselbe Schema für Dateiobjekte in items. Das Werkzeug kann das Dateifeld auf oberster Ebene unabhängig von den erforderlichen Eigenschaften innerhalb der einzelnen Dateiobjekte als erforderlich festlegen.

Zur Laufzeit übergibt ChatGPT Dateiwerte mit Feldnamen in Snake Case:

{
  "download_url": "https://...",
  "file_id": "file_...",
  "mime_type": "image/png",
  "file_name": "input.png"
}

ChatGPT übergibt immer download_url und file_id; mime_type und file_name können fehlen. Verwende file_id als Wert für fileId in window.openai.getFileDownloadUrl({ fileId }), wenn ein Widget eine neue temporäre Download-URL benötigt.

Verwende beim dauerhaften Speichern des Widget-Zustands die strukturierte Form (modelContent, privateContent, imageIds), wenn das Modell in nachfolgenden Gesprächsrunden Bild-IDs sehen soll.

Vom Host unterstützte Navigation

Die Sandbox-Laufzeitumgebung spiegelt den Navigationsverlauf aus dem iframe in die ChatGPT-Oberfläche. Verwende Standard-Routing-APIs wie React Router. Der Host hält dann seine Navigationselemente mit deiner Benutzeroberfläche synchron.

Router-Setup mit BrowserRouter von React Router:

export default function PizzaListRouter() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<PizzaListPlugin />}>
          <Route path="place/:placeId" element={<PizzaListPlugin />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}

Programmgesteuerte Navigation:

const navigate = useNavigate();

function openDetails(placeId: string) {
  navigate(`place/${placeId}`, { replace: false });
}

function closeDetails() {
  navigate("..", { replace: true });
}

Parameter des Werkzeugdeskriptors

Eine Werkzeugbeschreibung sollte standardmäßig die hier aufgeführten Felder enthalten.

Deklariere outputSchema für jedes Werkzeug, das structuredContent zurückgibt. Das Schema sollte das vom Werkzeug zurückgegebene Objekt exakt beschreiben, damit Clients die Ergebnisse validieren und das Modell darauf aufbauend weitere Werkzeugaufrufe planen kann.

_meta-Felder im Werkzeugdeskriptor

Verwende diese _meta-Felder im Werkzeugdeskriptor. Verwende vorzugsweise den im MCP Apps-Standard definierten Schlüssel _meta.ui.resourceUri, um ein Werkzeug mit einer UI-Vorlage zu verknüpfen. ChatGPT unterstützt OpenAI-spezifische Metadaten für Kompatibilität und optionale Erweiterungen.

Beispiel:

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "search",
  {
    title: "Public Search",
    description: "Search public documents.",
    inputSchema: { q: z.string() },
    outputSchema: {
      results: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
          url: z.string(),
        })
      ),
    },
    securitySchemes: [
      { type: "noauth" },
      { type: "oauth2", scopes: ["search.read"] },
    ],
    _meta: {
      securitySchemes: [
        { type: "noauth" },
        { type: "oauth2", scopes: ["search.read"] },
      ],
      ui: { resourceUri: "ui://widget/story.html" },
      // Optional compatibility alias (ChatGPT only):
      // "openai/outputTemplate": "ui://widget/story.html",
      "openai/toolInvocation/invoking": "Searching…",
      "openai/toolInvocation/invoked": "Results ready",
    },
  },
  async ({ q }) => {
    const results = await performSearch(q);

    return {
      structuredContent: { results },
      content: [{ type: "text", text: `Found ${results.length} results.` }],
    };
  }
);

Annotationen

Um ein Tool als „ohne Schreibzugriff“ zu kennzeichnen, verwende die folgenden Felder von ToolAnnotations im Tool-Deskriptor:

Diese Hinweise beeinflussen nur, wie ChatGPT oder Codex den Tool-Aufruf gegenüber den Nutzenden darstellt. Server müssen weiterhin ihre eigene Autorisierungslogik durchsetzen.

Beispiel:

import { z } from "zod";

server.registerTool(
  "list_saved_recipes",
  {
    title: "List saved recipes",
    description: "Returns the user’s saved recipes without modifying them.",
    inputSchema: {},
    outputSchema: {
      recipes: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
        })
      ),
    },
    annotations: { readOnlyHint: true },
  },
  async () => ({
    structuredContent: { recipes: await fetchSavedRecipes() },
  })
);

_meta-Felder der Komponentenressource

Setze diese Schlüssel in der Ressourcenvorlage, die deine Komponente bereitstellt (registerResource). Sie helfen ChatGPT, den gerenderten iframe zu beschreiben und darzustellen, ohne Metadaten an andere Clients weiterzugeben.

ChatGPT unterstützt den älteren Kompatibilitätsschlüssel _meta["openai/widgetCSP"] mit den folgenden Feldnamen in snake_case:

• connect_domains: string[]
• resource_domains: string[]
• frame_domains?: string[]
• redirect_domains?: string[]. ChatGPT-Erweiterung für Weiterleitungsziele von window.openai.openExternal.

Für neue Benutzeroberflächen wird im Allgemeinen das standardisierte Objekt _meta.ui.csp empfohlen. Es unterstützt:

• connectDomains: string[]. Domains, die das Widget über fetch/XHR kontaktieren darf.
• resourceDomains: string[]. Domains für statische Ressourcen (Bilder, Schriftarten, Skripte, Styles).
• frameDomains?: string[]. Optionale Liste der für iframe-Einbettungen zulässigen Origins. Standardmäßig können Widgets keine untergeordneten Frames rendern. Plug-ins können gemäß der iframe-Richtlinie Inhalte ihrer eigenen Domain einbetten, darunter vorhandene Editoren und Verwaltungsoberflächen. Bei der Einreichung ist eine Begründung erforderlich. Die Verwendung von iframes kann ein zusätzliches Review erfordern oder die Genehmigung verzögern.

Allerdings unterstützt _meta.ui.csp kein redirect_domains für Links über window.openai.openExternal(...). Um Weiterleitungsziele auf die Zulassungsliste zu setzen, musst du weiterhin _meta["openai/widgetCSP"].redirect_domains festlegen.

Tool-Ergebnisse

Tool-Ergebnisse können die folgenden Felder enthalten. Besonders relevant sind:

Nur structuredContent und content erscheinen im Gesprächsprotokoll. Der Host leitet _meta an die Komponente weiter, damit du die Benutzeroberfläche mit Daten versorgen kannst, ohne sie dem Modell offenzulegen.

Vom Host bereitgestellte Metadaten zu Tool-Ergebnissen:

Beispiel:

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "get_zoo_animals",
  {
    title: "get_zoo_animals",
    inputSchema: { count: z.number().int().min(1).max(20).optional() },
    outputSchema: {
      animals: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          species: z.string(),
        })
      ),
    },
    _meta: { ui: { resourceUri: "ui://widget/widget.html" } },
  },
  async ({ count = 10 }) => {
    const animals = generateZooAnimals(count);

    return {
      structuredContent: { animals },
      content: [{ type: "text", text: `Here are ${animals.length} animals.` }],
      _meta: {
        allAnimalsById: Object.fromEntries(
          animals.map((animal) => [animal.id, animal])
        ),
      },
    };
  }
);

Tool-Ergebnis mit Fehler

Um einen Fehler im Tool-Ergebnis zurückzugeben, verwende den folgenden Schlüssel in _meta:

Vom Client bereitgestellte _meta-Felder

Die während der Ausführung übermittelten Werte _meta["openai/userAgent"] und _meta["openai/userLocation"] dienen nur als Hinweise. Server sollten sich bei Autorisierungsentscheidungen niemals darauf verlassen und müssen auch ohne diese Angaben funktionieren. Behandle _meta["openai/userAgent"] als optionale Metadaten, die nach Möglichkeit bereitgestellt werden, und nicht als zuverlässige Möglichkeit, die aufrufende Host-Oberfläche zu erkennen.

Beispiel:

import { z } from "zod";

server.registerTool(
  "recommend_cafe",
  {
    title: "Recommend a cafe",
    inputSchema: {},
    outputSchema: {
      cafes: z.array(
        z.object({
          name: z.string(),
          address: z.string(),
        })
      ),
    },
  },
  async (_args, { _meta }) => {
    const locale = _meta?.["openai/locale"] ?? "en";
    const location = _meta?.["openai/userLocation"]?.city;
    const cafes = await findNearbyCafes(location);

    return {
      content: [{ type: "text", text: formatIntro(locale, location) }],
      structuredContent: { cafes },
    };
  }
);