O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Saída estruturada para modelos do Grok

As saídas estruturadas permitem que um modelo gere saídas que sempre seguem um esquema específico. Por exemplo, um modelo pode receber um esquema de resposta para garantir que a resposta produza um JSON válido. Os modelos Grok disponíveis no modelo como serviço (MaaS) da Gemini Enterprise Agent Platform oferecem suporte a saídas estruturadas.

Para mais informações conceituais sobre o recurso de saída estruturada, consulte Introdução à saída estruturada.

Usar saídas estruturadas com a API Responses

O valor padrão de store é false. Portanto, as solicitações são sem estado, a menos que você defina store como true (ou True em Python). Para armazenar respostas, consulte Fazer uma chamada com estado para a API Responses.

Os modelos a seguir mostram como usar saídas estruturadas com a API Responses:

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. Para mais informações, consulte Autenticação e credenciais.

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="MODEL",
    input="INPUT",
    text={
        "format": {
            "type": "json_schema",
            "name": "SCHEMA_NAME",
            "strict": True,
            "schema": JSON_SCHEMA
        }
    },
    stream=False,
)
print(response)

MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
INPUT: o comando ou a entrada para o modelo.
SCHEMA_NAME: um nome para o esquema de resposta.
JSON_SCHEMA: um dicionário que define o esquema JSON, por exemplo:
{"type": "object", "properties": {"name": {"type": "string"}, "age": {"type": "integer"}}, "required": ["name", "age"], "additionalProperties": False}

REST

Antes de usar os dados da solicitação abaixo, faça estas substituições:

PROJECT_ID: o ID do projeto do Google Cloud .
MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.20-reasoning.
INPUT: o comando ou a entrada para o modelo.
SCHEMA_NAME: um nome para o esquema de resposta.
JSON_SCHEMA: um objeto de esquema JSON que define a estrutura da saída.

Método HTTP e URL:

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses

Corpo JSON da solicitação:

{
  "model": "MODEL",
  "input": "INPUT",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "SCHEMA_NAME",
      "strict": true,
      "schema": JSON_SCHEMA
    }
  },
  "stream": false
}

Para enviar a solicitação, escolha uma destas opções:

curl

Observação: o comando a seguir pressupõe que você tenha feito login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login ou usando o Cloud Shell, que faz login automaticamente na gcloud CLI. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses"

PowerShell

Observação: o comando a seguir pressupõe que você fez login na gcloud CLI com sua conta de usuário executando gcloud init ou gcloud auth login. Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses" | Select-Object -Expand Content

Exemplo

Os exemplos a seguir mostram um exemplo completo de uso de saídas estruturadas com a API Responses:

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. Para mais informações, consulte Autenticação e credenciais.

from openai import OpenAI
client = OpenAI()

response = client.responses.create(
    model="xai/grok-4.7",
    input="Extract: John Doe is 30.",
    text={
        "format": {
            "type": "json_schema",
            "name": "person_info",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"}
                },
                "required": ["name", "age"],
                "additionalProperties": False
            }
        }
    },
    stream=False,
)
print(response)

REST

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/endpoints/openapi/responses -d \
'{
  "model": "xai/grok-4.7",
  "input": "Extract: John Doe is 30.",
  "text": {
    "format": {
      "type": "json_schema",
      "name": "person_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "age": {
            "type": "integer"
          }
        },
        "required": [
          "name",
          "age"
        ],
        "additionalProperties": false
      }
    }
  },
  "stream": false
}'

PROJECT_ID: o ID do projeto do Google Cloud .

Exemplo de resposta

Confira um exemplo de como seria a saída do modelo:

{
  "background": false,
  "completed_at": 1793837914,
  "created_at": 1793837914,
  "error": null,
  "frequency_penalty": 0,
  "id": "d18533b9-ecdc-447d-9bbd-f061359c89e9",
  "incomplete_details": null,
  "instructions": null,
  "max_output_tokens": null,
  "max_tool_calls": null,
  "metadata": {
    "system_fingerprint": "fp_grok47_0"
  },
  "model": "xai/grok-4.7",
  "object": "response",
  "output": [
    {
      "content": [
        {
          "annotations": [],
          "logprobs": [],
          "text": "{\"age\":30,\"name\":\"John Doe\"}",
          "type": "output_text"
        }
      ],
      "id": "msg_d18533b9-ecdc-447d-9bbd-f061359c89e9",
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "presence_penalty": 0,
  "previous_response_id": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": "high",
    "summary": "detailed"
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "store": false,
  "temperature": 0.7,
  "text": {
    "format": {
      "schema": {
        "additionalProperties": false,
        "properties": {
          "age": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "age"
        ],
        "type": "object"
      },
      "type": "json_schema"
    }
  },
  "tool_choice": "auto",
  "tools": [],
  "top_logprobs": 0,
  "top_p": 0.95,
  "truncation": "disabled",
  "usage": {
    "context_details": {
      "input_tokens": 276,
      "output_tokens": 70
    },
    "extra_properties": {
      "google": {
        "traffic_type": "ON_DEMAND"
      }
    },
    "input_tokens": 276,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "num_server_side_tools_used": 0,
    "num_sources_used": 0,
    "output_tokens": 70,
    "output_tokens_details": {
      "reasoning_tokens": 59
    },
    "total_tokens": 346
  },
  "user": null
}

Usar saídas estruturadas com a API Chat Completions

O caso de uso a seguir define um esquema de resposta que garante que a saída do modelo seja um objeto JSON com as seguintes propriedades: nome, data e participantes. O código Python usa o SDK da OpenAI e objetos Pydantic para gerar o esquema JSON.

from pydantic import BaseModel
from openai import OpenAI

client = OpenAI()

class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]

completion = client.beta.chat.completions.parse(
    model="MODEL_NAME",
    messages=[
        {"role": "system", "content": "Extract the event information."},
        {"role": "user", "content": "Alice and Bob are going to a science fair on Friday."},
    ],
    response_format=CalendarEvent,
)

print(completion.choices[0].message.parsed)

A saída do modelo vai seguir este esquema JSON:

{ "name": STRING, "date": STRING, "participants": [STRING] }

Ao receber o comando "Alice e Bob vão a uma feira de ciências na sexta-feira", o modelo pode produzir a seguinte resposta:

{
  "name": "science fair",
  "date": "Friday",
  "participants": [
    "Alice",
    "Bob"
  ]
}

exemplo detalhado

O código a seguir é um exemplo de esquema recursivo. A classe UI contém uma lista de children, que também pode ser da classe UI.

from pydantic import BaseModel
from openai import OpenAI
from enum import Enum
from typing import List

client = OpenAI()

class UIType(str, Enum):
  div = "div"
  button = "button"
  header = "header"
  section = "section"
  field = "field"
  form = "form"

class Attribute(BaseModel):
  name: str
  value: str

class UI(BaseModel):
  type: UIType
  label: str
  children: List["UI"]
  attributes: List[Attribute]

UI.model_rebuild() # This is required to enable recursive types

class Response(BaseModel):
  ui: UI

completion = client.beta.chat.completions.parse(
  model="MODEL_NAME",
  messages=[
    {"role": "system", "content": "You are a UI generator AI. Convert the user input into a UI."},
    {"role": "user", "content": "Make a User Profile Form"}
  ],
  response_format=Response,
)

print(completion.choices[0].message.parsed)

A saída do modelo vai seguir o esquema do objeto Pydantic especificado no snippet anterior. Neste exemplo, o modelo pode gerar o seguinte formulário de UI:

Form
  Input
    Name
    Email
    Age

A resposta pode ser assim:

ui = UI(
    type=UIType.div,
    label='Form',
    children=[
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Name')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Email')
            ]
        ),
        UI(
            type=UIType.div,
            label='Input',
            children=[],
            attributes=[
                Attribute(name='label', value='Age')
            ]
        )
    ],
    attributes=[
        Attribute(name='name', value='John Doe'),
        Attribute(name='email', value='john.doe@example.com'),
        Attribute(name='age', value='30')
    ]
)

Receber respostas de objetos JSON

É possível restringir o modelo para gerar apenas objetos JSON sintaticamente válidos definindo o campo response_format como { "type": "json_object" }. Isso é chamado de modo JSON. O modo JSON é útil ao gerar JSON para uso com chamadas de função ou outras tarefas downstream que exigem entrada JSON.

Quando o modo JSON está ativado, o modelo é restrito a gerar apenas strings que são analisadas em objetos JSON válidos. Embora esse modo garanta que a saída seja um JSON sintaticamente correto, ele não impõe nenhum esquema específico. Para garantir que a saída do modelo gere um JSON que siga um esquema específico, inclua instruções no comando, como mostrado no exemplo a seguir.

Os exemplos a seguir mostram como ativar o modo JSON e instruir o modelo a retornar um objeto JSON com uma estrutura específica:

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de executar este exemplo, defina a variável de ambiente OPENAI_BASE_URL ou configure as credenciais do OAuth. Para mais informações, consulte Autenticação e credenciais.

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
  model="MODEL",
  response_format={ "type": "json_object" },
  messages=[
    {"role": "user", "content": "List 5 rivers in South America. Your response must be a JSON object with a single key "rivers", which has a list of strings as its value."},
  ]
)
print(response.choices[0].message.content)

Substitua MODEL pelo nome do modelo que você quer usar, por exemplo, xai/grok-4.6.

Exemplo de saída

{
  "rivers": [
    "Amazon River",
    "Paraná River",
    "Orinoco River",
    "São Francisco River",
    "Magdalena River"
  ]
}

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID pelo ID do projeto no Google Cloud.
LOCATION: uma região compatível com modelos Grok.
MODEL: o nome do modelo que você quer usar, por exemplo, xai/grok-4.6.

Método HTTP e URL:

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions

Corpo JSON da solicitação:

{
  "model": "MODEL",
  "response_format": {
    "type": "json_object"
  },
  "messages": [
    {
      "role": "user",
      "content": "List 5 rivers in South America. Your response must be a JSON object with a single key \"rivers\", which has a list of strings as its value."
    }
  ]
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/endpoints/openapi/chat/completions" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte.

Resposta

{
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "{\n  \"rivers\": [\n    \"Amazon River\",\n    \"Paraná River\",\n    \"Orinoco River\",\n    \"São Francisco River\",\n    \"Magdalena River\"\n  ]\n}",
        "role": "assistant"
      }
    }
  ],
  "created": 1721860000,
  "id": "123456789",
  "model": "xai/grok-4.6",
  "object": "chat.completion",
  "system_fingerprint": "12345",
  "usage": {
    "completion_tokens": 54,
    "prompt_tokens": 46,
    "total_tokens": 100
  }
}

A seguir

Aprenda mais sobre a chamada de função.
Aprenda mais sobre o Raciocínio.

Saída estruturada para modelos do Grok Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Usar saídas estruturadas com a API Responses

Python

REST

curl

PowerShell

Exemplo

Python

REST

Exemplo de resposta

Usar saídas estruturadas com a API Chat Completions

exemplo detalhado

Receber respostas de objetos JSON

Python

Exemplo de saída

REST

curl

PowerShell

Resposta

A seguir

Saída estruturada para modelos do Grok