Quando você precisa que o Copilot gere dados que outro programa ou API possa consumir diretamente, a saída em texto livre causa erros. Você precisa de schemas JSON estritos — saída estruturada com nomes de campo exatos, tipos de dados e regras de validação. Este artigo explica como escrever prompts do Copilot que produzem JSON válido e compatível com o schema toda vez. Você aprenderá a estrutura exata do prompt, técnicas de definição de schema e armadilhas comuns de formatação a evitar.
Principais Conclusões: Prompts de Schema JSON Estrito para o Copilot
- Estrutura do prompt: “Gere um objeto JSON com o seguinte schema:” Força o Copilot a retornar um objeto JSON em vez de texto simples ou Markdown.
- Definição do schema com sintaxe JSON Schema: Use
"type": "object","properties"e"required"para definir nomes de campo exatos e tipos de dados. - Regra de validação:
"additionalProperties": falseImpede que o Copilot adicione campos extras que quebrem seu contrato de API.
Como Estruturar um Prompt para Saída JSON Estrita
O Copilot, por padrão, retorna respostas em linguagem natural ou Markdown. Para obter JSON estrito, você deve instruir explicitamente o modelo a gerar um objeto JSON e definir o schema dentro do prompt. Os componentes principais são: uma instrução clara para gerar JSON, uma definição de schema usando a sintaxe JSON Schema e uma solicitação para omitir qualquer texto explicativo. Sem esses três elementos, o Copilot pode envolver o JSON em um bloco de código ou adicionar frases descritivas ao redor.
A definição do schema atua como um modelo. O Copilot preenche os valores com base na sua solicitação, mas respeita a estrutura que você define. Por exemplo, se você especificar "type": "string" para um campo, o Copilot não gerará um número ou booleano para esse campo. Se você listar um campo no array "required", o Copilot sempre o incluirá. Esse comportamento torna a saída previsível para sistemas downstream.
Passos para Gerar Saída JSON com Schema Estrito Usando o Copilot
- Abra o painel do Copilot no seu aplicativo Microsoft 365
Clique no ícone do Copilot na faixa de opções ou pressione Alt+Shift+I para abrir o painel lateral. Isso funciona no Word, Excel, Outlook e Teams. - Escreva a instrução base
Digite: “Gere um objeto JSON com o seguinte schema. Não inclua nenhum texto fora do objeto JSON.” Isso impede que o Copilot adicione cercas de código Markdown ou frases extras. - Defina o schema inline
Após a instrução, cole sua definição JSON Schema. Exemplo:{"type":"object","properties":{"nome":{"type":"string"},"idade":{"type":"integer"}},"required":["nome","idade"],"additionalProperties":false} - Adicione a solicitação de dados
Escreva: “Gere dados para um novo registro de funcionário.” Isso informa ao Copilot quais valores preencher. Sem isso, o Copilot pode pedir esclarecimentos ou gerar um schema vazio. - Pressione Enter ou clique em Enviar
O Copilot retorna um objeto JSON que corresponde exatamente ao seu schema. Exemplo:{"nome":"Sarah Chen","idade":32} - Valide a saída
Copie o JSON para um validador como JSONLint ou sua ferramenta de teste de API. Verifique se não há campos extras e se todos os campos obrigatórios estão presentes.
Erros Comuns na Definição do Schema e Como Evitá-los
O Copilot adiciona campos extras que quebram meu contrato de API
O problema mais frequente é o Copilot gerar campos que você não definiu. Por exemplo, você solicita {"nome":"string","email":"string"} e o Copilot adiciona "id":123 ou "status":"ativo". Para evitar isso, inclua "additionalProperties": false no seu schema. Isso instrui o Copilot a rejeitar qualquer campo não listado no objeto properties.
O Copilot envolve o JSON em um bloco de código Markdown
Por padrão, o Copilot retorna JSON dentro de um bloco de código Markdown com três acentos graves. Se o parser da sua API esperar JSON bruto, isso causa um erro de análise. Adicione a instrução: “Não use cercas de código Markdown. Gere apenas o objeto JSON.” Se o Copilot ainda adicionar cercas, acrescente ao prompt: “Se você envolver o JSON em acentos graves, rejeitarei a saída.” Esse reforço negativo geralmente funciona.
O Copilot gera uma string em vez de um inteiro para um campo numérico
Quando você define "idade": {"type": "integer"}, o Copilot deve gerar "idade": 32, não "idade": "32". Mas às vezes o Copilot trata todos os valores como strings. Para impor o tipo, adicione "coerce": true no schema se sua versão do Copilot suportar, ou declare explicitamente: “O campo ‘idade’ deve ser um número, não uma string.” Você também pode adicionar um exemplo: "idade": 30 dentro da propriedade examples do schema.
Modos de Saída do Copilot: Estruturado vs. Livre
| Item | Saída JSON Estruturada | Saída em Texto Livre |
|---|---|---|
| Formato de saída | Objeto JSON com schema exato | Linguagem natural ou Markdown |
| Caso de uso | Ingestão de API, pipelines de dados, automação | Leitura humana, resumos, rascunhos |
| Imposição de schema | Sim — via JSON Schema no prompt | Não — o Copilot decide a estrutura |
| Tratamento de erros | Previsível — o parser pode validar | Imprevisível — requer revisão humana |
| Complexidade do prompt | Maior — deve definir schema inline | Menor — pergunta ou solicitação simples |
Para uso em API, sempre escolha a saída JSON estruturada. O esforço inicial de escrever o schema compensa com zero limpeza manual. A saída em texto livre é melhor para perguntas exploratórias ou quando você precisa que o Copilot decida a estrutura.
Modelo de Prompt Avançado para Schemas Complexos
Para objetos e arrays aninhados, estenda a definição do schema. Exemplo de prompt para um funcionário com múltiplos endereços:
Gere um objeto JSON com este schema: {"type":"object","properties":{"funcionario":{"type":"object","properties":{"nome":{"type":"string"},"departamento":{"type":"string"},"enderecos":{"type":"array","items":{"type":"object","properties":{"rua":{"type":"string"},"cidade":{"type":"string"},"cep":{"type":"string"}},"required":["rua","cidade"],"additionalProperties":false}}},"required":["nome","departamento"],"additionalProperties":false}} Gere um registro para um novo contratado no departamento de engenharia.
O Copilot gera um objeto JSON com funcionario aninhado e arrays de enderecos, todos respeitando o schema. Teste isso com um validador para confirmar que não aparecem campos extras.
Recursos Adicionais
Para mais controle, combine o prompt de schema JSON com os modos de saída estruturada integrados do Copilot no Microsoft 365 Copilot Studio. Você pode definir uma ação personalizada que imponha o schema no lado do servidor. Isso é útil quando você não pode modificar prompts por solicitação. Considere também usar a API Graph do Copilot com um parâmetro response_format definido como json_object para acesso programático. Isso ignora o painel do Copilot e retorna JSON bruto diretamente para sua aplicação.