스킬 API 및 SDK 참고 자료

Important

이 기능은 베타 버전으로 제공됩니다. 계정 관리자는 계정 콘솔 미리 보기 페이지에서 이 기능에 대한 액세스를 관리할 수 있습니다. 계정 수준 미리 보기 관리를 참조하세요.

이 예시들을 활용해 기술 관리를 자동화하세요. API는 각 스킬을 '라는 이름skills/{catalog}.{schema}.{skill}의 Skill 자원으로 표현합니다. 에이전트와 함께 스킬을 저술하고 출판하려면 ' 기술 생성 및 공유'를 참조하세요. 특권과 거버넌스에 대해서는 Govern 기술을 참조하세요. 스킬에는 Terraform이나 Declarative Automation Bundles 리소스가 없습니다.

필수 구성 요소

스킬에 대해 거버넌스된 스키마를 설정하세요.
운영에 필요한 권한을 갖추세요.
사용할 클라이언트를 설치하고 인증하세요. REST API는 버전 요구사항이 없습니다; 각 도구와 SDK는 최소 버전을 가지고 있습니다:
- Databricks CLI: v1.20.0 이상
- Python SDK: databricks-sdk 0.142.0 이상
- Go SDK: databricks-sdk-go v0.184.0 이상
- Go Modular SDK: v0.1.0 이후입니다 github.com/databricks/sdk-go/aigateway
- Java SDK: databricks-sdk-java 0.157.0 이상
- 자바스크립트 SDK: @databricks/sdk-aigateway 0.23.0 이상
SDK 스니펫은 인증된 작업 공간 클라이언트를 가정합니다. w모듈형 SDK 스니펫은 Go와 client JavaScript에서 인증된 Unity Gateway 클라이언트 c 를 가정합니다.

API 작업

Skills REST API는 이러한 작업을 제공합니다. 각 부모 또한 요구 USE CATALOG 합니다 USE SCHEMA . 각 링크의 필드, 권한, 답변을 확인하세요.

Operation	사용 사례	필요한 권한
창조하다	스킬을 만들고 그 묶음 저장소를 제공하세요.	`CREATE VOLUME` 스키마에서
Upload	파일 API를 통해 업로드 `SKILL.md` 하고 지원하는 파일들도 모두 사용할 수 있습니다.	`WRITE VOLUME` 그리고 `READ VOLUME` 기술에 대하여
완료	읽고 검증 `SKILL.md`한 다음, 스킬의 번들 이름과 설명을 설정하세요.	`READ VOLUME` 스킬에 관해
목록	스키마에서 접근할 수 있는 스킬을 찾으세요.	`READ VOLUME`, `READ METADATA`또는 `MANAGE` 기술에 대해
받기	스킬의 메타데이터와 현재 `etag`상태의 내용을 읽어보세요.	`READ VOLUME`, `READ METADATA`또는 `MANAGE` 기술에 대해
Update	스킬 댓글을 변경하세요.	`MANAGE` 스킬에 관해
Delete	스킬과 그 묶음을 제거하세요.	`MANAGE` 스킬에 관해

스킬 소유자는 이 모든 것을 스킬에 가지고 있습니다. 기술 접근 보조금 항목을 참조하세요.

기술 만들기

스킬을 생성하는 데는 세 단계가 필요합니다: 스킬을 만들고, 번들을 업로드한 다음, 최종 확정입니다. 스킬을 최종 확정하기 전까지는 번들 이름과 설명이 비어 있습니다.

1단계: 기술 만들기

스킬을 체계적으로 만들어 보세요. comment 설정할 수 있는 유일한 필드입니다. Azure Databricks derived ves, namebundle_name, .description

main.default.my_skill 및 data-team를 사용자 고유의 값으로 바꿉니다.

REST API

/api/2.1/unity-catalog/skills에 와 POST 를 쿼리 매개변수로 보내 parentskill_id 세요:

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트에 다음과 같이 적으세요:

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

Python SDK

Databricks SDK를 사용해 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를 사용해 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로 스킬을 만들고 관리하세요. 선택적 필드는 포인터이므로 예시에서는 한 줄 보조 도구를 사용합니다. 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

Databricks SDK를 사용해 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 모듈러 SDK

JavaScript SDK로 기술을 만들고 관리하세요:

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

2단계: 번들 업로드

파일 API를 통해 스킬의 저장 경로/Skills/<catalog>/<schema>/<skill>/로 , 그리고 지원하는 파일들을 업로드하세요SKILL.md. SKILL.md 반드시 와 를 설정 namedescription하는 YAML 프론트매터로 시작해야 합니다. 이 예시를 저장해 주세요: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

파일 API로 보내 PUT 세요. 작업 공간 URL(예: https://my-workspace.cloud.databricks.com, )과 DATABRICKS_TOKEN 토큰으로 설정 DATABRICKS_HOST 하세요. 이 예시는 표준 입력에서 토큰 curl 을 전달하여 프로세스 목록에 나타나지 않게 합니다:

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

스킬 폴더를 만든 후 파일을 복사하세요:

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 소프트웨어 개발 키트 (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

Go Modular SDK에는 파일 API가 포함되어 있지 않습니다. Go 대신 Files SDK로 업로드하세요:

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 모듈러 SDK

JavaScript Modular SDK에는 파일 API가 포함되어 있지 않기 때문에, 이 예시는 REST 엔드포인트를 직접 호출합니다. 이 도구는 작업 공간 URL(예: https://my-workspace.cloud.databricks.com, )과 환경 변수에서 토큰 DATABRICKS_HOSTDATABRICKS_TOKEN 을 읽습니다:

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한 후 기술과 bundle_namedescription 그 앞부분에서 설정됩니다. 나중에 번들을 변경하면 다시 최종 확정하세요.

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 소프트웨어 개발 키트 (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 모듈러 SDK

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

기술을 찾아보세요

접근 가능한 스킬을 스키마에 나열한 후, 스킬의 리소스 이름으로 메타데이터를 받으세요.

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"

리스트 응답에 가 포함될 next_page_token때는 다음 요청처럼 page_token 전달합니다. 이 없거나 비어 있을 때까지 next_page_token 계속하세요.

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

CLI와 Python 이터레이터가 페이지네이션을 처리해줍니다.

접근 권한 부여

이 예시들은 기술을 부여 READ VOLUME 하며, 교장이 기술을 읽고 그 묶음을 다운로드할 수 있게 합니다. 다른 기술 특권에 대해서는 기술 접근 권한 부여를 참조하세요.

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

Databricks CLI와 함께 그랜트:READ VOLUME

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

Python SDK

READ VOLUME을 사용한 권한 부여:

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)

READ VOLUME를 사용한 권한 부여:

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

Java용 Databricks SDK와 함께 그랜트를 받으세요READ VOLUME:

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

스킬 업데이트

이 예시들은 스킬의 코멘트를 업데이트하는 것으로, 변경할 수 있는 유일한 필드입니다. 스킬 이름은 바꿀 수 없습니다. 스킬 내용을 변경하려면 새 번들을 업로드 하고 스킬을 다시 최종 확정 하세요.

조건부 업데이트의 경우, 먼저 스킬을 얻 고 업데이트와 함께 패스 etag 하세요. 업데이트는 그 스킬이 그 이후 변경되지 않았을 때만 성공합니다. REST 쿼리 문자열에 추가할 때 를 etag URL-인코딩하세요.

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 소프트웨어 개발 키트 (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 모듈러 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'),
});

기술 삭제

스킬을 삭제하면 그 스킬과 그 묶음이 제거됩니다. 요원들은 더 이상 불러올 수 없습니다.

또한 스킬의 현재 상태를 etag 패스하여 삭제가 마지막 읽기 이후 변경되지 않은 조건으로 설정할 수도 있습니다. REST 쿼리 문자열을 etag URL-인코딩합니다.

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 소프트웨어 개발 키트 (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 모듈러 SDK

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

추가 리소스

피드백

이 페이지가 도움이 되었나요?

2026-10-15 에 마지막으로 업데이트됨