Guias

Saídas estruturadas no SDK

Obtenha resultados JSON validados de fluxos de trabalho de agentes

Obtenha JSON estruturado e validado de fluxos de trabalho de agentes. O Agent SDK suporta saídas estruturadas através de JSON Schemas, garantindo que seus agentes retornem dados exatamente no formato que você precisa.

Quando usar saídas estruturadas

Use saídas estruturadas quando você precisar de JSON validado após um agente completar um fluxo de trabalho multi-turno com ferramentas (buscas de arquivo, execução de comando, pesquisa na web, etc.).

Para chamadas de API única sem uso de ferramentas, consulte Saídas Estruturadas de API.

Por que usar saídas estruturadas

Saídas estruturadas fornecem integração confiável e type-safe com suas aplicações:

Estrutura validada: Sempre receba JSON válido correspondendo ao seu schema
Integração simplificada: Nenhum código de análise ou validação necessário
Segurança de tipo: Use com dicas de tipo TypeScript ou Python para segurança end-to-end
Separação limpa: Defina requisitos de saída separadamente das instruções de tarefa
Autonomia de ferramentas: O agente escolhe quais ferramentas usar enquanto garante o formato de saída

Como funcionam as saídas estruturadas

Defina seu JSON schema
Crie um JSON Schema que descreva a estrutura que você quer que o agente retorne. O schema usa o formato padrão de JSON Schema.
Adicione o parâmetro outputFormat
Inclua o parâmetro outputFormat nas opções de sua query com type: "json_schema" e sua definição de schema.
Execute sua query
O agente usa qualquer ferramenta que precisar para completar a tarefa (operações de arquivo, comandos, pesquisa na web, etc.).
Acesse a saída validada
O resultado final do agente será JSON válido correspondendo ao seu schema, disponível em message.structured_output.

Recursos de JSON Schema suportados

O Agent SDK suporta os mesmos recursos e limitações de JSON Schema que Saídas Estruturadas de API.

Recursos principais suportados:

Todos os tipos básicos: object, array, string, integer, number, boolean, null
enum, const, required, additionalProperties (deve ser false)
Formatos de string: date-time, date, email, uri, uuid, etc.
$ref, $def, e definitions

Para detalhes completos sobre recursos suportados, limitações e suporte a padrões regex, consulte Limitações de JSON Schema na documentação da API.

Exemplo: agente de rastreamento de TODO

Aqui está um exemplo completo mostrando um agente que pesquisa código para TODOs e extrai informações de git blame:

O agente usa autonomamente as ferramentas certas (Grep, Bash) para reunir informações e retorna dados validados.

Tratamento de erros

Se o agente não conseguir produzir saída válida correspondendo ao seu schema, você receberá um resultado de erro:

for await (const msg of query({
  prompt: 'Analyze the data',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: mySchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      console.error('Could not produce valid output')
    }
  }
}

Recursos relacionados

Documentação de JSON Schema
Saídas Estruturadas de API - Para chamadas de API única
Ferramentas personalizadas - Defina ferramentas para seus agentes
Referência do SDK TypeScript - API TypeScript completa
Referência do SDK Python - API Python completa

Por que usar saídas estruturadas

Saídas estruturadas fornecem integração confiável e type-safe com suas aplicações:

Estrutura validada: Sempre receba JSON válido correspondendo ao seu schema

Integração simplificada: Nenhum código de análise ou validação necessário

Segurança de tipo: Use com dicas de tipo TypeScript ou Python para segurança end-to-end

Separação limpa: Defina requisitos de saída separadamente das instruções de tarefa

Autonomia de ferramentas: O agente escolhe quais ferramentas usar enquanto garante o formato de saída

Como funcionam as saídas estruturadas

Defina seu JSON schema
Crie um JSON Schema que descreva a estrutura que você quer que o agente retorne. O schema usa o formato padrão de JSON Schema.
Adicione o parâmetro outputFormat
Inclua o parâmetro outputFormat nas opções de sua query com type: "json_schema" e sua definição de schema.
Execute sua query
O agente usa qualquer ferramenta que precisar para completar a tarefa (operações de arquivo, comandos, pesquisa na web, etc.).
Acesse a saída validada
O resultado final do agente será JSON válido correspondendo ao seu schema, disponível em message.structured_output.

Recursos de JSON Schema suportados

O Agent SDK suporta os mesmos recursos e limitações de JSON Schema que Saídas Estruturadas de API.

Recursos principais suportados:

Todos os tipos básicos: object, array, string, integer, number, boolean, null

enum, const, required, additionalProperties (deve ser false)

Formatos de string: date-time, date, email, uri, uuid, etc.

$ref, $def, e definitions

Para detalhes completos sobre recursos suportados, limitações e suporte a padrões regex, consulte Limitações de JSON Schema na documentação da API.

Tratamento de erros

Se o agente não conseguir produzir saída válida correspondendo ao seu schema, você receberá um resultado de erro:

for await (const msg of query({
  prompt: 'Analyze the data',
  options: {
    outputFormat: {
      type: 'json_schema',
      schema: mySchema
    }
  }
})) {
  if (msg.type === 'result') {
    if (msg.subtype === 'success' && msg.structured_output) {
      console.log(msg.structured_output)
    } else if (msg.subtype === 'error_max_structured_output_retries') {
      console.error('Could not produce valid output')
    }
  }
}