ALTER AGENT¶

Modifie les propriétés ou la spécification d’un Cortex Agent existant.

Voir aussi :: CREATE AGENT, DESCRIBE AGENT, DROP AGENT, SHOW AGENTS

Syntaxe¶

ALTER AGENT <name> SET
  [ COMMENT = '<string>' ]
  [ PROFILE = '<string>' ]

ALTER AGENT <name> MODIFY LIVE VERSION SET SPECIFICATION = <specification>

Copy

Paramètres requis¶

name

Chaîne spécifiant l’identificateur (c’est-à-dire le nom) de l’agent à modifier.

Si l’identificateur contient des espaces ou des caractères spéciaux, toute la chaîne doit être délimitée par des guillemets doubles. Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus d’informations, voir Exigences relatives à l’identificateur.

Paramètres facultatifs¶

SET ...

Définit une ou plusieurs propriétés ou paramètres spécifiés pour l’agent :

COMMENT = comment

Spécifie la description de l’agent.

PROFILE = string

Spécifie les informations de profil de l’agent, telles que le nom d’affichage, l’avatar et la couleur. Formatez la chaîne comme suit :

'{"display_name": "<display_name>", "avatar": "<avatar>", "color": "<color>"}'

Copy

Le tableau suivant décrit les paires clé-valeur de cette chaîne :

Clé	Type	Description
`display_name`	Chaîne	Nom d’affichage de l’agent.
`avatar`	Chaîne	Nom ou identificateur du fichier image avatar.
`color`	Chaîne	Thème de couleur de l’agent (comme « bleu », « vert », « rouge »).

MODIFY LIVE VERSION SET SPECIFICATION specification

Spécifie la valeur VARCHAR contenant les paramètres de remplacement d’un agent en tant qu’objet YAML ou JSON :

Littéral entouré de signes dollar : $$ … $$
Chaîne entre guillemets simples : “…”

La longueur maximale de l’objet de spécification est de 100 000 octets.

Important

La nouvelle spécification remplace entièrement la spécification existante. Les champs qui ne sont pas inclus dans la nouvelle spécification sont supprimés.

L’objet YAML doit avoir la structure suivante :

models:
  orchestration: <model_name>

orchestration:
  budget:
      seconds: <number_of_seconds>
      tokens: <number_of_tokens>

instructions:
  response: '<response_instructions>'
  orchestration: '<orchestration_instructions>'
  system: '<system_instructions>'
  sample_questions:
      - question: '<sample_question>'
        answer: '<sample_answer>'
      ...

tools:
  - tool_spec:
      type: '<tool_type>'
      name: '<tool_name>'
      description: '<tool_description>'
      input_schema:
          type: 'object'
          properties:
            <property_name>:
              type: '<property_type>'
              description: '<property_description>'
          required: <required_property_names>
  ...

tool_resources:
  <tool_name>:
    <resource_key>: '<resource_value>'
    ...
  ...

Copy

L’objet JSON doit avoir la structure suivante :

{
  "models": {
    "orchestration": "<model_name>"
  },
  "orchestration": {
    "budget": {
      "seconds": <number_of_seconds>,
      "tokens": <number_of_tokens>
    }
  },
  "instructions": {
    "response": "<response_instructions>",
    "orchestration": "<orchestration_instructions>",
    "system": "<system_instructions>",
    "sample_questions": [
      {
        "question": "<sample_question>",
        "answer": "<sample_answer>"
      }
    ]
  },
  "tools": [
    {
      "tool_spec": {
        "type": "<tool_type>",
        "name": "<tool_name>",
        "description": "<tool_description>",
        "input_schema": {
          "type": "object",
          "properties": {
            "<property_name>": {
              "type": "<property_type>",
              "description": "<property_description>"
            }
          },
          "required": ["<required_property_names>"]
        }
      }
    }
  ],
  "tool_resources": {
    "<tool_name>": {
      "<resource_key>": "<resource_value>"
    }
  }
}

Copy

Le tableau suivant décrit les paires clé-valeur de cet objet :

Clé	Type	Description
`models`	ModelConfig	Configuration facultative du modèle pour l’agent. Inclut le modèle d’orchestration (par exemple, claude-4-sonnet). S’il n’est pas fourni, un modèle est automatiquement sélectionné. Actuellement disponible uniquement pour l’étape d’`orchestration`.
`orchestration`	OrchestrationConfig	Configuration facultative de l’orchestration, y compris les contraintes budgétaires (par exemple, secondes, jetons).
`instructions`	AgentInstructions	Instructions facultatives relatives au comportement de l’agent, y compris la réponse, l’orchestration, le système et les exemples de questions.
`tools`	tableau d”Tool	Liste facultative des outils disponibles pour l’agent à utiliser. Chaque outil inclut une `tool_spec` avec un type, un nom, une description et un schéma d’entrée. Les outils peuvent avoir une configuration correspondante dans `tool_resources`.
`tool_resources`	carte de ToolResource	Configuration facultative pour chaque outil référencé dans le tableau des outils. Les clés doivent correspondre au nom de l’outil correspondant.

Exigences en matière de contrôle d’accès¶

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

Privilège	Objet	Remarques
OWNERSHIP ou MODIFY	Agent	Nécessaire pour modifier les propriétés ou la spécification de l’agent. OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

Privilège

Objet

Remarques

OWNERSHIP ou MODIFY

Agent

Nécessaire pour modifier les propriétés ou la spécification de l’agent.

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

Pour effectuer une opération sur un objet dans un schéma, il est nécessaire de disposer d’au moins un privilège sur la base de données parente et d’au moins un privilège sur le schéma parent.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

Lors de la modification de la spécification d’une version en ligne, la nouvelle spécification remplace entièrement la spécification existante. Les champs qui ne sont pas inclus dans la nouvelle spécification sont supprimés.
Les formats YAML et JSON sont pris en charge pour les spécifications.
Les champs de spécification non valides entraînent une erreur.
Concernant les métadonnées :

Attention

Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

Exemples¶

Mise à jour du commentaire d’un agent :

ALTER AGENT my_support_agent SET COMMENT = 'Customer support agent for product inquiries';

Copy

Mise à jour du profil d’un agent :

ALTER AGENT my_support_agent SET PROFILE = '{"display_name": "Support Bot", "avatar": "bot-icon.png"}';

Copy

Mise à jour du commentaire et du profil ensemble :

ALTER AGENT my_support_agent
  SET COMMENT = 'Production support agent',
      PROFILE = '{"display_name": "Customer Assistant", "avatar": "assistant.png"}';

Copy

Mise à jour de la spécification de la version en ligne à l’aide du format YAML :

ALTER AGENT my_support_agent
  MODIFY LIVE VERSION SET SPECIFICATION =
  $$
  models:
    orchestration: claude-4-sonnet

  orchestration:
    budget:
      seconds: 30
      tokens: 50000

  instructions:
    system: "You are a helpful customer support assistant."
    response: "Always be concise and accurate."
    sample_questions:
      - question: "What is the status of my order?"
        answer: "I can help you check your order status. Please provide your order number."
  $$;

Copy

Mise à jour de la spécification de la version en ligne à l’aide du format JSON :

ALTER AGENT my_support_agent
  MODIFY LIVE VERSION SET SPECIFICATION = '{"models":{"orchestration":"claude-4-sonnet"},"orchestration":{"budget":{"seconds":45,"tokens":80000}}}';

Copy