Compétences de l’agent¶

Structure de fichiers SKILL.md¶

Chaque compétence est définie par un fichier SKILL.md qui contient les éléments suivants :

• Un nom de compétence

• Une description de la compétence

• Des instructions système pour l’agent

• Des références de script facultatives

Chaque dossier de compétences doit contenir un fichier SKILL.md à sa racine. Le fichier définit l’identité de la compétence, les instructions et les scripts associés. L’exemple suivant montre la structure du dossier des compétences :

skills/
  forecaster/
    SKILL.md
    forecaster.py
  planner/
    SKILL.md
    planner.py

Le fichier SKILL.md comprend les champs suivants :

Découverte des compétences¶

Les Agents Cortex références les fichiers SKILL.md à la racine de chaque dossier de compétences. L’agent analyse le contenu de la zone de préparation pour les fichiers SKILL.md et renvoie le nom, la description et l’emplacement du fichier de la compétence.

Orchestration des compétences¶

Lors de l’appel de l’agent, l’orchestration de l’agent utilise le nom et la description de toutes les compétences référencées dans l’agent pour décider quelles compétences sont pertinentes pour la requête de l’utilisateur. Si une compétence est sélectionnée, l’agent récupère le contenu SKILL.md complet, y compris les instructions détaillées et les chemins de script, à partir de l’emplacement source.

Zones de préparation nommées¶

L’exemple suivant montre comment stocker les dossiers des compétences dans une zone de préparation nommée Snowflake.

Référentiels git¶

L’exemple suivant montre comment référencer les compétences dans un référentiel Git Snowflake. Vous pouvez pointer vers un hachage de validation spécifique pour la stabilité ou une balise pour les mises à jour automatiques :

-- Reference a skill at a specific commit
@my_db.my_schema.skills_repo/commits/abc123def/skills/forecaster

-- Reference a skill at a tag (updates automatically on fetch)
@my_db.my_schema.skills_repo/tags/latest/skills/forecaster

Afficher les capacités disponibles¶

Énumérer toutes les compétences disponibles dans la zone de préparation nommée ou le référentiel git :

LS @db1.schema1.stage1/ PATTERN='.*SKILL\.md';

La sortie indique le nom, la description et l’emplacement du fichier de chaque compétence :

Lister les compétences d’un agent¶

Afficher toutes les compétences configurées sur un agent spécifique :

DESCRIBE AGENT db1.schema1.my_agent;

La sortie renvoie une structure JSON avec le nom et l’URL source de chaque compétence.

Ajouter une compétence à un agent¶

Ajoutez une compétence à un Agent Cortex en mettant à jour la spécification de l’agent. Vous pouvez utiliser l’UI Snowsight, le SQL, ou l’API REST. Le champ de description est facultatif. Si omis, Snowflake lit la description à partir du fichier SKILL.md de la compétence.

ALTER AGENT db1.schema1.my_agent
  MODIFY LIVE VERSION
   SET SPECIFICATION = $$
    {
     //Please include all existing non-changed fields as well
      "skills": [
        {
          "name": "forecaster",
          "source": {
            "type": "STAGE",
            "path": "@db1.schema1.stage1/skills/forecaster"
          }
        }
      ]
    }
  $$;

ALTER AGENT db1.schema1.my_agent
  MODIFY LIVE VERSION
   SET SPECIFICATION = $$
    {
     //Please include all existing non-changed fields as well
      "skills": [
        {
          "name": "forecaster",
          "source": {
            "type": "GIT",
            "path": "@my_db.my_schema.skills_repo/tags/latest/skills/forecaster"
          }
        }
      ]
    }
  $$;

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
            {
                "name": "forecaster",
                "source": {
                    "type": "STAGE",
                    "path": "@db1.schema1.stage1/skills/forecaster"
                }
            }
        ]
    }
}

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
            {
                "name": "forecaster",
                "source": {
                    "type": "GIT_INTEGRATION",
                    "path": "@my_db.my_schema.skills_repo/tags/latest/skills/forecaster"
                }
            }
        ]
    }
}

Mettre à jour une compétence¶

Pour mettre à jour le contenu d’une compétence, modifiez le fichier SKILL.md et tout script associé à l’emplacement source. Tous les agents qui font référence à la compétence utilisent automatiquement la version mise à jour lors de leur prochain appel.

Pour mettre à jour les métadonnées d’une compétence dans la spécification de l’agent (par exemple, la description), utilisez le même point de terminaison PUT avec les valeurs mises à jour.

Supprimer une compétence d’un agent¶

Supprimez une compétence d’un agent à l’aide de l’UI Snowsight, du SQL, ou de l’API REST. Les compétences restantes continuent de fonctionner.

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
        ]
    }
}

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}
{
    "name": "my_agent",
    "comment": "Agent with skill capabilities",
    "spec": {
        "models": {
            "orchestration": "claude-4-sonnet"
        },
        "instructions": {
            "system": "You are an assistant with forecasting and analysis capabilities."
        },
        "skills": [
        ]
    }
}

Ajouter une compétence existante à un autre agent¶

Vous pouvez ajouter la même compétence à plusieurs agents en référençant le même chemin source dans la spécification de chaque agent. Étant donné que les compétences sont référencées et non copiées, les mises à jour des fichiers de compétences s’appliquent à tous les agents qui utilisent la compétence.

Compétences avec code¶

Si vos compétences doivent exécuter du code, vous devez activer l’outil d’exécution de code sur l’agent. Tous les scripts référencés par une compétence doivent se trouver dans le même dossier que le fichier SKILL.md.

Utiliser des compétences dans Snowflake Intelligence¶

Les compétences configurées sur un agent sont automatiquement disponibles dans Snowflake Intelligence. Vous pouvez également sélectionner explicitement une compétence à utiliser en sélectionnant le bouton + puis en choisissant la compétence dans la liste.