Saídas estruturadas com modelos Anthropic Claude

As saídas estruturadas permitem restringir a saída gerada de um modelo do Claude para que ela esteja exatamente em conformidade com um esquema JSON específico. Isso é útil para garantir que as respostas dos modelos do Claude estejam sempre no formato exato exigido para aplicativos, bancos de dados e pipelines de processamento downstream.

As saídas estruturadas oferecem dois recursos complementares que podem ser usados de forma independente ou juntos na mesma solicitação:

  • Saídas JSON (output_config.format): restringem a resposta de texto do modelo a um objeto JSON que corresponde a um esquema fornecido. Use isso quando precisar extrair dados estruturados de texto, gerar relatórios estruturados ou formatar respostas de API.
  • Uso rigoroso de ferramentas (tools[].strict): garante que os argumentos que o modelo transmite a uma ferramenta correspondam ao input_schema da ferramenta. Use isso quando precisar de chamadas de função com segurança de tipo em fluxos de trabalho agênticos.

Para mais informações, consulte a documentação do Anthropic sobre como criar com o Claude: saídas estruturadas e uso rigoroso de ferramentas.

Modelos Anthropic Claude com suporte

A plataforma de agentes do Gemini Enterprise oferece suporte a saídas estruturadas para os seguintes modelos do Anthropic Claude:

  • Claude Opus 4.7
  • Claude Sonnet 4.6
  • Claude Opus 4.6
  • (Em breve) Claude Opus 4.5
  • (Em breve) Claude Sonnet 4.5
  • (Em breve) Claude Haiku 4.5

Controlar o acesso a saídas estruturadas

Por padrão, as saídas estruturadas são desativadas pela restrição de política da organização constraints/vertexai.allowedPartnerModelFeatures. Para ativar as saídas estruturadas, configure essa restrição para permitir explicitamente o recurso structured_outputs.

Além disso, você pode configurar a restrição de política da organização constraints/vertexai.allowedModels para restringir o acesso aos modelos do Claude.

Para instruções detalhadas sobre como configurar restrições de política da organização, consulte Controlar o acesso aos modelos do Model Garden.

Enviar uma solicitação de saída estruturada

Para solicitar uma saída JSON, envie uma solicitação POST para o endpoint do modelo do editor e inclua o parâmetro output_config no corpo da solicitação. O parâmetro output_config especifica o esquema JSON a que a resposta do modelo precisa estar em conformidade.

REST

O exemplo a seguir mostra como enviar uma solicitação para a API da plataforma de agentes que extrai dados de contato estruturadas de um e-mail não estruturado. A resposta é restrita a um objeto JSON com campos name, email, plan_interest e demo_requested.

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

  • LOCATION: uma região compatível com modelos do Anthropic Claude. Para usar o endpoint global, consulte Especificar o endpoint global.
  • MODEL: um modelo do Claude com suporte, por exemplo, claude-opus-4-7.
  • ROLE: o papel associado a uma mensagem. É possível especificar user ou assistant. A primeira mensagem precisa usar o papel user. Os modelos de Claude funcionam com voltas alternadas de user e assistant. Se a mensagem final usar o papel assistant, o conteúdo da resposta continuará imediatamente a partir do conteúdo dessa mensagem. É possível usar isso para restringir parte da resposta do modelo.
  • CONTENT: o conteúdo, como texto, da mensagem user ou assistant. Por exemplo, Extract the key information from this email: John Smith (john@example.com) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm.
  • MAX_TOKENS: Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente 3,5 caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

    Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

  • STREAM: um booleano que especifica se a resposta será transmitida ou não. Defina como true para transmitir a resposta e false para retornar a resposta de uma só vez. As saídas estruturadas geralmente são retornadas com false.

O exemplo usa os seguintes campos de saída estruturada. Para detalhes sobre cada campo, consulte a seção Campos de solicitação.

  • output_config: o bloco de configuração de nível superior que controla a estrutura da resposta do modelo.
  • output_config.format.type: definido como json_schema para restringir a resposta a um objeto JSON que esteja em conformidade com o esquema fornecido schema.
  • output_config.format.schema: um esquema JSON que define a estrutura necessária da resposta do modelo. O esquema precisa estar em conformidade com o subconjunto JSON Schema com suporte.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

Corpo JSON da solicitação: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "output_config": {
    "format": {
      "type": "json_schema",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "email": {"type": "string"},
          "plan_interest": {"type": "string"},
          "demo_requested": {"type": "boolean"}
        },
        "required": ["name", "email", "plan_interest", "demo_requested"],
        "additionalProperties": false
      }
    }
  }
}

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 a seguir: 

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/publishers/anthropic/models/MODEL:rawPredict"

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/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte. O campo text do bloco content contém uma string JSON que está em conformidade com o esquema especificado em output_config.

Campos de solicitação

Os campos a seguir são específicos para saídas JSON. Para informações sobre os outros campos de solicitação, consulte a referência da API de mensagens do Claude.

  • output_config: o bloco de configuração de nível superior que controla a estrutura da resposta do modelo.
  • output_config.format: a definição de formato para a saída. Somente o tipo json_schema é compatível.
  • output_config.format.type: o tipo de formato de saída a ser aplicado. Defina como json_schema para restringir a resposta a um objeto JSON.

  • output_config.format.schema: um esquema JSON que define a estrutura necessária da resposta do modelo. As saídas estruturadas oferecem suporte ao JSON Schema padrão com algumas limitações, como exigir que additionalProperties seja definido como false para objetos e não oferecer suporte a restrições numéricas ou de comprimento de string. Para conferir a lista completa de recursos com suporte e sem suporte, consulte a documentação de limitações do JSON Schema do Anthropic. No esquema, geralmente você especifica:

    • type: o tipo JSON do valor nesse nível (mais comumente object para o esquema raiz).
    • properties: um mapa de nomes de campos para as definições de tipo, que descrevem cada campo que o modelo precisa retornar.
    • required: uma lista de nomes de propriedades que o modelo precisa incluir na resposta.
    • additionalProperties: um booleano que, quando definido como false, impede que o modelo inclua campos que não sejam declarados em properties.

Usar o uso rigoroso de ferramentas

O uso rigoroso de ferramentas garante que os argumentos que o modelo transmite a uma ferramenta correspondam ao input_schema da ferramenta. Sem o modo rigoroso, o modelo pode chamar uma ferramenta com argumentos com tipo incorreto (por exemplo, "2" em vez de 2) ou omitir campos obrigatórios, o que pode interromper as funções downstream e exigir lógica de nova tentativa. Com o modo estrito ativado, a API usa a amostragem restrita por gramática para garantir que:

  • O name da ferramenta seja sempre uma das ferramentas fornecidas.
  • A ferramenta input esteja sempre em conformidade com o input_schema da ferramenta.

Use o uso rigoroso de ferramentas quando precisar validar parâmetros de ferramentas, criar fluxos de trabalho agênticos, garantir chamadas de função com segurança de tipo ou processar ferramentas complexas com propriedades aninhadas.

Para ativar o uso rigoroso de ferramentas, defina "strict": true como um campo de nível superior na sua definição de ferramenta, junto com name, description e input_schema.

REST

O exemplo a seguir mostra como enviar uma solicitação para a API da plataforma de agentes que define uma ferramenta get_weather rigorosa. O modelo tem a garantia de chamar a ferramenta com uma string location e uma unit opcional que seja celsius ou fahrenheit.

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

  • LOCATION: uma região compatível com modelos do Anthropic Claude. Para usar o endpoint global, consulte Especificar o endpoint global.
  • MODEL: um modelo do Claude com suporte, por exemplo, claude-opus-4-7.
  • ROLE: o papel associado a uma mensagem. A primeira mensagem precisa usar o papel user.
  • CONTENT: o conteúdo, como texto, da mensagem user ou assistant. Por exemplo, What is the weather in San Francisco?
  • MAX_TOKENS: Número máximo de tokens que podem ser gerados na resposta. Um token tem aproximadamente 3,5 caracteres. 100 tokens correspondem a cerca de 60 a 80 palavras.

    Especifique um valor mais baixo para respostas mais curtas e um valor mais alto para respostas potencialmente mais longas.

  • STREAM: um booleano que especifica se a resposta será transmitida ou não. Defina como true para transmitir a resposta e false para retornar a resposta de uma só vez.

O exemplo usa os seguintes campos de uso rigoroso de ferramentas. Para detalhes sobre cada campo, consulte a seção Campos de uso rigoroso de ferramentas.

  • tools[].strict: um booleano que, quando definido como true, ativa a amostragem restrita por gramática para a ferramenta. O modelo tem a garantia de chamar a ferramenta com argumentos que correspondam ao input_schema.
  • tools[].input_schema: um esquema JSON que define os argumentos que o modelo pode transmitir à ferramenta. Quando strict é true, o esquema precisa estar em conformidade com o mesmo subconjunto JSON Schema com suporte que o esquema output_config para saídas JSON.

Método HTTP e URL: 

POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/anthropic/models/MODEL:rawPredict

Corpo JSON da solicitação: 

{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "ROLE",
      "content": "CONTENT"
    }
  ],
  "max_tokens": MAX_TOKENS,
  "stream": STREAM,
  "tools": [
    {
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, for example San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }
  ]
}

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 a seguir: 

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/publishers/anthropic/models/MODEL:rawPredict"

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/publishers/anthropic/models/MODEL:rawPredict" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a seguinte. O tool_use bloco de conteúdo contém um campo input cujas chaves e tipos de valor têm a garantia de corresponder ao input_schema da ferramenta.

Campos de uso rigoroso de ferramentas

Os campos a seguir são específicos para uso rigoroso de ferramentas. Para informações sobre os outros campos de definição de ferramentas, consulte a documentação do Anthropic sobre como definir ferramentas.

  • tools[].strict: um booleano que, quando definido como true, ativa a amostragem restrita por gramática para a ferramenta. Quando strict é true, a entrada da ferramenta do modelo é restrita para corresponder ao esquema em input_schema. O valor padrão é false.

  • tools[].input_schema: um esquema JSON que define os argumentos que o modelo pode transmitir à ferramenta. Quando strict é true, o esquema precisa estar em conformidade com o mesmo subconjunto JSON Schema usado pelas saídas JSON. Para isso, siga as etapas a seguir:

    • Defina additionalProperties como false em cada objeto no esquema.
    • Liste todas as propriedades na matriz required.

    Para conferir a lista completa de recursos com suporte e sem suporte, consulte a documentação de limitações do JSON Schema do Anthropic.