Obter saída consistente e bem formatada é essencial para aplicações em produção e fluxos de trabalho eficientes. Este capítulo cobre técnicas para controlar exatamente como os modelos de IA formatam suas respostas.

<Callout type="info" title="De Prosa para Dados">
Saída estruturada transforma respostas de IA de texto livre em dados acionáveis e parseáveis.
</Callout>

## Por Que Estrutura Importa

<StructuredOutputDemo />

## Técnicas Básicas de Formatação

### Listas

Listas são perfeitas para instruções passo a passo, itens ranqueados ou coleções de pontos relacionados. São fáceis de escanear e parsear. Use **listas numeradas** quando ordem importa (passos, rankings) e **marcadores** para coleções não ordenadas.

<TryIt 
  compact
  title="Formatação de Lista"
  prompt={`Forneça 5 dicas para dormir melhor.

Formato: Lista numerada com breve explicação para cada.
Cada dica deve estar em negrito, seguida de um traço e explicação.`}
/>

<Callout type="tip" title="Melhores Práticas para Listas">
Especifique o número exato de itens que você quer, se deve incluir explicações, e se os itens devem estar em negrito ou ter uma estrutura específica.
</Callout>

### Tabelas

Tabelas são excelentes para comparar múltiplos itens nas mesmas dimensões. São ideais para comparações de recursos, resumos de dados e qualquer informação com atributos consistentes. Sempre defina seus cabeçalhos de coluna explicitamente.

<TryIt 
  compact
  title="Formatação de Tabela"
  prompt={`Compare os 4 principais frameworks web Python.

Formate como tabela markdown com colunas:
| Framework | Melhor Para | Curva de Aprendizado | Performance |`}
/>

<Callout type="tip" title="Melhores Práticas para Tabelas">
Especifique nomes das colunas, tipos de dados esperados (texto, números, avaliações), e quantas linhas você precisa. Para comparações complexas, limite a 4-6 colunas para legibilidade.
</Callout>

### Cabeçalhos e Seções

Cabeçalhos criam uma estrutura clara de documento, tornando respostas longas escaneáveis e organizadas. Use-os para relatórios, análises ou qualquer resposta com múltiplas partes. Cabeçalhos hierárquicos (##, ###) mostram relacionamentos entre seções.

```
Analise esta proposta de negócio.

Estruture sua resposta com estas seções:
## Resumo Executivo
## Pontos Fortes
## Pontos Fracos
## Recomendações
## Avaliação de Riscos
```

<Callout type="tip" title="Melhores Práticas para Seções">
Liste suas seções na ordem que você quer. Para consistência, especifique o que cada seção deve conter (ex: "Resumo Executivo: apenas 2-3 frases").
</Callout>

### Ênfase com Diretivas em Maiúsculas

Palavras em maiúsculas funcionam como sinais fortes para o modelo, enfatizando restrições ou requisitos críticos. Use-as com moderação para máximo impacto—uso excessivo dilui sua eficácia.

**Diretivas Comuns em Maiúsculas:**

<InfoGrid items={[
  { label: "NUNCA", description: "Proibição absoluta: \"NUNCA inclua opiniões pessoais\"", color: "red" },
  { label: "SEMPRE", description: "Requisito obrigatório: \"SEMPRE cite fontes\"", color: "green" },
  { label: "IMPORTANTE", description: "Instrução crítica: \"IMPORTANTE: Mantenha respostas abaixo de 100 palavras\"", color: "amber" },
  { label: "NÃO", description: "Proibição forte: \"NÃO invente estatísticas\"", color: "red" },
  { label: "DEVE", description: "Ação requerida: \"Saída DEVE ser JSON válido\"", color: "blue" },
  { label: "APENAS", description: "Restrição: \"Retorne APENAS o código, sem explicações\"", color: "purple" },
]} />

```
Resuma este artigo.

IMPORTANTE: Mantenha o resumo abaixo de 100 palavras.
NUNCA adicione informação não presente no original.
SEMPRE mantenha o tom e perspectiva originais.
NÃO inclua suas próprias opiniões ou análise.
```

<Callout type="warning" title="Use Com Moderação">
Se tudo está em maiúsculas ou marcado como crítico, nada se destaca. Reserve essas diretivas para restrições genuinamente importantes.
</Callout>

## Saída JSON

JSON (JavaScript Object Notation) é o formato mais popular para saída estruturada de IA. É legível por máquina, amplamente suportado por linguagens de programação, e perfeito para APIs, bancos de dados e fluxos de trabalho de automação. A chave para JSON confiável é fornecer um schema claro.

### Requisição JSON Básica

Comece com um template mostrando a estrutura exata que você quer. Inclua nomes de campos, tipos de dados e valores de exemplo. Isso funciona como um contrato que o modelo vai seguir.

<TryIt 
  title="Extração JSON"
  description="Extraia dados estruturados de texto não estruturado."
  prompt={`Extraia informações deste texto e retorne como JSON:

{
    "nome_empresa": "string",
    "ano_fundacao": number,
    "sede": "string",
    "funcionarios": number,
    "industria": "string"
}

Texto: "Apple Inc., fundada em 1976, tem sede em Cupertino, Califórnia. A gigante de tecnologia emprega aproximadamente 164.000 pessoas em todo o mundo."`}
/>

### Estruturas JSON Complexas

Para dados aninhados, use JSON hierárquico com objetos dentro de objetos, arrays de objetos e tipos mistos. Defina cada nível claramente e use anotações estilo TypeScript (`"positive" | "negative"`) para restringir valores.

```
Analise esta avaliação de produto e retorne JSON:

{
  "review_id": "string (gere único)",
  "sentimento": {
    "geral": "positivo" | "negativo" | "misto" | "neutro",
    "score": 0.0-1.0
  },
  "aspectos": [
    {
      "aspecto": "string (ex: 'preço', 'qualidade')",
      "sentimento": "positivo" | "negativo" | "neutro",
      "mencoes": ["citações exatas da avaliação"]
    }
  ],
  "intencao_compra": {
    "recomendaria": boolean,
    "confianca": 0.0-1.0
  },
  "frases_chave": ["array de frases notáveis"]
}

Retorne APENAS JSON válido, sem texto adicional.

Avaliação: "[texto da avaliação]"
```

### Garantindo JSON Válido

Modelos às vezes adicionam texto explicativo ou formatação markdown ao redor do JSON. Previna isso com instruções explícitas sobre formato de saída. Você pode solicitar JSON puro ou JSON dentro de blocos de código—escolha baseado nas suas necessidades de parsing.

Adicione instruções explícitas:

```
IMPORTANTE:
- Retorne APENAS o objeto JSON, sem blocos de código markdown
- Garanta que todas as strings estejam corretamente escapadas
- Use null para valores ausentes, não undefined
- Valide que a saída é JSON parseável
```

Ou solicite blocos de código pedindo ao modelo para envolver sua saída:

````
Retorne o resultado como bloco de código JSON:
```json
{ ... }
```
````

## Saída YAML

YAML é mais legível por humanos que JSON, usando indentação em vez de colchetes. É o padrão para arquivos de configuração (Docker, Kubernetes, GitHub Actions) e funciona bem quando a saída será lida por humanos ou usada em contextos DevOps. YAML é sensível a indentação, então seja específico sobre requisitos de formatação.

<TryIt 
  compact
  title="Geração YAML"
  prompt={`Gere um workflow do GitHub Actions para um projeto Node.js.

Retorne como YAML válido:
- Inclua: estágios de install, lint, test, build
- Use Node.js 18
- Cache de dependências npm
- Execute em push para main e pull requests`}
/>

## Saída XML

XML ainda é necessário para muitos sistemas empresariais, APIs SOAP e integrações legadas. É mais verboso que JSON mas oferece recursos como atributos, namespaces e seções CDATA para dados complexos. Especifique nomes de elementos, estrutura de aninhamento e onde usar atributos vs. elementos filhos.

```
Converta estes dados para formato XML:

Requisitos:
- Elemento raiz: <catalogo>
- Cada item em elemento <livro>
- Inclua atributos onde apropriado
- Use CDATA para texto de descrição

Dados: [dados do livro]
```

## Formatos Customizados

Às vezes formatos padrão não atendem suas necessidades. Você pode definir qualquer formato customizado fornecendo um template claro. Formatos customizados funcionam bem para relatórios, logs ou saídas específicas de domínio que serão lidas por humanos.

### Formato de Análise Estruturada

Use delimitadores (===, ---, [SEÇÃO]) para criar documentos escaneáveis com limites claros entre seções. Este formato é ótimo para code reviews, auditorias e análises.

```
Analise este código usando este formato exato:

=== ANÁLISE DE CÓDIGO ===

[RESUMO]
Um parágrafo de visão geral

[PROBLEMAS]
• CRÍTICO: [problema] — [arquivo:linha]
• ALERTA: [problema] — [arquivo:linha]  
• INFO: [problema] — [arquivo:linha]

[MÉTRICAS]
Complexidade: [Baixa/Média/Alta]
Manutenibilidade: [score]/10
Cobertura de Testes: [% estimado]

[RECOMENDAÇÕES]
1. [Recomendação prioridade 1]
2. [Recomendação prioridade 2]

=== FIM DA ANÁLISE ===
```

### Formato de Preencher Lacunas

Templates com lacunas (___) guiam o modelo a preencher campos específicos mantendo formatação exata. Esta abordagem é excelente para formulários, briefs e documentos padronizados onde consistência importa.

```
Complete este template para o produto dado:

BRIEF DO PRODUTO
─────────────
Nome: _______________
Tagline: _______________
Usuário Alvo: _______________
Problema Resolvido: _______________
Recursos Principais:
  1. _______________
  2. _______________
  3. _______________
Diferencial: _______________

Produto: [descrição do produto]
```

## Respostas Tipadas

Respostas tipadas definem categorias ou tipos de entidade que o modelo deve reconhecer e rotular. Esta técnica é essencial para Reconhecimento de Entidades Nomeadas (NER), tarefas de classificação e qualquer extração onde você precisa categorizar informação consistentemente. Defina seus tipos claramente com exemplos.

<TryIt 
  compact
  title="Extração de Entidades"
  prompt={`Extraia entidades deste texto.

Tipos de Entidade:
- PESSOA: Nomes completos de pessoas
- ORG: Nomes de organizações/empresas
- LOCAL: Cidades, países, endereços
- DATA: Datas em formato ISO (AAAA-MM-DD)
- DINHEIRO: Valores monetários com moeda

Formate cada como: [TIPO]: [valor]

Texto: "Tim Cook anunciou que a Apple investirá $1 bilhão em uma nova instalação em Austin até dezembro de 2024."`}
/>

## Respostas Estruturadas Multi-Partes

Quando você precisa de saída abrangente cobrindo múltiplos aspectos, defina partes distintas com limites claros. Especifique exatamente o que vai em cada parte—formato, tamanho e tipo de conteúdo. Isso previne o modelo de misturar seções ou omitir partes.

```
Pesquise este tópico e forneça:

### PARTE 1: RESUMO EXECUTIVO
[Visão geral de 2-3 frases]

### PARTE 2: DESCOBERTAS PRINCIPAIS
[Exatamente 5 pontos]

### PARTE 3: TABELA DE DADOS
| Métrica | Valor | Fonte |
|---------|-------|-------|
[Inclua mínimo 5 linhas]

### PARTE 4: RECOMENDAÇÕES
[Lista numerada de 3 recomendações acionáveis]

### PARTE 5: LEITURA ADICIONAL
[3 recursos sugeridos com breves descrições]
```

## Formatação Condicional

Formatação condicional permite definir diferentes formatos de saída baseados nas características da entrada. Isso é poderoso para classificação, triagem e sistemas de roteamento onde o formato de resposta deve variar baseado no que o modelo detecta. Use lógica if/then clara com templates de saída explícitos para cada caso.

<TryIt 
  compact
  title="Classificação de Ticket"
  prompt={`Classifique este ticket de suporte.

Se URGENTE (sistema fora, problema de segurança, perda de dados):
  Retorne: 🔴 URGENTE | [Categoria] | [Ação Sugerida]

Se ALTO (afeta múltiplos usuários, impacto de receita):
  Retorne: 🟠 ALTO | [Categoria] | [Ação Sugerida]

Se MÉDIO (único usuário afetado, workaround existe):
  Retorne: 🟡 MÉDIO | [Categoria] | [Ação Sugerida]

Se BAIXO (perguntas, solicitações de recursos):
  Retorne: 🟢 BAIXO | [Categoria] | [Ação Sugerida]

Ticket: "Não consigo fazer login na minha conta. Tentei resetar minha senha duas vezes mas ainda recebo erro. Isso está bloqueando toda minha equipe de acessar o dashboard."`}
/>

## Arrays e Listas em JSON

Extrair múltiplos itens em arrays requer definição cuidadosa de schema. Especifique a estrutura do array, o que cada item deve conter, e como lidar com casos limite (arrays vazios, itens únicos). Incluir um campo de contagem ajuda a verificar completude.

```
Extraia todos os itens de ação desta transcrição de reunião.

Retorne como array JSON:
{
  "itens_acao": [
    {
      "tarefa": "string descrevendo a tarefa",
      "responsavel": "nome da pessoa ou 'Não Atribuído'",
      "prazo": "data se mencionada, senão null",
      "prioridade": "alta" | "media" | "baixa",
      "contexto": "citação relevante da transcrição"
    }
  ],
  "contagem_total": number
}

Transcrição: "[transcrição da reunião]"
```

## Instruções de Validação

Auto-validação instrui o modelo a verificar sua própria saída antes de responder. Isso captura problemas comuns como seções faltando, texto placeholder ou violações de restrições. O modelo vai iterar internamente para corrigir problemas, melhorando qualidade da saída sem chamadas de API adicionais.

```
Gere o relatório, então:

CHECKLIST DE VALIDAÇÃO:
□ Todas as seções requeridas presentes
□ Nenhum texto placeholder restante
□ Todas estatísticas incluem fontes
□ Contagem de palavras entre 500-700
□ Conclusão conecta de volta à introdução

Se qualquer verificação falhar, corrija antes de responder.
```

## Lidando com Campos Opcionais

Dados do mundo real frequentemente têm valores ausentes. Instrua explicitamente o modelo sobre como lidar com campos opcionais—usar `null` é mais limpo que strings vazias e mais fácil de processar programaticamente. Também previna "alucinação" de dados faltantes enfatizando que o modelo nunca deve inventar informação.

```
Extraia informações de contato. Use null para campos ausentes.

{
  "nome": "string (obrigatório)",
  "email": "string ou null",
  "telefone": "string ou null", 
  "empresa": "string ou null",
  "cargo": "string ou null",
  "linkedin": "string URL ou null"
}

IMPORTANTE: 
- Nunca invente informação não presente na fonte
- Use null, não strings vazias, para dados ausentes
- Números de telefone em formato E.164 se possível
```

## Resumo

<Callout type="tip" title="Técnicas Principais">
Seja explícito sobre formato, use exemplos, especifique tipos, lide com casos limite com valores null, e peça ao modelo para validar sua própria saída.
</Callout>

<Quiz 
  question="Qual é a principal vantagem de saída estruturada sobre texto não estruturado?"
  options={[
    "Usa menos tokens",
    "É mais fácil para a IA gerar",
    "Pode ser parseada programaticamente e validada",
    "Sempre produz informação correta"
  ]}
  correctIndex={2}
  explanation="Saídas estruturadas como JSON podem ser parseadas por código, comparadas entre consultas, integradas em fluxos de trabalho e validadas para completude—coisas que são difíceis ou impossíveis com texto livre."
/>

Saídas estruturadas são essenciais para construir aplicações confiáveis alimentadas por IA. No próximo capítulo, exploraremos prompting chain-of-thought para tarefas de raciocínio complexo.
