Skills registrieren

In der Agent Registry stellt ein Skill eine eigenständige, ausführbare Funktion dar, die ein Agent haben kann. Sie enthält Anweisungen in einer SKILL.md-Datei, Codeskripts und Assets, die die Argumentation eines Agents erweitern. Durch die Registrierung von eigenständigen Skills in der Agent Registry können Sie Funktionen zentral verwalten, versionieren und für die KI‑Agenten Ihrer Organisation freigeben.

Von Google erstellte Skills sind sofort sichtbar, wenn Sie die Agent Registry einrichten. In diesem Dokument wird beschrieben, wie Sie Ihre eigenen eigenständigen Skills manuell in der Agent Registry registrieren.

Hinweis

Richten Sie zuerst die Agent Registry ein. Sie benötigen die Projekt-ID, um diese Aufgaben auszuführen.

Wenn Sie die Google Cloud CLI-Befehle in diesem Dokument verwenden möchten, müssen Sie Ihre gcloud CLI-Umgebung einrichten.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für das Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Registrieren von Skills in der Agent Registry benötigen:

  • Eigenständige Skills registrieren und verwalten: Agent Registry User (roles/agentregistry.user)
  • Eigenständige Skills und andere Agent Registry-Ressourcen registrieren und verwalten: Agent Registry API Editor (roles/agentregistry.editor)

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Andere Agent Registry-Rollen können auch die Berechtigungen enthalten, die zum Registrieren und Verwalten von Skills und Skill-Revisionen erforderlich sind. Weitere Informationen finden Sie unter Rollen und Berechtigungen für die Agent Registry.

Einschränkungen für die Aufnahme-Payload

Um einen Skill zu registrieren, müssen Sie die Quelldateien der Funktion in einem ZIP-Archiv verpacken. Das Archiv muss im Stammverzeichnis eine SKILL.md-Anweisungsdatei enthalten. Während der Erfassungsphase des Skill-Registrierungsprozesses prüft die Agent Registry, ob die Nutzlast den folgenden Einschränkungen entspricht:

  • Größe des ZIP-Archivs:Die maximale Größe des komprimierten Archivs beträgt 500 KB.
  • Gesamtgröße der unkomprimierten Nutzlast:maximal 10 MB.
  • Größe der einzelnen Dateien:Die maximale unkomprimierte Größe beträgt 1 MB pro Datei.
  • Tiefe Verschachtelung:Die maximale Verschachtelungstiefe von Verzeichnissen beträgt 8 Ebenen.
  • Einhaltung der Spezifikation:Die Datei SKILL.md muss einen gültigen YAML-Frontmatter-Abschnitt enthalten, in dem Name, Beschreibung und Metadaten gemäß der Spezifikation für Agent-Skills definiert sind.

Skill registrieren

Von Google erstellte Skills sind sofort sichtbar, wenn Sie die Agent Registry einrichten. Sie können Ihre eigenen Skills aber auch manuell registrieren. Jeder Skill hat eine Standardversion und kann mehrere versionierte Skill-Versionen enthalten.

Um eigene Skills zu registrieren, erstellen Sie einen logischen Skill-Container und laden die Nutzlast der ersten Revision in einem einzigen Vorgang hoch. Später können Sie Ihre registrierten Skills verwalten und die nachfolgenden Skill-Überarbeitungen.

Informationen zu Preisen und Funktionskosten für Skills finden Sie unter Preise für die Agent Registry.

Die Skills, die Sie oder andere Nutzer erstellen, werden automatisch dem Standardverlag private zugewiesen, um Namenskonflikte mit von Google erstellten Skills zu vermeiden. Aus diesem Grund wird die veröffentlichte ID eines bestimmten Skills zu private-SKILL_ID. Sie können beim Erstellen eines Skills keinen benutzerdefinierten Publisher angeben.

Wenn Sie beispielsweise einen Skill mit der ID workspace-tools erstellen, wird der Ressourcenname als projects/PROJECT_ID/locations/LOCATION/skills/private-workspace-tools erstellt. Der logische Uniform Resource Name (URN) wird als urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-workspace-tools zugewiesen. Sie müssen diese veröffentlichte ID (private-workspace-tools) für alle nachfolgenden Skill-Vorgänge verwenden.

So registrieren Sie einen Skill:

Console

  1. Rufen Sie in der Google Cloud Console die Seite Agent Registry auf:

    Zur Agent Registry

  2. Wählen Sie in der Projektauswahl Ihr Google Cloud Projekt aus.

  3. Wählen Sie den Tab Skills aus.

  4. Auf dem Tab Skills werden für die Schaltfläche Skill hinzufügen zwei Optionen angezeigt. Sie haben folgende Möglichkeiten:

    • Skill hinzufügen: Erstellen Sie einen neuen Skill-Container in der Registry. Sie können optional ein Skill-Paket hochladen, um die erste Version zu erstellen.
    • Skill importieren: Nehmen Sie ein neues benutzerdefiniertes Skill-Paket in Betrieb, indem Sie ein ZIP-Bundle mit Ihrem Code oder einer Datei mit Prompt-Anweisungen (SKILL.md) hochladen.

  5. Geben Sie im Bereich Skill erstellen oder Skill importieren die folgenden Details an:

    • Anzeigename:Geben Sie einen nutzerfreundlichen Namen für den Skill ein.
    • Beschreibung:Gib eine kurze Zusammenfassung der Skill-Funktionen ein.
    • Standort:Wählen Sie die geografische Region aus, z. B. global, us oder eu.

  6. Wählen Sie im Bereich Payload-Quelle eine der folgenden Optionen aus:

    • Datei:Ziehen Sie die ZIP-Datei Ihres Skills per Drag-and-drop hierher oder suchen Sie in Ihrem lokalen Verzeichnis danach.

    • Bucket:Geben Sie den Pfad zu Ihrem ZIP-Archiv ein, das in einem Cloud Storage-Bucket gespeichert ist, im Format gs://BUCKET_NAME/SKILL_PACKAGE.zip.

  7. Klicken Sie auf Erstellen.

Ihr Skill wurde erstellt. Bei allen nachfolgenden Skill-Vorgängen verweisen Sie auf Ihren Skill als private-SKILL_ID, wie in derGoogle Cloud -Konsole angezeigt.

gcloud

Um einen Skill zu registrieren und die erste Nutzlast hochzuladen, können Sie entweder eine lokale ZIP-Datei hochladen oder ein in Cloud Storage gespeichertes Paket importieren.

Ersetzen Sie Folgendes:

  • SKILL_ID: Die Ressourcen-ID des Skills, z. B. workspace-docs-skill. Nach der Erstellung wird dem Registrierungseintrag automatisch das Präfix private- vorangestellt. Sie müssen die ID mit dem Präfix in allen nachfolgenden Skill-Befehlen verwenden, z. B. private-workspace-docs-skill.
  • PROJECT_ID: die Projekt-ID
  • LOCATION: Die geografische Region, z. B. global, us oder eu.
  • DISPLAY_NAME: Ein nutzerfreundlicher Name für den Skill.

  • DESCRIPTION: Eine kurze Zusammenfassung der Skill-Funktionen.

  • Lokale ZIP-Datei hochladen: So registrieren Sie einen Skill mit einer lokalen ZIP-Nutzlast:

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --payload="LOCAL_ZIP_PATH"

    Ersetzen Sie LOCAL_ZIP_PATH durch den Pfad zu Ihrem verpackten Skill-Archiv auf Ihrem lokalen Computer, z. B. ./workspace-docs-skill.zip.

  • Aus einem Cloud Storage-Bucket importieren: So registrieren Sie einen Skill mit einem ZIP-Archiv, das in einem Cloud Storage-Bucket gehostet wird:

    gcloud alpha agent-registry skills create SKILL_ID \
  --project=PROJECT_ID \
  --location=LOCATION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --gcs-source-uri="gs://BUCKET_NAME/SKILL_PACKAGE.zip"

    Ersetzen Sie Folgendes:

    • BUCKET_NAME: Der Name des Cloud Storage-Bucket, der das ZIP-Bundle enthält.
    • SKILL_PACKAGE: Der Name des Skill-Pakets, das die Skill-Nutzlast enthält.

REST

So erstellen Sie einen Skill mit einer ersten Inline-Version:

HTTP-Methode und URL

POST https://agentregistry.googleapis.com/v1alpha/projects/{project}/locations/{location}/skills?skillId={skillId}

JSON-Text der Anfrage (lokaler Dateiupload)

Wenn Sie einen Skill erstellen möchten, indem Sie lokale ZIP-Archivbytes direkt hochladen, verwenden Sie die archiveUploadSource-Nutzlast:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "archiveUploadSource": {
      "archiveContent": "BASE64_ZIP_BYTES"
    }
  }
}

Ersetzen Sie BASE64_ZIP_BYTES durch die base64-codierte Stringdarstellung Ihres lokalen ZIP-Archivs.

JSON-Text der Anfrage (Import aus Cloud Storage)

Alternativ können Sie einen Skill auch mit einem Archiv erstellen, das in einem Cloud Storage-Bucket gespeichert ist. Verwenden Sie dazu gcsSource:

{
  "displayName": "DISPLAY_NAME",
  "description": "DESCRIPTION",
  "type": "SIMPLE",
  "targetState": "TARGET_STATE_ACTIVE",
  "initialRevision": {
    "gcsSource": {
      "uri": "gs://BUCKET_NAME/SKILL_PACKAGE.zip"
    }
  }
}

Ersetzen Sie Folgendes:

  • BUCKET_NAME: Der Name des Cloud Storage-Bucket, der das ZIP-Bundle enthält.
  • SKILL_PACKAGE: Der Name des Skill-Pakets, das die Skill-Nutzlast enthält.

curl-Befehl (lokaler Dateiupload)

curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -d '{
        "displayName": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        "type": "SIMPLE",
        "targetState": "TARGET_STATE_ACTIVE",
        "initialRevision": {
          "archiveUploadSource": {
            "archiveContent": "$(base64 -w0 local_skill.zip)"
          }
        }
      }' \
      "https://agentregistry.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

Ersetzen Sie für einen Dateiupload in einen Cloud Storage-Bucket den JSON-Text der Anfrage durch die entsprechenden Felder und Werte.

Nächste Schritte