Refinamento de Instrução

Use o Refinamento de Instrução para revisar instruções do sistema, prompts e habilidades antes de enviá-los a um modelo. O serviço verifica esses elementos contra um catálogo de diretrizes de engenharia de prompts compiladas a partir da documentação dos fornecedores de modelos, retornando uma pontuação, problemas priorizados localizados no seu texto, as diretrizes por trás de cada problema e sugestões de correção.

Ele se encaixa em revisões de prompts em pull requests, auditorias de instruções e habilidades de gateways de IA e editores que destacam problemas conforme você escreve. Ele relata questões relacionadas às diretrizes; não executa seu prompt nem mede como um modelo performa com ele. Para testar o comportamento contra conversas reais, use Testes Agênticos.

Antes de chamar este endpoint, crie uma chave de API e certifique-se de que a conta tenha um saldo positivo.

Endpoint #

Escolha uma visualização #

A revisão é executada em uma de duas visualizações. Cada solicitação executa uma visualização e é cobrada separadamente, portanto, execute ambas quando desejar uma revisão completa.

• micro (padrão) revisa a redação dentro de cada item: clareza, limites mensuráveis, estrutura, exemplos, ênfase, orientação de ferramentas, formato de saída e diretrizes semelhantes. Use-o enquanto escreve ou edita um único prompt.
• macro revisa como os itens funcionam juntos como um único agente. Verifica se o agente tem um propósito claro e limites de autoridade, se cada comportamento reside em um único item responsável por ele, se as habilidades podem ser selecionadas a partir de suas descrições sem sobreposição ou serem forçadas, se o contexto corresponde às ferramentas que o agente realmente possui e se evita superespecificação, como conversas roteirizadas ou regras que a plataforma já fornece. Use-o ao revisar um agente inteiro ou seu conjunto de habilidades.

A visualização macro precisa dos itens relacionados para julgar relações. Envie as instruções base junto com as habilidades, descrições de ferramentas e conhecimento que o agente usa; um único item lhe dá pouco para comparar.

Comportamento da solicitação #

Envie em uma única solicitação os itens que o mesmo agente recebe. Uma diretriz pode ser satisfeita por outro item, e as descobertas podem apontar itens que entram em conflito ou se duplicam; revisar itens em solicitações separadas perde essas relações. Na visualização micro, os itens knowledge e documentation são usados apenas como contexto.

Um view ou type desconhecido, um content vazio ou um array context vazio retorna 400 Bad Request.

{
  "view": "macro",
  "purpose": "Responder perguntas sobre faturamento e repassar reembolsos à equipe financeira.",
  "context": [
    {
      "type": "instruction",
      "title": "support-agent.md",
      "content": "Você é um agente de suporte.\nNunca prometa reembolsos."
    },
    {
      "type": "skill",
      "title": "refunds",
      "description": "Reembolsos.",
      "content": "Prometa um reembolso quando o cliente pedir um."
    }
  ]
}

Leia a resposta #

data contém a revisão de todos os itens:

Cada descoberta tem estas propriedades:

evidenceSpan fornece a localização do problema no content desse item como fromLine, toLine, fromColumn e toColumn, todos baseados em 1 e inclusivos. É null quando o problema é uma omissão, quando está na description de uma habilidade ou quando o texto citado não pôde ser localizado. As colunas contam caracteres a partir do início da linha, portanto, as quebras de linha dentro de content devem corresponder ao texto que você exibe ao destacar um trecho.

Cada fonte tem um id que identifica a diretriz em seu catálogo, um number dentro de seu tipo, um type e references com as URLs da documentação do fornecedor por trás dela. type reflete o peso da diretriz: uma rule previne falhas previsíveis, uma practice melhora os resultados de forma confiável, uma tip é opcional e situacional, e um dont é um anti-padrão a ser evitado. Algumas diretrizes macro cobrem o design do agente em vez de orientações do fornecedor e têm um array references vazio.

Cada correção sugerida tem um array refFinding com os ids das descobertas que resolve, uma description do que exatamente alterar e em qual item, e um type:

title, description, summary e as descrições das correções são escritos no idioma usado pela maior parte do conteúdo analisado.

{
  "message": null,
  "data": {
    "overallScore": 0.35,
    "summary": "As instruções e a habilidade de reembolsos contradizem-se sobre reembolsos, e a descrição da habilidade é vaga demais para ser selecionada de forma confiável.",
    "findings": [
      {
        "id": 1,
        "priority": "P0",
        "title": "Autoridade de reembolso contraditória",
        "description": "As instruções proíbem prometer reembolsos enquanto a habilidade exige isso, então o agente pode prometer reembolsos que não pode conceder.",
        "locations": [
          {
            "contextIndex": 0,
            "evidenceSpan": { "fromLine": 2, "toLine": 2, "fromColumn": 1, "toColumn": 22 }
          },
          {
            "contextIndex": 1,
            "evidenceSpan": { "fromLine": 1, "toLine": 1, "fromColumn": 1, "toColumn": 48 }
          }
        ],
        "sources": [
          {
            "id": "B.D. 3",
            "number": 3,
            "type": "dont",
            "references": [
              "https://cookbook.openai.com/examples/gpt-5/gpt-5_prompting_guide"
            ]
          }
        ]
      }
    ],
    "suggestedFixes": [
      {
        "refFinding": [ 1 ],
        "type": "modify",
        "description": "Na habilidade de reembolsos, substitua a promessa por: \"Explique que a equipe financeira analisa reembolsos e transfira a solicitação para eles.\""
      }
    ]
  }
}

As revisões são geradas por modelos. A pontuação e as descobertas podem variar entre solicitações para o mesmo conteúdo, e uma descoberta pode estar errada ou perder contexto que só você tem. Uma remoção sugerida ainda pode eliminar uma regra de negócios que a revisão não reconheceu como crítica, portanto, verifique as remoções contra seus requisitos, aplique as correções deliberadamente e confirme que o agente alterado ainda se comporta conforme o esperado.

Preços e limites #

O Refinamento de Instrução é cobrado em unidades de processamento (PUs), cobrindo o uso de entrada e saída. O uso é registrado uma vez por solicitação. O preço da PU varia com o modelo de processamento que atende à solicitação, e o multiplicador de plano se aplica. Itens de contexto mais longos consomem mais entrada.

O Refinamento de Instrução compartilha os limites de documento do Extração e Resumo. Cada item no array context da solicitação conta como um documento, não cada solicitação HTTP. O número de documentos processados por minuto e por dia depende do plano; veja Limites de processamento de dados. Uma solicitação que excederia qualquer janela ativa retorna 429 Too Many Requests.

A referência de API embutida contém os detalhes de solicitação, resposta, autenticação e erro mantidos pelo servidor: