Skills API and SDK reference

備考

ベータ版

This feature is in Beta. Account admins can manage access to this feature from the account console Previews page. See Manage account-level previews.

これらの例を使用して、スキル管理を自動化してください。APIは各スキルを、skills/{catalog}.{schema}.{skill}という名前のSkillリソースとして表します。エージェントを使用したスキルの作成と公開については、スキルの作成と共有を参照してください。権限とガバナンスについては、スキルのガバナンスを参照してください。スキルには、Terraformリソースも宣言型オートメーションバンドルのリソースもありません。

前提条件

• Set up a governed schema for skills.

• 操作に必要な権限を持っていることを確認してください。

• 使用するクライアントをインストールして認証します。REST APIにバージョン要件はありません。各ツールとSDKには最小バージョンがあります：

  • Databricks CLI：バージョン1.20.0以降
  • Python SDK：databricks-sdk 0.142.0以降
  • Go SDK：databricks-sdk-go v0.184.0以降
  • Go Modular SDK：github.com/databricks/sdk-go/aigateway v0.1.0以上
  • Java SDK：databricks-sdk-java 0.157.0以降
  • JavaScript SDK：@databricks/sdk-aigateway 0.23.0以降

  SDK snippets assume an authenticated workspace client, w; Modular SDK snippets assume an authenticated Unity Gateway client, c in Go and client in JavaScript.

API operations

「Skills REST API」は、次の操作を提供します。それぞれについて、親に対してUSE CATALOGおよびUSE SCHEMAも必要です。各Linkで、そのフィールド、権限、および応答を確認してください。

オペレーション	ユースケース	必要な権限
作成	スキルを作成し、そのバンドルストレージをプロビジョニングします。	CREATE VOLUME スキーマで
アップロード	Upload SKILL.md and any supporting files through the Files API.	WRITE VOLUME およびスキルのREAD VOLUME
完了する	SKILL.mdを読み込んで検証し、スキルのバンドル名と説明を設定します。	READ VOLUME スキルについて
リスト	スキーマ内でアクセスできるスキルを検索します。	READ VOLUME, READ METADATA, or MANAGE on the skill
取得	スキルのメタデータと現在のetagを読み取ります。	READ VOLUME, READ METADATA, or MANAGE on the skill
更新	Change the skill's comment.	MANAGE スキルについて
削除	Remove a skill and its bundle.	MANAGE スキルについて

オペレーション	ユースケース	必要な権限
作成	スキルを作成し、そのバンドルストレージをプロビジョニングします。	CREATE VOLUME スキーマで
アップロード	Upload SKILL.md and any supporting files through the Files API.	WRITE VOLUME およびスキルのREAD VOLUME
完了する	SKILL.mdを読み込んで検証し、スキルのバンドル名と説明を設定します。	READ VOLUME スキルについて
リスト	スキーマ内でアクセスできるスキルを検索します。	READ VOLUME, READ METADATA, or MANAGE on the skill
取得	スキルのメタデータと現在のetagを読み取ります。	READ VOLUME, READ METADATA, or MANAGE on the skill
更新	Change the skill's comment.	MANAGE スキルについて
削除	Remove a skill and its bundle.	MANAGE スキルについて

スキルの所有者は、そのスキルに対するこれらすべての権限を持ちます。「スキルへのアクセス権の付与」を参照してください。

スキルを作成

スキルの作成には3つのステップがあります。スキルを作成し、そのバンドルをuploadしてから、スキルを完了します。スキルを完了するまでは、バンドル名と説明は空です。

ステップ 1：スキルを作成する

スキーマ内にスキルを作成します。設定できるフィールドはcommentのみです。Databricksはname、bundle_name、descriptionを導出します。

main.default.my_skillとdata-teamを独自の値に置き換えます。

REST API

/api/2.1/unity-catalog/skillsにPOSTを送信し、parentとskill_idをクエリーパラメーターとして渡す場合：

Bash

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

親スキーマとスキル名を渡し、--jsonを使用してコメントを指定します：

Bash

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

Python SDK

Databricks SDK for Pythonを使用して、スキルを作成・管理します：

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 SDK

次のDatabricks SDK for Goを使用してスキルを作成および管理します：

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

Go Modular SDKを使用して、スキルを作成・管理します。オプションフィールドはポインターであるため、この例では1行のヘルパーfunc ptr[T any](v T) *T { return &v }を使用します。

Go

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

Create and manage a skill with the Databricks SDK for Java:

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

JavaScript SDKを使用して、スキルを作成および管理します：

TypeScript

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

ステップ 2：バンドルをuploadする

Files APIを使用して、SKILL.mdおよび関連ファイルをスキルのストレージパス/Skills/<catalog>/<schema>/<skill>/にuploadします。SKILL.mdは、nameとdescriptionを設定するYAML frontmatterで始まる必要があります。この例をSKILL.mdとして保存：

Markdown

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

PUTをFiles APIに送信します。DATABRICKS_HOSTにワークスペースURL（例：https://my-workspace.cloud.databricks.com）を設定し、DATABRICKS_TOKENにトークンを設定します。この例では、プロセス一覧に表示されないように、標準入力からcurlにトークンを渡します：

Bash

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

スキルのフォルダを作成し、ファイルをその中にコピーします：

Bash

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

Python

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

Go SDK

Go

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

Go Modular SDK には Files API が含まれていません。代わりにFiles SDK for Goでuploadしてください：

Go

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

Java

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

JavaScript Modular SDKにはFiles APIが含まれていないため、この例ではREST Endpointを直接呼び出します。DATABRICKS_HOSTおよびDATABRICKS_TOKEN環境変数から、https://my-workspace.cloud.databricks.comなどのワークスペースURLとトークンを読み取ります：

TypeScript

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}`);
}

ステップ3：スキルを完了する

確定処理では、SKILL.mdを読み込んで検証し、その後、frontmatterからスキルのbundle_nameとdescriptionを設定します。後でバンドルを変更した場合は、もう一度確定処理を実行してください。

REST API

Bash

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

CLI

Bash

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

Python SDK

Python

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

Go SDK

Go

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

Go Modular SDK

Go

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

Java SDK

Java

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

JS Modular SDK

TypeScript

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

Find a skill

スキーマ内でアクセスできるスキルを一覧表示し、リソース名を指定してスキルのメタデータを取得します。

REST API

Bash

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"

リストのレスポンスにnext_page_tokenが含まれている場合は、次のリクエストでpage_tokenとして渡します。next_page_tokenが存在しないか空になるまで続行します。

CLI

Bash

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

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

Python SDK

Python

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

CLI と Python イテレーターがページネーションを処理します。

アクセス権を付与

これらの例では、スキルにREAD VOLUMEを付与します。これにより、プリンシパルはスキルを読み取り、そのバンドルをdownloadできます。その他のスキル権限については、スキルへのアクセスを付与するを参照してください。

REST API

Bash

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

CLI

Databricks CLIでREAD VOLUMEを付与します：

Bash

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

Python SDK

次のDatabricks SDK for Pythonを使用してREAD VOLUMEに権限を付与します：

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 SDK

Databricks SDK for Goを使用してREAD VOLUMEを付与します：

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

次のDatabricks SDK for Javaを使用してREAD VOLUMEに権限を付与します：

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

スキルを更新

これらの例では、変更できる唯一のフィールドであるスキルのコメントを更新します。スキルの名前は変更できません。スキルの内容を変更するには、新しいバンドルをuploadし、スキルを再度確定してください。

条件付き更新の場合は、まずスキルを取得し、そのetagを更新とともに渡します。更新が成功するのは、その読み取り以降にスキルが変更されていない場合のみです。RESTクエリー文字列に追加するときは、etagをURLエンコードします。

REST API

Bash

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

CLI

Bash

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

Python SDK

Python

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 SDK

Go

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

Go

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

Java

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

TypeScript

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'),
});

スキルを削除

スキルを削除すると、そのスキルとバンドルが削除されます。エージェントはこれを読み込めなくなります。

最後に読み取ってから変更されていないことを条件に削除するため、スキルの現在のetagを渡すこともできます。RESTクエリー文字列内のetagをURLエンコードします。

REST API

Bash

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

CLI

Bash

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

Python SDK

Python

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

Go SDK

Go

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

Go Modular SDK

Go

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

Java SDK

Java

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

JS Modular SDK

TypeScript

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

その他のリソース

• Skills REST API
• スキルを管理する
• スキルを作成して共有する
• スキルを見つけて使用する