Saídas estruturadas com modelos Anthropic Claude

Com as saídas estruturadas, é possível restringir a saída gerada de um modelo do Claude para que ela siga exatamente um esquema JSON específico. Isso é útil para garantir que as respostas dos modelos do Claude estejam sempre no formato preciso 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 da API.
• Uso estrito de ferramentas (tools[].strict): garante que os argumentos que o modelo transmite a uma ferramenta correspondam ao input_schema dela. 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 Como criar com o Claude: saídas estruturadas e Uso estrito de ferramentas da Anthropic.

Modelos Anthropic Claude compatíveis

A Gemini Enterprise Agent Platform oferece suporte a saídas estruturadas para todos os modelos do Claude 4.5 da Anthropic e versões mais recentes.

Controlar o acesso a saídas estruturadas

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

Além disso, é possível 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 ao endpoint do modelo do publisher 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 obedecer.

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

{
  "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
      }
    }
  }
}

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"

$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

{
  "id": "msg_vrtx_01ABcdEFghIJklMNopQRstUV",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-7",
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"John Smith\", \"email\": \"john@example.com\", \"plan_interest\": \"Enterprise\", \"demo_requested\": true}"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 78,
    "output_tokens": 42
  }
}

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 Claude Messages.

• 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 são compatíveis com o esquema JSON padrão, mas têm algumas limitações, como exigir que additionalProperties seja definido como false para objetos e não aceitar restrições numéricas ou de comprimento de string. Para conferir a lista completa de recursos compatíveis e incompatíveis, consulte a documentação de limitações do esquema JSON da Anthropic. No esquema, normalmente você especifica:

  • type: o tipo JSON do valor neste 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 não declarados em properties.

Use a ferramenta de forma restrita

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

• A ferramenta name é sempre uma das ferramentas que você forneceu.
• A ferramenta input sempre está em conformidade com o input_schema dela.

Use o uso estrito de ferramentas quando precisar validar parâmetros de ferramentas, criar fluxos de trabalho de agentes, garantir chamadas de função com segurança de tipo ou lidar com ferramentas complexas com propriedades aninhadas.

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

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

{
  "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
      }
    }
  ]
}

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"

$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

{
  "id": "msg_vrtx_01ABcdEFghIJklMNopQRstUV",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-7",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_vrtx_01TAJCTkxe8HhRoaQ69N4ouP",
      "name": "get_weather",
      "input": {
        "location": "San Francisco, CA",
        "unit": "fahrenheit"
      }
    }
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 412,
    "output_tokens": 64
  }
}

Campos de uso estrito de ferramentas

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

• tools[].strict: um booleano que, quando definido como true, ativa a amostragem com restrição gramatical para a ferramenta. Quando strict é true, a entrada de 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 para a ferramenta. Quando strict é true, o esquema precisa estar de acordo com o mesmo subconjunto de esquema JSON usado pelas saídas JSON. Para isso, siga as etapas a seguir:

  • Defina additionalProperties como false em todos os objetos do esquema.
  • Liste todas as propriedades na matriz required.

  Para conferir a lista completa de recursos compatíveis e incompatíveis, consulte a documentação de limitações do esquema JSON da Anthropic.