API de habilidades y referencia del SDK

Importante

Esta característica se encuentra en su versión beta. Los administradores de cuentas pueden administrar el acceso a esta característica desde la página Vista previa de la consola de la cuenta. Consulte Gestionar previsualizaciones a nivel de cuenta.

Utiliza estos ejemplos para automatizar la gestión de habilidades. La API representa cada habilidad como un Skill recurso llamado skills/{catalog}.{schema}.{skill}. Para crear y publicar una habilidad con un agente, consulta Crear y compartir habilidades. Para privilegios y gobernanza, véase Habilidades de Gobernar. Las habilidades no tienen recursos de Terraform ni de Paquetes de Automatización Declarativa.

Prerrequisitos

  • Establece un esquema gobernado para las habilidades.

  • Ten los permisos necesarios para tu operación.

  • Instala y autentica el cliente que planeas usar. La API REST no requiere versión; cada herramienta y SDK tiene una versión mínima:

    Los fragmentos del SDK asumen un cliente de espacio de trabajo autenticado, w; Los fragmentos modulares del SDK asumen un cliente Unity Gateway autenticado, c tanto en Go como client en JavaScript.

Operaciones de la API REST

La API REST de Skills proporciona estas operaciones. Cada una también requiere USE CATALOG y USE SCHEMA recae sobre el padre. Sigue cada enlace para sus campos, permisos y respuestas.

Operation Caso de uso Permisos necesarios
Crear Crea una habilidad y provisiona su almacenamiento en paquete. CREATE VOLUME en el esquema
Upload Sube SKILL.md y cualquier archivo de soporte a través de la API de archivos. WRITE VOLUME y READ VOLUME en la habilidad
Finalizar Lee y valida SKILL.md, luego establece el nombre y la descripción del paquete de la habilidad. READ VOLUME Sobre la habilidad
Lista Encuentra habilidades a las que puedas acceder en un esquema. READ VOLUME, READ METADATA, o MANAGE sobre la habilidad
Get Lee los metadatos y los datos actuales etagde una habilidad READ VOLUME, READ METADATA, o MANAGE sobre la habilidad
Update Cambia el comentario de la habilidad. MANAGE Sobre la habilidad
Eliminar Elimina una habilidad y su paquete. MANAGE Sobre la habilidad

El dueño de la habilidad tiene todas estas en la habilidad. Consulta Conceder acceso a habilidades.

Creación de una aptitud

Crear una habilidad requiere tres pasos: crear la habilidad, subir su paquete y luego finalizarla. Hasta que finalizes una habilidad, su nombre y descripción del paquete están vacíos.

Paso 1: Crear la habilidad

Crea la habilidad en un esquema. comment es el único campo que puedes establecer. Azure Databricks deriva name, bundle_name, e description.

Reemplace main.default.my_skill y data-team con sus propios valores.

API DE REST

Envía a POST/api/2.1/unity-catalog/skills, pasando parent y skill_id como parámetros de consulta:

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

Pásame el esquema padre y el nombre de la habilidad, y proporciona el comentario con --json:

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

SDK de Python

Crea y gestiona una habilidad con el SDK Databricks para 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"),
)

Kit de Desarrollo de Software Go

Crea y gestiona una habilidad con el SDK Databricks para 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

Crea y gestiona una habilidad con el SDK Modular de Go. Los campos opcionales son punteros, por lo que el ejemplo utiliza un asistente de una línea, 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")},
})

SDK de Java

Crea y gestiona una habilidad con el SDK Databricks para 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

Crea y gestiona una habilidad con el SDK de JavaScript:

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

Paso 2: Sube el paquete

Sube SKILL.md, y cualquier archivo de apoyo, a la ruta de almacenamiento de la habilidad, /Skills/<catalog>/<schema>/<skill>/, a través de la API de Archivos. SKILL.md debe comenzar con frontmatter YAML que establezca name y description. Guarda este ejemplo como 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.

API DE REST

Envía a PUT la API de archivos. Establece DATABRICKS_HOST la URL de tu espacio de trabajo, como https://my-workspace.cloud.databricks.com, y DATABRICKS_TOKEN un token. Este ejemplo pasa el token a curl una entrada estándar para que no aparezca en la lista de procesos:

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

Crea la carpeta de la habilidad y luego copia el archivo dentro:

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

SDK de Python

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

Kit de Desarrollo de Software 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

El SDK Modular de Go no incluye la API de Archivos. Sube con el SDK de archivos para Go en su lugar:

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

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

El SDK Modular de JavaScript no incluye la API de Archivos, así que este ejemplo llama directamente al endpoint REST. Lee la URL del espacio de trabajo, como https://my-workspace.cloud.databricks.com, y un token de las DATABRICKS_HOST variables de entorno y DATABRICKS_TOKEN de entorno:

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

Paso 3: Finaliza la habilidad

Finalizar lee y valida SKILL.md, luego establece la habilidad bundle_name y description desde su material inicial. Si cambias el paquete más adelante, finaliza de nuevo.

API DE REST

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

SDK de Python

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

Kit de Desarrollo de Software Go

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

SDK de Java

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

Encuentra una habilidad

Haz una lista de las habilidades a las que puedes acceder en un esquema y luego obtén los metadatos de una habilidad por el nombre de su recurso.

API DE REST

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"

Cuando la respuesta de la lista incluya next_page_token, pásala como page_token en la siguiente petición. Continúa hasta que next_page_token falte o se vacíe.

CLI

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

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

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

La CLI y el iterador de Python se encargan de la paginación por ti.

Conceder acceso

Estos ejemplos otorgan READ VOLUME a la habilidad, que permite al director leer la habilidad y descargar su paquete. Para los otros privilegios de habilidad, véase Conceder acceso a habilidades.

API DE REST

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 con la CLI de Databricks:

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

SDK de Python

Concede READ VOLUME con el SDK de Databricks para 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])],
)

Kit de Desarrollo de Software Go

Conceder READ VOLUME con el SDK de Databricks para 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},
	}},
})

SDK de Java

Conceder READ VOLUME con el SDK de Databricks para 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)))));

Actualización de una aptitud

Estos ejemplos actualizan el comentario de la habilidad, el único campo que puedes cambiar. El nombre de la habilidad no puede cambiarse. Para cambiar el contenido de una habilidad, sube el nuevo paquete y finaliza la habilidad de nuevo.

Para una actualización condicional, primero consigue la habilidad y la etag aprueba con la actualización. La actualización solo tiene éxito si la habilidad no ha cambiado desde esa lectura. Codifica URL al etag añadirlo a una cadena de consulta REST.

API DE REST

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

SDK de 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"),
)

Kit de Desarrollo de Software 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

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

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

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

Eliminar una habilidad

Eliminar una habilidad la elimina junto con su paquete. Los agentes ya no pueden cargarlo.

También puedes pasar la corriente etag de la habilidad para condicionar la eliminación a que no haya cambiado desde la última lectura. Codifica URL las etag cadenas de consulta in REST.

API DE REST

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

CLI

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

SDK de Python

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

Kit de Desarrollo de Software Go

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

SDK de Java

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

JS Modular SDK

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

Recursos adicionales

  • Se actualizó por última vez el