Referência da API e do SDK de Skills

info

Beta

Este recurso está em Beta. Os administradores da account podem gerenciar o acesso a este recurso na página Previews do console da account. Consulte Gerenciar prévias no nível da account.

Use estes exemplos para automatizar o gerenciamento de habilidades. A API representa cada habilidade como um recurso Skill chamado skills/{catalog}.{schema}.{skill}. Para criar e publicar uma habilidade com um agente, consulte Criar e compartilhar habilidades. Para ver os privilégios e a governança, consulte Governar habilidades. As habilidades não têm recursos do Terraform nem dos Pacotes de Automação Declarativa.

Pré-requisitos

Configure um esquema governado para habilidades.
Tenha as permissões necessárias para sua operação.
Instale e autentique o cliente que você pretende usar. A API REST não tem requisito de versão; cada ferramenta e SDK tem uma versão mínima:
- Databricks CLI: v1.20.0 ou acima
- SDK do Python: databricks-sdk v0.184.0 e acima
- SDK do Go: databricks-sdk-go v0.184.0 e acima
- SDK modular do Go: github.com/databricks/sdk-go/aigateway v0.1.0 e acima
- SDK do Java: databricks-sdk-java 0.157.0 e acima
- SDK do JavaScript: @databricks/sdk-aigateway 0.23.0 e acima
Os snippets do SDK pressupõem um cliente do Workspace autenticado, w; os snippets do SDK modular pressupõem um cliente do Unity Gateway autenticado, c em Go e client em JavaScript.

Operações da API

A API REST de Skills fornece estas operações. Cada um também exige USE CATALOG e USE SCHEMA no recurso pai. Consulte cada link para ver seus campos, permissões e respostas.

Operação	Caso de uso	Permissões obrigatórias
Criar	Crie uma habilidade e provisione o armazenamento do pacote dela.	`CREATE VOLUME` no esquema
Upload	Faça upload de `SKILL.md` e de quaisquer arquivos de suporte por meio da API Files.	`WRITE VOLUME` e `READ VOLUME` na habilidade
Finalizar	Leia e valide `SKILL.md` e, em seguida, defina o nome e a descrição do bundle da habilidade.	`READ VOLUME` na habilidade
Lista	Encontre as habilidades às quais você pode ter acesso em um esquema.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` na habilidade
Get	Leia os metadados da habilidade e o `etag` atual.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` na habilidade
Atualizar	Altere o comentário da habilidade.	`MANAGE` na habilidade
Deletar	Remova uma habilidade e seu pacote.	`MANAGE` na habilidade

Operação	Caso de uso	Permissões obrigatórias
Criar	Crie uma habilidade e provisione o armazenamento do pacote dela.	`CREATE VOLUME` no esquema
Upload	Faça upload de `SKILL.md` e de quaisquer arquivos de suporte por meio da API Files.	`WRITE VOLUME` e `READ VOLUME` na habilidade
Finalizar	Leia e valide `SKILL.md` e, em seguida, defina o nome e a descrição do bundle da habilidade.	`READ VOLUME` na habilidade
Lista	Encontre as habilidades às quais você pode ter acesso em um esquema.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` na habilidade
Get	Leia os metadados da habilidade e o `etag` atual.	`READ VOLUME`, `READ METADATA`, ou `MANAGE` na habilidade
Atualizar	Altere o comentário da habilidade.	`MANAGE` na habilidade
Deletar	Remova uma habilidade e seu pacote.	`MANAGE` na habilidade

O proprietário da habilidade detém todas estas permissões na habilidade. Consulte Conceder acesso às habilidades.

Criar uma habilidade

A criação de uma habilidade envolve três passos: criar a habilidade, fazer upload do pacote dela e, em seguida, finalizá-la. Até que você finalize uma habilidade, o nome e a descrição do pacote dela ficarão vazios.

O passo 1: criar a habilidade

Crie a habilidade em um esquema. comment é o único campo que você pode definir. O Databricks deriva name, bundle_name e description.

Substitua main.default.my_skill e data-team pelos seus próprios valores.

Envie um POST para /api/2.1/unity-catalog/skills, passando parent e skill_id como parâmetros de query:

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

Passe o esquema pai e o nome da habilidade e forneça o comentário com --json:

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

Crie e gerencie uma skill com o SDK do Databricks para 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"),
)

Crie e gerencie uma habilidade com o SDK do Databricks para 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"},
})

Crie e gerencie uma habilidade com o SDK modular para Go. Os campos opcionais são ponteiros, por isso o exemplo usa uma função auxiliar de uma linha, 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")},
})

Crie e gerencie uma habilidade com o SDK do Databricks para 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")));

Crie e gerencie uma habilidade com o SDK JavaScript:

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

o passo 2: fazer upload do pacote

Faça upload de SKILL.md e de quaisquer arquivos de suporte para o caminho de armazenamento da habilidade, /Skills/<catalog>/<schema>/<skill>/, por meio da API Files. SKILL.md deve começar com front matter YAML que define name e description. Salvar este exemplo como 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.

Envie um PUT para a API de arquivos. Defina DATABRICKS_HOST como a URL do seu workspace, como https://my-workspace.cloud.databricks.com, e DATABRICKS_TOKEN como um token. Este exemplo transmite o token para curl pela entrada padrão para que ele não apareça na lista de processos:

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

Crie a pasta da habilidade e copie o arquivo para ela:

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
with open("SKILL.md", "rb") as f:
    w.files.upload("/Skills/main/default/my_skill/SKILL.md", f, overwrite=True)

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

O SDK modular do Go não inclui a API Files. Em vez disso, faça upload com o SDK Files para Go:

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

O SDK Modular do JavaScript não inclui a API Files, portanto este exemplo chama diretamente o endpoint REST. Ele lê a URL do workspace, como https://my-workspace.cloud.databricks.com, e um token das variáveis de ambiente DATABRICKS_HOST e DATABRICKS_TOKEN:

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

o passo 3: Finalizar a habilidade

A finalização lê e valida SKILL.md e, em seguida, define bundle_name e description da skill a partir do frontmatter dela. Se você alterar o pacote mais tarde, finalize-o novamente.

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

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

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

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

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

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

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

Encontre uma habilidade

Liste as habilidades às quais você tem acesso em um esquema e, em seguida, obtenha os metadados de uma habilidade pelo nome do recurso.

REST API
CLI
Python SDK

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"

Quando a resposta da lista incluir next_page_token, passe como page_token na próxima solicitação. Continue até que next_page_token esteja ausente ou vazio.

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

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

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

A CLI e o iterador do Python gerenciam a paginação para você.

Conceder acesso

Estes exemplos concedem READ VOLUME à skill, permitindo que o principal leia a skill e faça download do pacote. Para ver os outros privilégios da skill, consulte Conceder acesso a skills.

REST API
CLI
Python SDK
Go SDK
Java SDK

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

Conceda READ VOLUME usando a CLI do Databricks:

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

Conceda READ VOLUME usando o SDK do Databricks para Python:

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])],
)

Conceda READ VOLUME usando o SDK do Databricks para Go:

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

Conceda READ VOLUME com o SDK do Databricks para Java:

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

Atualizar uma habilidade

Estes exemplos atualizam o comentário da habilidade, o único campo que você pode alterar. O nome da habilidade não pode ser alterado. Para alterar o conteúdo de uma habilidade, faça upload do novo pacote e finalize a habilidade novamente.

Para fazer uma atualização condicional, primeiro recupere a habilidade e passe seu etag junto com a atualização. A atualização só será bem-sucedida se a habilidade não tiver sido alterada desde essa leitura. Codifique o etag para URL ao adicioná-lo a uma string de query REST.

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

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

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

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

Excluir uma habilidade

Excluir uma habilidade remove essa habilidade e seu pacote. Os agentes não podem mais carregá-lo.

Você também pode passar o etag atual da habilidade para tornar a exclusão condicional a ele não ter sido alterado desde a última leitura. Codifique o etag para URL nas strings de query REST.

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

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

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

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

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

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

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

Pré-requisitos​

Operações da API​

Criar uma habilidade​

O passo 1: criar a habilidade​

o passo 2: fazer upload do pacote​

o passo 3: Finalizar a habilidade​

Encontre uma habilidade​

Conceder acesso​

Atualizar uma habilidade​

Excluir uma habilidade​

Outros recursos​