Otimizar: Metadados, Competências e Eventos
Nesta página
Lição reescrita a 3 de novembro de 2026 com base nas páginas de documentação de Plugins da OpenAI Optimize Metadata, Build Skills, MCP Events e Plugin Extensions. A versão anterior desta lição baseava-se nos módulos
analyticseexperimentde um SDK inexistente. Fontes: Optimize Metadata · Build Skills · MCP Events · Plugin Extensions.
Os metadados são texto de produto
O ChatGPT e o Codex decidem quando invocar as suas ferramentas com base nos metadados que fornece. Nomes, descrições e parâmetros bem redigidos garantem que a sua ferramenta é acionada quando necessário e previnem ativações indesejadas. A OpenAI recomenda tratar estes metadados como texto de produto: itere sobre eles, teste-os e meça o seu desempenho.
Um conjunto de prompts de referência
Antes de tocar nos seus metadados, crie um conjunto rotulado de prompts de teste:
- Prompts diretos que nomeiam explicitamente o seu produto ou fonte de dados.
- Prompts indiretos que descrevem o resultado desejado sem nomear a sua ferramenta.
- Prompts negativos que devem ser tratados por ferramentas integradas ou por outros plugins.
Para cada prompt, documente o comportamento esperado: chamar a sua ferramenta, não fazer nada ou delegar noutra solução. Utilize este conjunto para todos os testes de não regressão.
Metadados que orientam o modelo
- O nome deve combinar o domínio e a ação, como
calendar.create_event. - A descrição deve começar por “Utilizar quando…” e listar explicitamente os casos excluídos, como “Não utilizar para lembretes.”
- Cada parâmetro deve ser documentado com exemplos e uma lista de valores permitidos se a entrada estiver restrita.
- As anotações devem refletir o comportamento real (consulte as Lições 3 e 11).
Medir e, depois, iterar
Ligue o seu servidor, instale o plugin, execute o seu conjunto de prompts e registe qual foi a ferramenta selecionada, que argumentos foram passados e se algum componente de interface foi apresentado. Acompanhe duas métricas: precisão (a ferramenta correta foi chamada?) e recall (a ferramenta foi chamada todas as vezes que deveria ter sido?). Priorize uma alta precisão nos prompts negativos antes de procurar ganhos marginais no recall.
Altere apenas um campo de cada vez para isolar o que impulsiona a melhoria. Mantenha um registo de revisões datado com os resultados e peça a outra pessoa para rever as alterações antes da implementação. Em produção, revele a utilização das ferramentas semanalmente. Um pico nas confirmações de “ferramenta errada” sinaliza geralmente uma deriva nos metadados. Recolha feedback dos utilizadores e volte a executar os seus testes de prompts regularmente, especialmente após adicionar uma nova ferramenta ou modificar um campo estruturado.
Competências para fluxos de trabalho recorrentes
O seu servidor fornece dados, autenticação e ações controladas. Uma competência fornece a sequência de chamadas de ferramentas, pontos de decisão, formatação de saída, exemplos e modelos. A forma mais rápida de começar é com o criador integrado @skill-creator, onde descreve o objetivo do utilizador e as ferramentas MCP que o suportam.
Um ficheiro SKILL.md robusto especifica quais os passos a seguir, que resultado o utilizador deve receber, que factos o modelo não deve inventar, quando deve fazer perguntas, parar ou recusar, e quais os ficheiros a consultar. Prefira uma competência focada num fluxo de trabalho específico em vez de um grande conjunto de instruções díspares. Divida os fluxos de trabalho que diferem no seu gatilho, entradas ou critérios de sucesso. Mantenha o SKILL.md conciso e guarde os detalhes noutro local: utilize references/ para políticas, esquemas e exemplos; assets/ para modelos a copiar ou transformar; e scripts/ para cálculos determinísticos — mas apenas se as instruções e ferramentas existentes forem insuficientes.
Se uma competência depender de um servidor MCP, declare essa dependência em agents/openai.yaml. Isto torna a ferramenta disponível, mas não substitui a necessidade de instruções claras sobre quais ferramentas utilizar, em que ordem e como lidar com resultados em falta ou ambíguos. Para o GPT-6 Astra, a OpenAI aconselha a revisão das suas orientações sobre o seguimento de instruções: elimine diretivas vagas ou contraditórias e torne explícito que as instruções do utilizador têm prioridade sobre as instruções da competência.
Teste a ativação da competência e a qualidade da saída utilizando prompts diretos, indiretos, incompletos (que devem desencadear uma pergunta de esclarecimento), fora de contexto e casos limite onde a competência deve evitar alucinar ou agir fora do seu âmbito. Se uma competência for ativada na altura errada, corrija a sua descrição. Se selecionar o fluxo de trabalho correto, mas produzir resultados inconsistentes, corrija as suas instruções.
Eventos MCP: Reagir a alterações
Os Eventos MCP permitem ao ChatGPT subscrever atualizações do seu servidor, como novas mensagens, conteúdo modificado ou alterações de estado. O utilizador escolhe o que monitorizar e como o ChatGPT deve reagir quando chega uma atualização — por exemplo, “Monitorize este documento e aplique as correções solicitadas nos comentários.”
- O seu servidor lista os eventos que suporta.
- O utilizador diz ao ChatGPT o que monitorizar e como reagir.
- O ChatGPT subscreve através do seu servidor MCP, fornecendo um URL de retorno de chamada e um segredo de assinatura.
- O seu servidor envia eventos relevantes para esse URL.
- O ChatGPT recebe o evento na conversa subscrita e segue as instruções do utilizador.
Esta funcionalidade está disponível nas conversas do ChatGPT Work na web e na aplicação de ambiente de trabalho com Cloud selecionado. O ChatGPT depende da entrega via webhook conforme definido no rascunho da especificação de Eventos MCP. O seu servidor deve persistir as subscrições e ser capaz de aceder aos URLs de retorno de chamada via HTTPS.
Extensões da interface do ChatGPT
As OpenAI MCP Extensions permitem que um plugin se integre em áreas-chave da interface do ChatGPT: a barra lateral, a área de entrada e os visualizadores de ficheiros. As menções na área de entrada estão disponíveis apenas na aplicação de ambiente de trabalho. A OpenAI publica um plugin de exemplo, Bits & Bolts, que demonstra estas extensões e acompanha a sua implementação. É o melhor ponto de partida para explorar esta capacidade.
Pontos-chave
- Trate os metadados como texto de produto: utilize um conjunto de prompts de referência, acompanhe a precisão e o recall, e altere um campo de cada vez.
- Escreva descrições começando por “Utilizar quando…”, liste explicitamente os casos excluídos e documente todos os parâmetros.
- Crie uma competência focada por fluxo de trabalho, mantenha o
SKILL.mdconciso, guarde os recursos separadamente e declare as dependências MCP. - Os Eventos MCP subscrevem o ChatGPT às atualizações do seu servidor, entregues via webhook.
- As extensões integram o seu plugin na barra lateral, na área de entrada e nos visualizadores de ficheiros.
Teste os seus conhecimentos
Das ferramentas MCP à publicação: verifique se dominou os fundamentos.
1. Preciso de um pacote `@openai/apps-sdk` para criar uma aplicação no ChatGPT?
Resposta: Não, esse pacote não existe. Constrói um servidor MCP utilizando os SDKs oficiais do protocolo (@modelcontextprotocol/sdk para TypeScript, mcp para Python), adiciona opcionalmente uma interface compatível com o padrão MCP Apps e distribui o conjunto como um plugin.
2. Pode uma ferramenta existir sem interface de utilizador?
Resposta: Sim, e deve: uma ferramenta devolve structuredContent e um breve resumo textual, o que é suficiente para o modelo. A interface de utilizador, anexada via _meta.ui.resourceUri, é adicionada apenas quando ajuda os utilizadores a inspecionar, comparar, editar, confirmar ou navegar na informação.
3. Quem decide se um utilizador tem permissão para aceder aos dados?
Resposta: O servidor MCP decide em cada pedido, com base no token OAuth verificado (assinatura, emissor, audiência, expiração, âmbitos). As anotações ajudam o ChatGPT a escolher o nível de confirmação adequado, mas nunca substituem a autorização do lado do servidor.
4. Pode um plugin vender uma subscrição do seu serviço?
Resposta: Não. As regras restringem o comércio a bens físicos. Um subscritor existente pode iniciar sessão e utilizar as funcionalidades incluídas no seu plano. O plugin pode explicar que uma funcionalidade não está incluída e fornecer uma ligação para uma página de informações, mas nunca deve fornecer uma ligação para uma página de pagamento.
5. Como é que as ferramentas são atualizadas para um plugin publicado?
Resposta: Sem um novo ficheiro ZIP: a OpenAI volta a analisar o servidor e qualquer ferramenta nova ou modificada fica disponível após passar nas verificações automatizadas. Uma ferramenta eliminada desaparece imediatamente. No entanto, os metadados e as competências exigem um novo ficheiro ZIP e uma nova revisão.
Ferramentas bem descritas, interfaces de utilizador opcionais, autorização do lado do servidor e adesão às regras: eis o enquadramento que torna um plugin um serviço fiável no ChatGPT e no Codex.