Sorties structurées avec les modèles Anthropic Claude

Aperçu

Cette fonctionnalité est soumise aux "Conditions des offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service et aux Conditions supplémentaires pour les produits d'IA générative en version preview. Vous pouvez traiter des données à caractère personnel pour cette fonctionnalité, comme indiqué dans l'Avenant relatif au traitement des données dans le cloud, sous réserve de respecter les obligations et restrictions décrites dans le contrat en vertu duquel vous accédez à Google Cloud. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Les sorties structurées vous permettent de contraindre la sortie générée d'un modèle Claude à se conformer exactement à un schéma JSON spécifique. Cela permet de s'assurer que les réponses de vos modèles Claude sont toujours dans le format précis requis pour les applications, bases de données et pipelines de traitement en aval.

Les sorties structurées offrent deux fonctionnalités complémentaires que vous pouvez utiliser indépendamment ou ensemble dans la même requête :

• Sorties JSON (output_config.format) : contraint la réponse textuelle du modèle à un objet JSON correspondant à un schéma que vous fournissez. Utilisez-le lorsque vous devez extraire des données structurées à partir de texte, générer des rapports structurés ou mettre en forme des réponses d'API.
• Utilisation stricte des outils (tools[].strict) : garantit que les arguments que le modèle transmet à un outil correspondent à la input_schema de l'outil. Utilisez cette option lorsque vous avez besoin d'appels de fonction avec sûreté de typage dans les workflows agentiques.

Pour en savoir plus, consultez la documentation d'Anthropic Building with Claude: Structured Outputs (Créer avec Claude : sorties structurées) et Strict tool use (Utilisation stricte des outils).

Modèles Anthropic Claude compatibles

Gemini Enterprise Agent Platform est compatible avec les sorties structurées pour les modèles Anthropic Claude suivants :

• Claude Opus 4.7
• Claude Sonnet 4.6
• Claude Opus 4.6
• (Bientôt disponible) Claude Opus 4.5
• (Bientôt disponible) Claude Sonnet 4.5
• (Bientôt disponible) Claude Haiku 4.5

Contrôler l'accès aux sorties structurées

Par défaut, les sorties structurées sont désactivées par la contrainte de règle d'administration constraints/vertexai.allowedPartnerModelFeatures. Pour activer les sorties structurées, vous devez configurer cette contrainte afin d'autoriser explicitement la fonctionnalité structured_outputs.

Vous pouvez également configurer la contrainte de règle d'administration constraints/vertexai.allowedModels pour limiter l'accès aux modèles Claude.

Pour obtenir des instructions détaillées sur la configuration des contraintes de règles d'administration, consultez Contrôler l'accès aux modèles Model Garden.

Envoyer une requête de sortie structurée

Pour demander une sortie JSON, envoyez une requête POST au point de terminaison du modèle d'éditeur et incluez le paramètre output_config dans le corps de votre requête. Le paramètre output_config spécifie le schéma JSON auquel la réponse du modèle doit se conformer.

REST

L'exemple suivant montre comment envoyer une requête à l'API Agent Platform pour extraire des informations de contact structurées à partir d'un e-mail non structuré. La réponse est limitée à un objet JSON avec les champs name, email, plan_interest et demo_requested.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

• LOCATION : région compatible avec les modèles Anthropic Claude. Pour utiliser le point de terminaison mondial, consultez Spécifier le point de terminaison mondial.
• MODEL : modèle Claude compatible, par exemple claude-opus-4-7.
• ROLE : rôle associé à un message. Vous pouvez spécifier user ou assistant. Le premier message doit utiliser le rôle user. Les modèles Claude fonctionnent avec des tours user et assistant alternés. Si le message final utilise le rôle assistant, le contenu de la réponse continue immédiatement à partir du contenu de ce message. Cela vous permet de limiter une partie de la réponse du modèle.
• CONTENT : contenu du message user ou assistant (du texte, par exemple). Exemple : Extract the key information from this email: John Smith ([e-mail]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm..
• MAX_TOKENS : nombre maximal de jetons pouvant être générés dans la réponse. Un jeton correspond environ à 3,5 caractères. 100 jetons correspondent environ à 60-80 mots.

  Spécifiez une valeur inférieure pour obtenir des réponses plus courtes et une valeur supérieure pour des réponses potentiellement plus longues.

• STREAM : valeur booléenne qui spécifie si la réponse est diffusée ou non. Définissez la valeur sur true pour diffuser la réponse et sur false pour la renvoyer en une fois. Les sorties structurées sont généralement renvoyées avec false.

L'exemple utilise les champs de sortie structurée suivants. Pour en savoir plus sur chaque champ, consultez la section Champs de requête.

• output_config : bloc de configuration de premier niveau qui contrôle la structure de la réponse du modèle.
• output_config.format.type : définissez sur json_schema pour limiter la réponse à un objet JSON conforme au schéma fourni.
• output_config.format.schema : schéma JSON qui définit la structure requise de la réponse du modèle. Le schéma doit être conforme au sous-ensemble de schéma JSON pris en charge.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON semblable à la suivante. Le champ text du bloc content contient une chaîne JSON conforme au schéma que vous avez spécifié dans output_config.

Réponse

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

Champs des demandes

Les champs suivants sont spécifiques aux sorties JSON. Pour en savoir plus sur les autres champs de requête, consultez la documentation de référence de l'API Claude Messages.

• output_config : bloc de configuration de premier niveau qui contrôle la structure de la réponse du modèle.
• output_config.format : définition du format de sortie. Seul le type json_schema est accepté.
• output_config.format.type : type de format de sortie à appliquer. Définissez cette valeur sur json_schema pour limiter la réponse à un objet JSON.

• output_config.format.schema : schéma JSON qui définit la structure requise de la réponse du modèle. Les sorties structurées sont compatibles avec le schéma JSON standard, mais avec certaines limites. Par exemple, additionalProperties doit être défini sur false pour les objets, et les contraintes numériques ou de longueur de chaîne ne sont pas prises en charge. Pour obtenir la liste complète des fonctionnalités compatibles et non compatibles, consultez la documentation d'Anthropic sur les limitations du schéma JSON. Dans le schéma, vous spécifiez généralement les éléments suivants :

  • type : type JSON de la valeur à ce niveau (le plus souvent object pour le schéma racine).
  • properties : carte des noms de champs et de leurs définitions de type, qui décrivent chaque champ que le modèle doit renvoyer.
  • required : liste des noms de propriétés que le modèle doit inclure dans sa réponse.
  • additionalProperties : valeur booléenne qui, lorsqu'elle est définie sur false, empêche le modèle d'inclure des champs qui ne sont pas déclarés dans properties.

Utiliser strictement les outils

L'utilisation stricte des outils garantit que les arguments que le modèle transmet à un outil correspondent à son input_schema. Sans le mode strict, le modèle peut appeler un outil avec des arguments mal typés (par exemple, "2" au lieu de 2) ou omettre des champs obligatoires, ce qui peut interrompre vos fonctions en aval et nécessiter une logique de réessai. Lorsque le mode strict est activé, l'API utilise un échantillonnage contraint par la grammaire pour s'assurer que :

• L'outil name fait toujours partie de ceux que vous avez fournis.
• L'outil input respecte toujours le input_schema de l'outil.

Utilisez l'utilisation stricte des outils lorsque vous devez valider les paramètres des outils, créer des workflows agentiques, assurer des appels de fonction de type sécurisé ou gérer des outils complexes avec des propriétés imbriquées.

Pour activer l'utilisation stricte des outils, définissez "strict": true comme champ de premier niveau dans votre définition d'outil, à côté de name, description et input_schema.

REST

L'exemple suivant montre comment envoyer une requête à l'API Agent Platform qui définit un outil get_weather strict. Le modèle est garanti d'appeler l'outil avec une chaîne location et un unit facultatif qui est soit celsius, soit fahrenheit.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

• LOCATION : région compatible avec les modèles Anthropic Claude. Pour utiliser le point de terminaison mondial, consultez Spécifier le point de terminaison mondial.
• MODEL : modèle Claude compatible, par exemple claude-opus-4-7.
• ROLE : rôle associé à un message. Le premier message doit utiliser le rôle user.
• CONTENT : contenu du message user ou assistant (du texte, par exemple). Exemple : What is the weather in San Francisco?.
• MAX_TOKENS : nombre maximal de jetons pouvant être générés dans la réponse. Un jeton correspond environ à 3,5 caractères. 100 jetons correspondent environ à 60-80 mots.

  Spécifiez une valeur inférieure pour obtenir des réponses plus courtes et une valeur supérieure pour des réponses potentiellement plus longues.

• STREAM : valeur booléenne qui spécifie si la réponse est diffusée ou non. Définissez la valeur sur true pour diffuser la réponse et sur false pour la renvoyer en une fois.

L'exemple utilise les champs d'utilisation stricte des outils suivants. Pour en savoir plus sur chaque champ, consultez la section Champs d'utilisation stricte des outils.

• tools[].strict : valeur booléenne qui, lorsqu'elle est définie sur true, active l'échantillonnage contraint par la grammaire pour l'outil. Le modèle est garanti d'appeler l'outil avec des arguments correspondant à input_schema.
• tools[].input_schema : schéma JSON qui définit les arguments que le modèle peut transmettre à l'outil. Lorsque strict est défini sur true, le schéma doit être conforme au même sous-ensemble de schéma JSON compatible que le schéma output_config pour les sorties JSON.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON semblable à la suivante. Le bloc de contenu tool_use contient un champ input dont les clés et les types de valeurs correspondent forcément à input_schema de l'outil.

Réponse

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

Champs d'utilisation stricte des outils

Les champs suivants sont spécifiques à l'utilisation stricte des outils. Pour en savoir plus sur les autres champs de définition d'outil, consultez la documentation Définir des outils d'Anthropic.

• tools[].strict : valeur booléenne qui, lorsqu'elle est définie sur true, active l'échantillonnage contraint par la grammaire pour l'outil. Lorsque strict est défini sur true, l'entrée d'outil du modèle est limitée pour correspondre au schéma de input_schema. La valeur par défaut est false.

• tools[].input_schema : schéma JSON qui définit les arguments que le modèle peut transmettre à l'outil. Lorsque strict est défini sur true, le schéma doit être conforme au même sous-ensemble de schéma JSON que celui utilisé par les sorties JSON. En particulier, vous devez :

  • Définissez additionalProperties sur false pour chaque objet du schéma.
  • Listez chaque propriété du tableau required.

  Pour obtenir la liste complète des fonctionnalités compatibles et non compatibles, consultez la documentation d'Anthropic sur les limites du schéma JSON.