Fähigkeiten der Agenten¶

Dateistruktur: SKILL.md¶

Jede Fähigkeit wird durch eine SKILL.md-Datei definiert, die Folgendes enthält:

• Ein Fähigkeitsname

• Eine Beschreibung des Problems

• Anweisungen für den Agenten

• Optionale Skriptreferenzen

Jeder Ordner mit Fähigkeiten muss eine SKILL.md-Datei in ihrem Stammverzeichnis enthalten. Die Datei definiert die Identität der Fähigkeiten, die Anweisungen und alle zugehörigen Skripte. Das folgende Beispiel zeigt die Struktur des Fähigkeiten-Ordners:

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

Die SKILL.md-Datei enthält die folgenden Felder:

Erkennen von Fähigkeiten¶

Cortex Agents verweisen auf:code:SKILL.md-Dateien im Stammverzeichnis jedes Fähigkeiten-Ordners. Der Agent scannt den Inhalt des Stagingbereichs nach:code:SKILL.md-Dateien und gibt den Namen der Fähigkeit, die Beschreibung und den Speicherort der Datei zurück.

Orchestrierung von Fähigkeiten¶

Während des Aufrufs des Agenten verwendet der Orchestrator des Agenten den Namen und die Beschreibung jeder im Agenten referenzierten Fähigkeit, um zu entscheiden, welche Fähigkeiten für die Abfrage des Benutzers relevant sind. Wenn eine Fähigkeit ausgewählt ist, ruft der Agent den vollständigen SKILL.md-Inhalt ab, einschließlich detaillierter Anweisungen und Skriptpfade, vom Quellspeicherort.

Benannte Stagingbereiche¶

Das folgende Beispiel zeigt, wie Sie Ordner in einem benannten Snowflake-Stagingbereich speichern.

Git-Repositorys¶

Das folgende Beispiel zeigt, wie Sie auf Fähigkeiten verweisen, die sich in einem Snowflake-Git-Repository befinden. Sie können auf einen bestimmten Commit-Hash für Stabilität oder auf ein Tag für automatische Aktualisierungen verweisen:

-- 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

Verfügbare Fähigkeiten auflisten¶

Listet alle in einem benannten Stagingbereich oder Git-Repository verfügbaren Fähigkeiten auf:

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

Die Ausgabe zeigt den Namen, die Beschreibung und den Speicherort jeder Fähigkeit:

Liste der Fähigkeiten eines Agenten¶

Zeigen Sie alle Fähigkeiten an, die für einen bestimmten Agenten konfiguriert sind:

DESCRIBE AGENT db1.schema1.my_agent;

Die Ausgabe gibt eine JSON-Struktur zurück, die den Namen und die Quell-URL jeder Fähigkeit enthält.

Hinzufügen einer Fähigkeit zu einem Agenten¶

Fügen Sie eine Fähigkeit zu einem Cortex Agent hinzu, indem Sie die Agentenspezifikation aktualisieren. Sie können die Snowsight-UI, SQL oder die REST API verwenden. Das Beschreibungsfeld ist optional. Wenn weggelassen, liest Snowflake die Beschreibung aus der:code:SKILL.md-Datei der Fähigkeit aus.

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

Aktualisieren einer Fähigkeit¶

Um den Inhalt einer Fähigkeit zu aktualisieren, ändern Sie die:code:SKILL.md-Datei und alle verknüpften Skripte am Quellspeicherort. Alle Agenten, die auf die Fähigkeit verweisen, verwenden bei ihrem nächsten Aufruf automatisch die aktualisierte Version.

Um die Metadaten einer Fähigkeit in der Spezifikation des Agenten zu aktualisieren (z. B. die Beschreibung), verwenden Sie denselben PUT-Endpunkt mit den aktualisierten Werten.

Entfernen einer Fähigkeit von einem Agenten¶

Entfernen einer Fähigkeit von einem Agenten mit der |sf-web-interface|UI, SQL oder der RESTAPI. Die verbleibenden Fähigkeiten funktionieren weiterhin.

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": [
        ]
    }
}

Hinzufügen einer vorhandenen Fähigkeit zu einem anderen Agenten¶

Sie können die gleiche Fähigkeit zu mehreren Agenten hinzufügen, indem Sie in der Spezifikation jedes Agenten auf den gleichen Quellpfad verweisen. Da Fähigkeiten referenziert und nicht kopiert werden, gelten Aktualisierungen der Fähigkeitsdateien für alle Agenten, die die Fähigkeit verwenden.

Fähigkeiten mit Code¶

Wenn Ihre Fähigkeiten Code ausführen müssen, müssen Sie das Code-Ausführungstool auf dem Agenten aktivieren. Alle Skripte, die von einer Fähigkeit referenziert werden, müssen sich im gleichen Ordner wie die SKILL.md-Datei befinden.

Verwenden Sie Fähigkeiten in Snowflake Intelligence¶

Die auf einem Agenten konfigurierten Fähigkeiten sind automatisch auch in Snowflake Intelligence verfügbar. Sie können eine Fähigkeit auch explizit zur Verwendung auswählen, indem Sie die +-Schaltfläche und dann die Fähigkeit aus der Liste auswählen.