Sorties structurées avec les modèles Anthropic Claude

Les sorties structurées vous permettent de limiter la sortie générée d'un modèle Claude afin qu'elle soit exactement conforme à un schéma JSON spécifique. Cela est utile pour vous assurer que les réponses de vos modèles Claude sont toujours dans le format précis requis pour les applications, les bases de données et les 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) : limitent la réponse textuelle du modèle à un objet JSON correspondant à un schéma que vous fournissez. Utilisez cette option 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 à l'input_schema de l'outil. Utilisez cette option lorsque vous avez besoin d'appels de fonction de type sécurisé dans des workflows agentifs.

Pour en savoir plus, consultez la documentation d'Anthropic sur la création avec Claude : sorties structurées et 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ègle 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 de l'é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 être conforme.

REST

L'exemple suivant montre comment envoyer une requête à l'API Agent Platform qui extrait 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 ci-dessous, effectuez les remplacements suivants :

  • LOCATION : région compatible avec les modèles Anthropic Claude. Pour utiliser le point de terminaison global, consultez Spécifier le point de terminaison global.
  • 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 (john@example.com) 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 simultanément. 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 des requêtes.

  • 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éfini 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 compatible.

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

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

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.

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

  • 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 la sortie. Seul le type json_schema est compatible.
  • output_config.format.type : type de format de sortie à appliquer. Définissez cette option 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, avec quelques limites, par exemple, la nécessité de définir additionalProperties sur false pour les objets et l'impossibilité de prendre en charge les contraintes numériques ou de longueur de chaîne. Pour obtenir la liste complète des fonctionnalités compatibles et non compatibles, consultez la documentation d'Anthropic sur les limitesdu 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: mappage des noms de champs à 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 l'utilisation stricte des outils

L'utilisation stricte des outils garantit que les arguments que le modèle transmet à un outil correspondent à l'input_schema de l'outil. Sans le mode strict, le modèle peut appeler un outil avec des arguments de type incorrect (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 nouvelle tentative. Lorsque le mode strict est activé, l'API utilise un échantillonnage contraint par la grammaire pour s'assurer que :

  • Le name de l'outil est toujours l'un des outils que vous avez fournis.
  • L'outil input est toujours conforme à l'input_schema de l'outil.

Utilisez l'utilisation stricte des outils lorsque vous devez valider les paramètres des outils, créer des workflows agentifs, garantir 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 la définition de votre 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 une unit facultative qui est celsius ou fahrenheit.

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

  • LOCATION : région compatible avec les modèles Anthropic Claude. Pour utiliser le point de terminaison global, consultez Spécifier le point de terminaison global.
  • 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 simultanément.

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 à l' input_schema.
  • tools[].input_schema : schéma JSON qui définit les arguments que le modèle peut transmettre à l'outil. Lorsque strict est true, le schéma doit être conforme au même sous-ensemble de schéma JSON 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

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

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 tool_use bloc de contenu contient un champ input dont les clés et les types de valeurs sont garantis de correspondre à l' input_schema.

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'Anthropic sur la définition 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. Lorsque strict est true, l'entrée de l'outil du modèle est limitée pour correspondre au schéma dans 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 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éfinir additionalProperties sur false pour chaque objet du schéma.
    • Lister chaque propriété dans le 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.