Salidas estructuradas con los modelos Claude de Anthropic

Los resultados estructurados te permiten restringir el resultado generado de un modelo de Claude para que se ajuste exactamente a un esquema JSON específico. Esto es útil para garantizar que las respuestas de tus modelos de Claude siempre tengan el formato preciso que se requiere para las aplicaciones, las bases de datos y las canalizaciones de procesamiento posteriores.

Los resultados estructurados proporcionan dos funciones complementarias que puedes usar de forma independiente o juntas en la misma solicitud:

  • Salidas en formato JSON (output_config.format): Restringe la respuesta de texto del modelo a un objeto JSON que coincida con un esquema que proporciones. Úsalo cuando necesites extraer datos estructurados del texto, generar informes estructurados o dar formato a las respuestas de la API.
  • Uso estricto de herramientas (tools[].strict): Garantiza que los argumentos que el modelo pasa a una herramienta coincidan con el input_schema de la herramienta. Úsalo cuando necesites llamadas a funciones con seguridad de tipos en flujos de trabajo basados en agentes.

Para obtener más información, consulta la documentación de Anthropic sobre Building with Claude: Structured Outputs y Strict tool use.

Modelos de Anthropic Claude compatibles

Agent Platform de Gemini Enterprise admite resultados estructurados para los siguientes modelos de Claude de Anthropic:

  • Claude Opus 4.7
  • Claude Sonnet 4.6
  • Claude Opus 4.6
  • (Próximamente) Claude Opus 4.5
  • (Próximamente) Claude Sonnet 4.5
  • (Próximamente) Claude Haiku 4.5

Controla el acceso a los resultados estructurados

De forma predeterminada, las salidas estructuradas están inhabilitadas por la restricción de la política de la organización constraints/vertexai.allowedPartnerModelFeatures. Para habilitar las salidas estructuradas, debes configurar esta restricción para permitir explícitamente la función structured_outputs.

Además, puedes configurar la restricción de la política de la organización constraints/vertexai.allowedModels para restringir el acceso a los modelos de Claude.

Si deseas obtener instrucciones detalladas para configurar restricciones de políticas de la organización, consulta Controla el acceso a los modelos de Model Garden.

Envía una solicitud de salida estructurada

Para solicitar un resultado en formato JSON, envía una solicitud POST al extremo del modelo de publicador y, luego, incluye el parámetro output_config en el cuerpo de la solicitud. El parámetro output_config especifica el esquema JSON al que debe ajustarse la respuesta del modelo.

REST

En el siguiente ejemplo, se muestra cómo enviar una solicitud a la API de Agent Platform que extrae información de contacto estructurada de un correo electrónico no estructurado. La respuesta se limita a un objeto JSON con los campos name, email, plan_interest y demo_requested.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: Es una región que admite modelos de Claude Anthropic. Para usar el extremo global, consulta Cómo especificar el extremo global.
  • MODEL: Un modelo de Claude compatible, por ejemplo, claude-opus-4-7.
  • ROLE: El rol asociado a un mensaje. Puedes especificar un user o un assistant. El primer mensaje debe usar el rol user. Los modelos de Claude operan con turnos alternativos de user y assistant. Si el mensaje final usa el rol assistant, el contenido de la respuesta continúa inmediatamente desde el contenido de ese mensaje. Puedes usar esto para restringir parte de la respuesta del modelo.
  • CONTENT: el contenido, como texto, del mensaje user o assistant. Por ejemplo: 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: Cantidad máxima de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente 3.5 caracteres. 100 tokens corresponden a casi 60 u 80 palabras.

    Especifica un valor más bajo para las respuestas más cortas y un valor más alto para las respuestas potencialmente más largas.

  • STREAM: Un valor booleano que especifica si la respuesta se transmite o no. Configúralo como true para transmitir la respuesta y false para mostrar la respuesta de una sola vez. Por lo general, los resultados estructurados se devuelven con false.

En el ejemplo, se usan los siguientes campos de salida estructurada. Para obtener detalles sobre cada campo, consulta la sección Campos de solicitud.

  • output_config: Es el bloque de configuración de nivel superior que controla la estructura de la respuesta del modelo.
  • output_config.format.type: Se establece en json_schema para restringir la respuesta a un objeto JSON que se ajuste al esquema proporcionado.
  • output_config.format.schema: Es un esquema JSON que define la estructura requerida de la respuesta del modelo. El esquema debe cumplir con el subconjunto de esquemas JSON admitido.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: El campo text del bloque content contiene una cadena JSON que se ajusta al esquema que especificaste en output_config.

Campos de la solicitud

Los siguientes campos son específicos de los resultados en formato JSON. Para obtener información sobre los otros campos de la solicitud, consulta la referencia de la API de mensajes de Claude.

  • output_config: Es el bloque de configuración de nivel superior que controla la estructura de la respuesta del modelo.
  • output_config.format: Es la definición del formato de salida. Solo se admite el tipo json_schema.
  • output_config.format.type: Es el tipo de formato de salida que se aplicará. Establece este parámetro en json_schema para restringir la respuesta a un objeto JSON.

  • output_config.format.schema: Es un esquema JSON que define la estructura requerida de la respuesta del modelo. Las salidas estructuradas admiten el esquema JSON estándar con algunas limitaciones, como requerir que additionalProperties se establezca en false para los objetos y no admitir restricciones numéricas o de longitud de cadena. Para obtener la lista completa de funciones compatibles y no compatibles, consulta la documentación sobre las limitaciones del esquema JSON de Anthropic. Dentro del esquema, sueles especificar lo siguiente:

    • type: Es el tipo JSON del valor en este nivel (lo más común es object para el esquema raíz).
    • properties: Es un mapa de nombres de campos y sus definiciones de tipo, que describen cada campo que debe devolver el modelo.
    • required: Es una lista de nombres de propiedades que el modelo debe incluir en su respuesta.
    • additionalProperties: Es un valor booleano que, cuando se establece en false, impide que el modelo incluya campos que no se declaran en properties.

Usa herramientas estrictas

El uso estricto de herramientas garantiza que los argumentos que el modelo pasa a una herramienta coincidan con el input_schema de la herramienta. Sin el modo estricto, el modelo podría llamar a una herramienta con argumentos con un tipo incorrecto (por ejemplo, "2" en lugar de 2) o bien omitir campos obligatorios, lo que puede interrumpir las funciones posteriores y requerir lógica de reintento. Con el modo estricto habilitado, la API usa un muestreo restringido por la gramática para garantizar lo siguiente:

  • La herramienta name siempre es una de las herramientas que proporcionaste.
  • La herramienta input siempre se ajusta a la input_schema de la herramienta.

Usa el uso estricto de herramientas cuando necesites validar parámetros de herramientas, crear flujos de trabajo de agentes, garantizar llamadas a funciones con seguridad de tipos o controlar herramientas complejas con propiedades anidadas.

Para habilitar el uso estricto de herramientas, establece "strict": true como un campo de nivel superior en la definición de tu herramienta, junto con name, description y input_schema.

REST

En el siguiente ejemplo, se muestra cómo enviar una solicitud a la API de Agent Platform que define una herramienta get_weather estricta. Se garantiza que el modelo llamará a la herramienta con una cadena location y un unit opcional que puede ser celsius o fahrenheit.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • LOCATION: Es una región que admite modelos de Claude Anthropic. Para usar el extremo global, consulta Cómo especificar el extremo global.
  • MODEL: Un modelo de Claude compatible, por ejemplo, claude-opus-4-7.
  • ROLE: El rol asociado a un mensaje. El primer mensaje debe usar el rol user.
  • CONTENT: el contenido, como texto, del mensaje user o assistant. Por ejemplo: What is the weather in San Francisco?
  • MAX_TOKENS: Cantidad máxima de tokens que se pueden generar en la respuesta. Un token tiene aproximadamente 3.5 caracteres. 100 tokens corresponden a casi 60 u 80 palabras.

    Especifica un valor más bajo para las respuestas más cortas y un valor más alto para las respuestas potencialmente más largas.

  • STREAM: Un valor booleano que especifica si la respuesta se transmite o no. Configúralo como true para transmitir la respuesta y false para mostrar la respuesta de una sola vez.

En el ejemplo, se usan los siguientes campos estrictos de uso de herramientas. Para obtener detalles sobre cada campo, consulta la sección Campos de uso estricto de herramientas.

  • tools[].strict: Es un valor booleano que, cuando se establece en true, habilita el muestreo restringido por la gramática para la herramienta. Se garantiza que el modelo llamará a la herramienta con argumentos que coincidan con el input_schema.
  • tools[].input_schema: Es un esquema JSON que define los argumentos que el modelo puede pasar a la herramienta. Cuando strict es true, el esquema debe cumplir con el mismo subconjunto de esquema JSON admitido que el esquema output_config para las salidas JSON.

Método HTTP y URL: 

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

Cuerpo JSON de la solicitud:

{
  "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 tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

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

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

$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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación: El bloque de contenido tool_use contiene un campo input cuyas claves y tipos de valores coinciden con el input_schema de la herramienta.

Campos de uso estricto de herramientas

Los siguientes campos son específicos para el uso estricto de la herramienta. Para obtener información sobre los otros campos de definición de herramientas, consulta la documentación de Define tools de Anthropic.

  • tools[].strict: Es un valor booleano que, cuando se establece en true, habilita el muestreo restringido por la gramática para la herramienta. Cuando strict es true, la entrada de la herramienta del modelo se limita para que coincida con el esquema en input_schema. El valor predeterminado es false.

  • tools[].input_schema: Es un esquema JSON que define los argumentos que el modelo puede pasar a la herramienta. Cuando strict es true, el esquema debe cumplir con el mismo subconjunto de JSON Schema que usan los resultados de JSON. En concreto, debes hacer lo siguiente:

    • Configura additionalProperties en false en cada objeto del esquema.
    • Enumera cada propiedad del array required.

    Para obtener la lista completa de funciones compatibles y no compatibles, consulta la documentación sobre las limitaciones del esquema JSON de Anthropic.