Skills API und SDK-Referenz

Important

Dieses Feature befindet sich in der Betaversion. Kontoadministratoren können den Zugriff auf dieses Feature über die Seite " Vorschauen " der Kontokonsole verwalten. Siehe Verwalten von Vorschauen auf Kontoebene.

Nutzen Sie diese Beispiele, um das Fähigkeitsmanagement zu automatisieren. Die API stellt jede Skill als Ressource Skill namens skills/{catalog}.{schema}.{skill}dar. Um eine Fähigkeit mit einem Agenten zu verfassen und zu veröffentlichen, siehe Erstelle und Teilen von Fähigkeiten. Für Privilegien und Verwaltung siehe Regierungsfähigkeiten. Skills haben keine Terraform- oder Declarative Automation Bundles-Ressourcen.

Voraussetzungen

API-Vorgänge

Die Skills REST API stellt diese Operationen bereit. Jede erfordert USE CATALOG auch und USE SCHEMA auf den Eltern. Folgen Sie jedem Link für seine Felder, Berechtigungen und Antworten.

Operation Anwendungsfall Erforderliche Berechtigungen
Erstellen Erstellen Sie eine Fähigkeit und stellen Sie deren Bundle-Speicher bereit. CREATE VOLUME im Schema
Upload Laden Sie alle unterstützenden Dateien über die Datei-API hoch.SKILL.md WRITE VOLUME und READ VOLUME über die Fertigkeit
fertigstellen Lesen und validieren SKILL.md, dann legen Sie den Namen und die Beschreibung des Skils fest. READ VOLUME Über die Fertigkeit
List Finde Fähigkeiten, auf die du in einem Schema Zugriff hast. READ VOLUME, READ METADATA, oder MANAGE auf die Fähigkeit
Get Lies die Metadaten einer Fähigkeit und aktuelle etag. READ VOLUME, READ METADATA, oder MANAGE auf die Fähigkeit
Update Ändere den Kommentar der Fähigkeit. MANAGE Über die Fertigkeit
Delete Entferne eine Fähigkeit und ihr Bündel. MANAGE Über die Fertigkeit

Der Besitzer der Fähigkeit besitzt all diese auf der Fähigkeit. Siehe Zugang zu Fähigkeiten gewähren.

Erstellen einer Fähigkeit

Die Erstellung einer Fähigkeit erfordert drei Schritte: die Fähigkeit erstellen, das Bundle hochladen und dann finalisieren. Bis du eine Fähigkeit finalisiert hast, sind der Name und die Beschreibung des Pakets leer.

Schritt 1: Erstelle die Fähigkeit

Erstelle die Fähigkeit in einem Schema. comment ist das einzige Feld, das du festlegen kannst. Azure Databricks leitet name, bundle_name, und description.

Ersetzen Sie main.default.my_skill und data-team durch Ihre eigenen Werte.

REST API

Senden Sie ein POST an /api/2.1/unity-catalog/skills, indem Sie und skill_id als Abfrageparameter übergebenparent:

databricks api post \
  "/api/2.1/unity-catalog/skills?parent=schemas/main.default&skill_id=my_skill" \
  --json '{"comment": "Team-shared math helper skill"}'

CLI

Übergebe das Elternschema und den Namen der Fähigkeit und gib dem Kommentar folgende Beiträge mit --json:

databricks ai-gateway create-skill schemas/main.default my_skill \
  --json '{"comment": "Team-shared math helper skill"}'

Python SDK

Erstellen und verwalten Sie eine Fähigkeit mit dem Databricks SDK für Python:

from databricks.sdk import WorkspaceClient
from databricks.sdk.service import catalog as c

w = WorkspaceClient()

skill = w.ai_gateway.create_skill(
    parent="schemas/main.default",
    skill_id="my_skill",
    skill=c.Skill(comment="Team-shared math helper skill"),
)

Go Software Development Kit (SDK)

Erstellen und verwalten Sie eine Fähigkeit mit dem Databricks SDK für Go:

skill, err := w.AiGateway.CreateSkill(ctx, catalog.CreateSkillRequest{
	Parent:  "schemas/main.default",
	SkillId: "my_skill",
	Skill:   catalog.Skill{Comment: "Team-shared math helper skill"},
})

Go Modular SDK

Erstellen und verwalten Sie eine Fähigkeit mit dem Go Modular SDK. Optionale Felder sind Zeiger, daher verwendet das Beispiel einen einzeiligen Helfer, func ptr[T any](v T) *T { return &v }.

skill, err := c.CreateSkill(ctx, aigateway.CreateSkillRequest{
	Parent:  ptr("schemas/main.default"),
	SkillId: ptr("my_skill"),
	Skill:   &aigateway.Skill{Comment: ptr("Team-shared math helper skill")},
})

Java SDK

Erstellen und verwalten Sie eine Fähigkeit mit dem Databricks SDK für Java:

Skill skill =
    w.aiGateway()
        .createSkill(
            new CreateSkillRequest()
                .setParent("schemas/main.default")
                .setSkillId("my_skill")
                .setSkill(new Skill().setComment("Team-shared math helper skill")));

JS Modular SDK

Erstellen und verwalten Sie eine Fähigkeit mit dem JavaScript SDK:

const created = await client.createSkill({
  parent: 'schemas/main.default',
  skillId: 'my_skill',
  skill: { comment: 'Team-shared math helper skill' },
});

Schritt 2: Laden Sie das Bundle hoch

Lade SKILL.md, und alle unterstützenden Dateien, über die Datei-API auf den Speicherpfad /Skills/<catalog>/<schema>/<skill>/der Skill hoch. SKILL.mdmuss mit YAML-Frontmaterie beginnen, die und descriptionsetztname. Speichern Sie dieses Beispiel als SKILL.md:

---
name: my-skill
description: A team-shared skill that helps with basic math.
---

# My Skill

Step-by-step guidance the agent follows when this skill is loaded.

REST API

Senden Sie ein A PUT an die Datei-API. Setze DATABRICKS_HOST auf deine Workspace-URL, zum Beispiel https://my-workspace.cloud.databricks.com, und DATABRICKS_TOKEN auf ein Token. Dieses Beispiel übergibt das Token an curl Standardeingabe, sodass es nicht in der Prozessliste erscheint:

curl --request PUT --config - --data-binary @SKILL.md \
  --header "Content-Type: application/octet-stream" \
  "${DATABRICKS_HOST}/api/2.0/fs/files/Skills/main/default/my_skill/SKILL.md?overwrite=true" \
  <<< "header = \"Authorization: Bearer ${DATABRICKS_TOKEN}\""

CLI

Erstelle den Skill-Ordner und kopiere dann die Datei hinein:

databricks fs mkdir dbfs:/Skills/main/default/my_skill
databricks fs cp SKILL.md dbfs:/Skills/main/default/my_skill/SKILL.md --overwrite

Python SDK

with open("SKILL.md", "rb") as f:
    w.files.upload("/Skills/main/default/my_skill/SKILL.md", f, overwrite=True)

Go Software Development Kit (SDK)

f, err := os.Open("SKILL.md")
if err != nil {
	return err
}
defer f.Close()

err = w.Files.Upload(ctx, files.UploadRequest{
	FilePath:  "/Skills/main/default/my_skill/SKILL.md",
	Contents:  f,
	Overwrite: true,
})

Go Modular SDK

Das Go Modular SDK enthält keine Datei-API. Stattdessen mit dem Files SDK für Go hochladen:

fc, err := files.NewClient(ctx)
if err != nil {
	return err
}

f, err := os.Open("SKILL.md")
if err != nil {
	return err
}
defer f.Close()

_, err = fc.Upload(ctx, "/Skills/main/default/my_skill/SKILL.md", f, files.WithOverwrite(true))

Java SDK

try (InputStream contents = Files.newInputStream(Paths.get("SKILL.md"))) {
  w.files()
      .upload(
          new UploadRequest()
              .setFilePath("/Skills/main/default/my_skill/SKILL.md")
              .setOverwrite(true)
              .setContents(contents));
}

JS Modular SDK

Das JavaScript Modular SDK enthält die Dateien-API nicht, daher ruft dieses Beispiel direkt den REST-Endpunkt auf. Es liest die URL des Arbeitsbereichs, wie https://my-workspace.cloud.databricks.com, und ein Token aus den DATABRICKS_HOST und DATABRICKS_TOKEN Umgebungsvariablen:

import { readFile } from 'node:fs/promises';

const response = await fetch(
  `${process.env.DATABRICKS_HOST}/api/2.0/fs/files/Skills/main/default/my_skill/SKILL.md?overwrite=true`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/octet-stream',
      Authorization: `Bearer ${process.env.DATABRICKS_TOKEN}`,
    },
    body: await readFile('SKILL.md'),
  },
);
if (!response.ok) {
  throw new Error(`Upload failed: ${response.status} ${response.statusText}`);
}

Schritt 3: Die Fertigkeit finalisieren

Das Finalisieren liest und validiert SKILL.md, dann legt es die Fähigkeiten bundle_name und description deren Frontmaterial fest. Wenn du das Bundle später änderst, mach es erneut fertig.

REST API

databricks api post "/api/2.1/unity-catalog/skills/main.default.my_skill/finalize" --json '{}'

CLI

databricks ai-gateway finalize-skill skills/main.default.my_skill

Python SDK

finalized = w.ai_gateway.finalize_skill(name="skills/main.default.my_skill")
print(finalized.bundle_name, finalized.description)

Go Software Development Kit (SDK)

finalized, err := w.AiGateway.FinalizeSkill(ctx, catalog.FinalizeSkillRequest{
	Name: "skills/main.default.my_skill",
})

Go Modular SDK

finalized, err := c.FinalizeSkill(ctx, aigateway.FinalizeSkillRequest{
	Name: ptr("skills/main.default.my_skill"),
})

Java SDK

Skill finalized =
    w.aiGateway().finalizeSkill(new FinalizeSkillRequest().setName("skills/main.default.my_skill"));

JS Modular SDK

const finalized = await client.finalizeSkill({ name: 'skills/main.default.my_skill' });

Finde eine Fähigkeit

Listen Sie die Fähigkeiten auf, auf die Sie in einem Schema zugreifen können, und erhalten Sie dann die Metadaten einer Fähigkeit anhand ihres Ressourcennamens.

REST API

databricks api get "/api/2.1/unity-catalog/skills?parent=schemas/main.default"

databricks api get "/api/2.1/unity-catalog/skills/main.default.my_skill"

Wenn die Listenantwort enthält next_page_token, übergeben Sie sie wie page_token in der nächsten Anfrage. Mach weiter, bis next_page_token es fehlt oder leer ist.

CLI

databricks ai-gateway list-skills schemas/main.default

databricks ai-gateway get-skill skills/main.default.my_skill

Python SDK

for skill in w.ai_gateway.list_skills(parent="schemas/main.default"):
    print(skill.name)

skill = w.ai_gateway.get_skill(name="skills/main.default.my_skill")

Der CLI- und Python-Iterator übernehmen die Paginierung für dich.

Zugriff gewähren

Diese Beispiele gewähren READ VOLUME die Fertigkeit, die es dem Schulleiter ermöglicht, die Fertigkeit zu lesen und das Bundle herunterzuladen. Für die anderen Fertigkeitsprivilegien siehe Zugang zu Fähigkeiten gewähren.

REST API

databricks api patch \
  "/api/2.1/unity-catalog/permissions/skill/main.default.my_skill" \
  --json '{
    "changes": [
      { "principal": "data-team", "add": ["READ_VOLUME"] }
    ]
  }'

CLI

Grant READ VOLUME mit der Databricks-CLI:

databricks grants update skill main.default.my_skill \
  --json '{"changes": [{"principal": "data-team", "add": ["READ_VOLUME"]}]}'

Python SDK

Grant READ VOLUME mit dem Databricks SDK für Python:

from databricks.sdk.service import catalog as c

w.grants.update(
    securable_type="skill",
    full_name="main.default.my_skill",
    changes=[c.PermissionsChange(principal="data-team", add=[c.Privilege.READ_VOLUME])],
)

Go Software Development Kit (SDK)

Grant READ VOLUME mit dem Databricks SDK für Go:

_, err := w.Grants.Update(ctx, catalog.UpdatePermissions{
	SecurableType: "skill",
	FullName:      "main.default.my_skill",
	Changes: []catalog.PermissionsChange{{
		Principal: "data-team",
		Add:       []catalog.Privilege{catalog.PrivilegeReadVolume},
	}},
})

Java SDK

Grant READ VOLUME mit dem Databricks SDK für Java:

w.grants()
    .update(
        new UpdatePermissions()
            .setSecurableType("skill")
            .setFullName("main.default.my_skill")
            .setChanges(
                Arrays.asList(
                    new PermissionsChange()
                        .setPrincipal("data-team")
                        .setAdd(Arrays.asList(Privilege.READ_VOLUME)))));

Aktualisieren einer Fähigkeit

Diese Beispiele aktualisieren den Kommentar der Fähigkeit, das einzige Feld, das du ändern kannst. Der Name der Fähigkeit kann nicht geändert werden. Um den Inhalt einer Fähigkeit zu ändern, lade das neue Bundle hoch und finaliere die Fähigkeit erneut.

Für ein bedingtes Update erhalte zuerst die Fähigkeit und gib sie etag mit dem Update durch. Das Update funktioniert nur, wenn sich die Fähigkeit seit diesem Lesen nicht verändert hat. URL-encodieren, etag wenn man es zu einer REST-Abfrage-Zeichenkette hinzugefügt hat.

REST API

databricks api patch \
  "/api/2.1/unity-catalog/skills/main.default.my_skill?update_mask=comment" \
  --json '{"comment": "Updated: team-shared math helper"}'

CLI

databricks ai-gateway update-skill skills/main.default.my_skill comment \
  --json '{"comment": "Updated: team-shared math helper"}'

Python SDK

from databricks.sdk.service import catalog as c
from databricks.sdk.common.types.fieldmask import FieldMask

updated = w.ai_gateway.update_skill(
    name="skills/main.default.my_skill",
    update_mask=FieldMask(["comment"]),
    skill=c.Skill(comment="Updated: team-shared math helper"),
)

Go Software Development Kit (SDK)

updated, err := w.AiGateway.UpdateSkill(ctx, catalog.UpdateSkillRequest{
	Name:       "skills/main.default.my_skill",
	UpdateMask: *fieldmask.New([]string{"comment"}),
	Skill:      catalog.Skill{Comment: "Updated: team-shared math helper"},
})

Go Modular SDK

mask, err := types.NewFieldMask[aigateway.Skill]("comment")
updated, err := c.UpdateSkill(ctx, aigateway.UpdateSkillRequest{
	Skill: &aigateway.Skill{
		Name:    ptr("skills/main.default.my_skill"),
		Comment: ptr("Updated: team-shared math helper"),
	},
	UpdateMask: mask,
})

Java SDK

Skill updated =
    w.aiGateway()
        .updateSkill(
            new UpdateSkillRequest()
                .setName("skills/main.default.my_skill")
                .setUpdateMask(FieldMask.newBuilder().addPaths("comment").build())
                .setSkill(new Skill().setComment("Updated: team-shared math helper")));

JS Modular SDK

import { skillFieldMask } from '@databricks/sdk-aigateway/v1';

const updated = await client.updateSkill({
  skill: {
    name: 'skills/main.default.my_skill',
    comment: 'Updated: team-shared math helper',
  },
  updateMask: skillFieldMask('comment'),
});

Löschen einer Fähigkeit

Das Löschen einer Fähigkeit entfernt sie und ihr Bündel. Die Agenten können es nicht mehr laden.

Du kannst auch den aktuellen etag Bestand der Fähigkeit übergeben, um das Löschen an die Bedingung zu knüpfen, dass sich seit dem letzten Lesen nichts geändert hat. URL-kodieren Sie die etag in REST-Abfragestrings ein.

REST API

databricks api delete "/api/2.1/unity-catalog/skills/main.default.my_skill"

CLI

databricks ai-gateway delete-skill skills/main.default.my_skill

Python SDK

w.ai_gateway.delete_skill(name="skills/main.default.my_skill")

Go Software Development Kit (SDK)

err := w.AiGateway.DeleteSkill(ctx, catalog.DeleteSkillRequest{
	Name: "skills/main.default.my_skill",
})

Go Modular SDK

err := c.DeleteSkill(ctx, aigateway.DeleteSkillRequest{
	Name: ptr("skills/main.default.my_skill"),
})

Java SDK

w.aiGateway().deleteSkill(new DeleteSkillRequest().setName("skills/main.default.my_skill"));

JS Modular SDK

await client.deleteSkill({ name: 'skills/main.default.my_skill' });

Weitere Ressourcen

  • Zuletzt aktualisiert um