Référence

Passerelle de composants window.openai

ChatGPT fournit window.openai pour les alias de compatibilité et les extensions facultatives de ChatGPT. Les nouvelles interfaces doivent utiliser la passerelle MCP Apps dès que la spécification commune propose un équivalent, puis réserver window.openai aux capacités propres à ChatGPT.

Consultez Créer une interface ChatGPT pour des guides de mise en œuvre détaillés.

Si votre outil nécessite une confirmation, l’absence initiale de toolInput est normale. ChatGPT ne charge pas les arguments soumis à approbation dans les valeurs du widget avant l’approbation ; l’hôte les transmet via ui/notifications/tool-input une fois que l’utilisateur a approuvé l’appel.

Capacités

Fonction utilitaire useOpenAiGlobal

De nombreux projets d’interface ChatGPT encapsulent l’accès à window.openai dans de petites fonctions utilitaires pour que les vues restent testables. La fonction utilitaire de cet exemple écoute les événements openai:set_globals de l’hôte et permet aux composants React de s’abonner à une seule valeur globale :

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]
  );
}

Fermez l’interface

Appelez window.openai.requestClose() pour demander à ChatGPT de fermer l’interface actuelle.

Demandez un autre mode d’affichage

Utilisez window.openai.requestDisplayMode pour demander un affichage intégré, en incrustation d’image ou en plein écran :

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

Ouvrez une fenêtre modale

Utilisez window.openai.requestModal pour ouvrir une fenêtre modale contrôlée par l’hôte. Fournissez l’URI d’un autre modèle d’interface enregistré par le même serveur MCP, ou omettez template pour ouvrir le modèle actuel :

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

API de fichiers

ChatGPT prend en charge des fonctions utilitaires d’importation et de téléchargement de fichiers via window.openai, sous forme d’extensions facultatives.

La bibliothèque de fichiers de ChatGPT est facultative et peut ne pas être accessible à tous les utilisateurs. Lorsque la fonction utilitaire est disponible, les fichiers renvoyés par window.openai.selectFiles() sont déjà autorisés pour le plugin actuel. Utilisez la valeur fileId renvoyée avec window.openai.getFileDownloadUrl({ fileId }) ou dans une entrée d’outil qui utilise des paramètres de fichier.

Importez un fichier sélectionné par l’utilisateur :

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

Sélectionnez des fichiers que l’utilisateur a déjà importés dans ChatGPT :

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

Vérifiez la disponibilité de window.openai.selectFiles et utilisez window.openai.uploadFile comme solution de repli lorsque la bibliothèque de fichiers n’est pas disponible.

Demandez une URL de téléchargement temporaire :

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

Définissez les fichiers en entrée

Pour permettre à ChatGPT de transmettre des fichiers à un outil, répertoriez chaque entrée de fichier de premier niveau dans _meta["openai/fileParams"]. Chaque champ répertorié doit correspondre à un objet fichier ou à un tableau d’objets fichier.

Chaque schéma d’objet fichier doit déclarer les quatre propriétés prises en charge :

Les valeurs mime_type et file_name sont facultatives, mais vous devez déclarer les propriétés correspondantes dans le schéma. L’étape Analyser les outils et la soumission du plugin rejettent tout schéma de fichier qui omet l’une des quatre propriétés, ne rend pas obligatoires download_url et file_id, rend obligatoire l’une des deux propriétés facultatives ou exige une propriété autre que download_url ou file_id. Vous pouvez déclarer des propriétés facultatives supplémentaires.

Ce descripteur d’outil complet accepte un fichier obligatoire en entrée :

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

Pour accepter plusieurs fichiers, définissez le champ de premier niveau comme un tableau et utilisez le même schéma d’objet fichier dans items. L’outil peut rendre obligatoire le champ de fichier de premier niveau indépendamment des propriétés obligatoires dans chaque objet fichier.

À l’exécution, ChatGPT transmet les valeurs des fichiers avec des noms de champs en snake case :

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

ChatGPT inclut toujours download_url et file_id ; il peut omettre mime_type et file_name. Utilisez file_id comme valeur de fileId pour window.openai.getFileDownloadUrl({ fileId }) lorsqu’un widget a besoin d’une nouvelle URL de téléchargement temporaire.

Lorsque vous enregistrez l’état du widget, utilisez le format structuré (modelContent, privateContent, imageIds) si vous souhaitez que le modèle ait accès aux identifiants des images lors des échanges suivants.

Navigation prise en charge par l’hôte

L’environnement d’exécution du bac à sable répercute l’historique de navigation de l’iframe dans l’interface de ChatGPT. Utilisez des API de routage standard, comme React Router, et l’hôte maintiendra ses commandes de navigation synchronisées avec votre interface.

Configuration du routeur avec BrowserRouter de React Router :

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

Navigation par programmation :

const navigate = useNavigate();

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

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

Paramètres du descripteur d’outil

Par défaut, la description d’un outil devrait inclure les champs répertoriés ici.

Déclarez outputSchema pour tout outil qui renvoie structuredContent. Le schéma devrait décrire précisément l’objet renvoyé par votre outil afin que les clients puissent valider les résultats et que le modèle puisse raisonner sur les appels d’outils suivants.

Champs _meta du descripteur d’outil

Utilisez ces champs _meta dans le descripteur d’outil. Privilégiez la clé standard de MCP Apps _meta.ui.resourceUri pour associer un outil à un modèle d’interface. ChatGPT prend en charge des métadonnées propres à OpenAI pour assurer la compatibilité et proposer des extensions facultatives.

Exemple :

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.` }],
    };
  }
);

Annotations

Pour indiquer qu’un outil est « en lecture seule », utilisez les champs ToolAnnotations suivants dans le descripteur d’outil :

Ces indications influencent uniquement la manière dont ChatGPT ou Codex présente l’appel d’outil à l’utilisateur ; les serveurs doivent toujours appliquer leur propre logique d’autorisation.

Exemple :

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() },
  })
);

Champs _meta de la ressource du composant

Définissez ces clés dans le modèle de ressource qui sert votre composant (registerResource). Elles aident ChatGPT à décrire et à présenter l’iframe affichée sans divulguer de métadonnées aux autres clients.

ChatGPT prend en charge l’ancienne clé de compatibilité _meta["openai/widgetCSP"] avec les noms de champs suivants au format snake_case :

• connect_domains: string[]
• resource_domains: string[]
• frame_domains?: string[]
• redirect_domains?: string[]. Extension ChatGPT pour les cibles de redirection de window.openai.openExternal.

L’objet standard _meta.ui.csp est généralement recommandé pour les nouvelles interfaces et prend en charge les champs suivants :

• connectDomains: string[]. Domaines que le widget peut contacter via fetch/XHR.
• resourceDomains: string[]. Domaines des ressources statiques (images, polices, scripts, styles).
• frameDomains? : string[]. Liste facultative des origines autorisées pour les intégrations dans des iframes. Par défaut, les widgets ne peuvent pas afficher de cadres imbriqués. Les Plugins peuvent intégrer du contenu de leur propre domaine, notamment des éditeurs et des interfaces d’administration existants, conformément à la politique relative aux iframes. Une justification est requise lors de la soumission, et l’utilisation d’iframes peut nécessiter une révision supplémentaire ou allonger le délai d’approbation.

Cependant, _meta.ui.csp ne prend pas en charge redirect_domains pour les liens window.openai.openExternal(...). Pour ajouter des cibles de redirection à la liste des destinations autorisées, vous devez toujours définir _meta["openai/widgetCSP"].redirect_domains.

Résultats des outils

Les résultats des outils peuvent contenir les champs suivants, notamment :

Seuls structuredContent et content apparaissent dans la transcription de la conversation. L’hôte transmet _meta au composant pour vous permettre d’alimenter l’interface sans exposer les données au modèle.

Métadonnées des résultats des outils fournies par l’hôte :

Exemple :

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

Résultat d’outil signalant une erreur

Pour renvoyer une erreur dans le résultat de l’outil, utilisez la clé _meta suivante :

Champs _meta fournis par le client

Pendant l’exécution, _meta["openai/userAgent"] et _meta["openai/userLocation"] ne sont que des indications ; les serveurs ne doivent jamais s’appuyer sur ces valeurs pour prendre des décisions d’autorisation et doivent tolérer leur absence. Considérez _meta["openai/userAgent"] comme une métadonnée facultative, fournie dans la mesure du possible, et non comme un moyen fiable d’identifier l’interface hôte qui appelle votre serveur.

Exemple :

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