Referência

Ponte de comunicação de componentes window.openai

O ChatGPT fornece window.openai para aliases de compatibilidade e extensões opcionais do ChatGPT. Novas interfaces devem usar a ponte de comunicação MCP Apps sempre que a especificação compartilhada oferecer um equivalente e usar window.openai apenas para capacidades específicas do ChatGPT.

Consulte Crie uma interface para o ChatGPT para ver guias de implementação passo a passo.

Se sua ferramenta exigir confirmação, a ausência inicial de toolInput é esperada. O ChatGPT não carrega argumentos que dependem de aprovação nos valores do widget antes da aprovação; o host os envia por meio de ui/notifications/tool-input assim que o usuário aprova a chamada.

Capacidades

Função auxiliar useOpenAiGlobal

Muitos projetos de interface para o ChatGPT encapsulam o acesso a window.openai em pequenas funções auxiliares para que as visualizações continuem testáveis. Esta função auxiliar de exemplo monitora os eventos openai:set_globals do host e permite que componentes React acompanhem um único valor global:

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

Feche a interface

Chame window.openai.requestClose() para pedir ao ChatGPT que feche a interface atual.

Solicite outro modo de apresentação

Use window.openai.requestDisplayMode para solicitar a apresentação na própria conversa, em imagem sobre imagem ou em tela cheia:

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

Abra um modal

Use window.openai.requestModal para abrir um modal controlado pelo host. Forneça o URI de outro modelo de interface registrado pelo mesmo servidor MCP ou omita template para abrir o modelo de interface atual:

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

APIs de arquivos

O ChatGPT oferece funções auxiliares para envio e download de arquivos como extensões opcionais de window.openai.

A biblioteca de arquivos do ChatGPT é opcional e pode não estar disponível para todos os usuários. Os arquivos retornados por window.openai.selectFiles() já estão autorizados para o plug-in atual quando a função auxiliar está disponível. Use o fileId retornado com window.openai.getFileDownloadUrl({ fileId }) ou em uma entrada de ferramenta que use parâmetros de arquivo.

Envie um arquivo selecionado pelo usuário:

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

Selecione arquivos que o usuário já enviou ao ChatGPT:

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

Verifique se window.openai.selectFiles está disponível e use window.openai.uploadFile como alternativa quando a biblioteca de arquivos estiver indisponível.

Solicite uma URL temporária de download:

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

Defina arquivos de entrada

Para permitir que o ChatGPT passe arquivos a uma ferramenta, liste cada entrada de arquivo de nível superior em _meta["openai/fileParams"]. Cada campo listado deve corresponder a um objeto de arquivo ou a um array de objetos de arquivo.

Todo esquema de objeto de arquivo deve declarar as quatro propriedades suportadas:

mime_type e file_name são valores opcionais, mas você deve declarar suas propriedades no esquema. A etapa Verificar ferramentas e o processo de envio do plug-in rejeitam um esquema de arquivo que omita qualquer uma das quatro propriedades, não exija download_url e file_id, marque qualquer uma das propriedades opcionais como obrigatória ou exija uma propriedade diferente de download_url ou file_id. Você pode declarar propriedades opcionais adicionais.

Este descritor completo de ferramenta aceita uma entrada de arquivo obrigatória:

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

Para aceitar mais de um arquivo, defina o campo de nível superior como um array e use o mesmo esquema de objeto de arquivo em items. A ferramenta pode exigir o campo de arquivo de nível superior independentemente das propriedades obrigatórias dentro de cada objeto de arquivo.

Em tempo de execução, o ChatGPT passa valores de arquivo com campos em snake case:

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

O ChatGPT sempre inclui download_url e file_id; ele pode omitir mime_type e file_name. Use file_id como valor de fileId em window.openai.getFileDownloadUrl({ fileId }) quando um widget precisar de uma nova URL temporária de download.

Ao persistir o estado do widget, use o formato estruturado (modelContent, privateContent, imageIds) se quiser que o modelo tenha acesso aos IDs das imagens nas próximas interações.

Navegação com suporte do host

O ambiente de execução do sandbox espelha o histórico de navegação do iframe na interface do ChatGPT. Use APIs de roteamento padrão, como o React Router, e o host manterá seus controles de navegação sincronizados com a sua interface.

Configuração do roteador com o BrowserRouter do React Router:

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

Navegação programática:

const navigate = useNavigate();

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

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

Parâmetros do descritor de ferramenta

Por padrão, a descrição de uma ferramenta deve incluir os campos listados aqui.

Declare outputSchema para qualquer ferramenta que retorne structuredContent. O esquema deve descrever exatamente o objeto retornado pela ferramenta para que os clientes possam validar os resultados e o modelo possa raciocinar sobre chamadas de ferramenta subsequentes.

Campos de _meta no descritor de ferramenta

Use estes campos de _meta no descritor de ferramenta. Dê preferência à chave padrão do MCP Apps _meta.ui.resourceUri para vincular uma ferramenta a um modelo de interface. O ChatGPT oferece suporte a metadados específicos da OpenAI para compatibilidade e extensões opcionais.

Exemplo:

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

Anotações

Para identificar uma ferramenta como "somente leitura", use os seguintes campos de ToolAnnotations no descritor da ferramenta:

Essas indicações influenciam apenas como o ChatGPT ou o Codex apresenta a chamada de ferramenta ao usuário; os servidores ainda devem aplicar sua própria lógica de autorização.

Exemplo:

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

Campos _meta do recurso do componente

Defina estas chaves no template de recurso que fornece seu componente (registerResource). Elas ajudam o ChatGPT a descrever e apresentar o iframe renderizado sem expor metadados a outros clientes.

O ChatGPT oferece suporte à chave legada de compatibilidade _meta["openai/widgetCSP"] com os seguintes nomes de campos em snake_case:

• connect_domains: string[]
• resource_domains: string[]
• frame_domains?: string[]
• redirect_domains?: string[]. Extensão do ChatGPT para destinos de redirecionamento de window.openai.openExternal.

O objeto padrão _meta.ui.csp geralmente é a opção recomendada para novas interfaces e oferece suporte a:

• connectDomains: string[]. Domínios aos quais o widget pode se conectar via fetch/XHR.
• resourceDomains: string[]. Domínios para recursos estáticos (imagens, fontes, scripts, estilos).
• frameDomains?: string[]. Lista opcional de origens permitidas para incorporações em iframes. Por padrão, widgets não podem renderizar subquadros. Plug-ins podem incorporar conteúdo do próprio domínio, incluindo editores e interfaces de administração existentes, conforme a política de iframes. É necessário apresentar uma justificativa no envio, e o uso de iframes pode exigir revisão adicional ou tornar a aprovação mais demorada.

No entanto, _meta.ui.csp não oferece suporte a redirect_domains para links de window.openai.openExternal(...). Para adicionar destinos de redirecionamento à lista de permissões, ainda é necessário definir _meta["openai/widgetCSP"].redirect_domains.

Resultados de ferramentas

Os resultados de ferramentas podem conter os seguintes campos. Em especial:

Apenas structuredContent e content aparecem na transcrição da conversa. O host encaminha _meta ao componente para que você possa hidratar a interface sem expor os dados ao modelo.

Metadados do resultado da ferramenta fornecidos pelo host:

Exemplo:

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

Resultado de ferramenta com erro

Para retornar um erro no resultado da ferramenta, use a seguinte chave de _meta:

Campos de _meta fornecidos pelo cliente

Na fase de operação, _meta["openai/userAgent"] e _meta["openai/userLocation"] são apenas indicações; os servidores nunca devem usá-los como base para decisões de autorização e devem funcionar mesmo na ausência deles. Trate _meta["openai/userAgent"] como metadados opcionais, fornecidos conforme possível, e não como uma forma estável de detectar qual interface do host está chamando seu servidor.

Exemplo:

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