スキルを作成して管理する

このガイドでは、REST API を使用して Skill Registry でスキルを作成、更新、管理する方法について説明します。

始める前に

Skill Registry を使用する前に、環境を設定します。

  1. In the Cloud de Confiance console, on the project selector page, select or create a Cloud de Confiance project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Cloud de Confiance project.

  3. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  4. Make sure that you have the following role or roles on the project: roles/aiplatform.viewer or roles/aiplatform.user, roles/serviceusage.serviceUsageConsumer

    Check for the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Cloud de Confiance console, go to the IAM page.

      Go to IAM
    2. Select the project.
    3. Click Grant access.

    4. In the New principals field, enter your user identifier. This is typically the identifier for a user in a workforce identity pool. For details, see Represent workforce pool users in IAM policies, or contact your administrator.

    5. Click Select a role, then search for the role.
    6. To grant additional roles, click Add another role and add each additional role.
    7. Click Save.

コンプライアンス

次の表に、コンプライアンス ステータスをまとめます。

機能 ステータス
アクセスの透明性 サポート対象
米国と EU のデータ所在地（DRZ） サポート対象
顧客管理の暗号鍵（CMEK） サポート対象外
HIPAA 認定 サポート対象外
VPC SC サポート対象外

利用可能なリージョン

スキル レジストリは、次のリージョンで利用できます。

リージョン ロケーション
us-central1 アイオワ
europe-west4 オランダ
us-east5 コロンバス（オハイオ州）

スキルを作成する

新しいスキルを作成するには、CreateSkill メソッドを使用します。このオペレーションは、長時間実行オペレーションです。

スキル構造の例については、Google Cloud Skills リポジトリの SKILL.md ファイルをご覧ください。

REST

以降のセクションでは、REST API を使用してスキルを作成する方法について説明します。

ペイロードを準備する

API を呼び出す前に、スキルファイルを ZIP アーカイブにパッケージ化し、1 行の base64 文字列にエンコードします。ペイロードを準備する手順は次のとおりです。

  1. スキル ディレクトリに移動します。

    cd <SKILL_DIRECTORY>

  2. ZIP アーカイブを作成し、base64 にエンコードします。

    次に例を示します。

    zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。

  • LOCATION: スキルのリージョン。詳細については、利用可能なリージョンをご覧ください。

  • SKILL_ID: SKILL_ID は不変であり、作成後にスキルを削除しても、永続的に予約されたままになります。スキル ID は次の制約に従う必要があります。

    • 1 ～ 63 文字で指定する必要があります。
    • 使用できるのは小文字、数字、ハイフンのみです。
    • 先頭は英文字、末尾は英文字または数字にする必要があります。
    • gcp- で始まってはならない（この接頭辞は組み込みスキル用に予約されています）。

  • DISPLAY_NAME: エージェントで使用されるスキルの名前。RetrieveSkills メソッドは、表示名と説明を使用して関連するスキルを検索します。

  • DESCRIPTION: スキルの機能の説明。

  • BASE64_ZIPPED_BODY: スキル アーカイブの zip ファイルの Base64 エンコードされたコンテンツ。

HTTP メソッドと URL

POST https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID

リクエストの本文（JSON）

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}

curl コマンド

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "zippedFilesystem": "BASE64_ZIPPED_BODY"
    }' \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills?skillId=SKILL_ID"

Python

スキルファイル（SKILL.md、手順、コードファイルなど）をローカル ディレクトリに整理します。SDK は、ローカル ディレクトリ パス（自動的に圧縮されます）または事前に圧縮されたパスのいずれかの受け渡しをサポートしています。

google-cloud-aiplatform（agentplatform を提供）バージョン 1.154.0 以降の場合:

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.create(
    skill_id="SKILL_ID",
    display_name="DISPLAY_NAME",
    description="DESCRIPTION",
    config={
        # Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

1.154.0 より前の google-cloud-aiplatform（agentplatform を提供）バージョン:

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.create(
    display_name="DISPLAY_NAME",
    description="DESCRIPTION",
    config={
        "skill_id": "SKILL_ID",
        # Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Node.js

スキルファイル（SKILL.md、手順、コードファイルなど）をローカル ディレクトリに整理します。SDK は、ローカル ディレクトリ パス（自動的に圧縮されます）または事前に圧縮されたパスのいずれかの受け渡しをサポートしています。

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.create({
  skillId: 'SKILL_ID',
  displayName: 'DISPLAY_NAME',
  description: 'DESCRIPTION',
  config: {
    // Local directory path (automatically compressed) or pre-zipped path (.zip)
    localPath: 'SKILL_PATH',
  },
});
console.log(skill.name);

スキルを更新する

既存のスキルを更新するには、UpdateSkill メソッドを使用します。このオペレーションは、長時間実行オペレーションです。

既存のスキルの表示名、説明、ペイロード（zip 形式のファイル システム）を更新できます。updateMask クエリ パラメータにリストされているフィールドのみが更新されます。

REST

以降のセクションでは、REST API を使用してスキルを更新する方法について説明します。

ペイロードを準備する

省略可。スキルのファイルを更新する場合は、更新したスキルのファイルを ZIP 形式のアーカイブにパッケージ化し、単一行の Base64 文字列にエンコードします。

  1. スキル ディレクトリに移動します。

    cd <SKILL_DIRECTORY>

  2. ZIP アーカイブを作成して base64 にエンコードします。

    zip -r skill.zip scripts/ references/ SKILL.md assets/ && base64 -w 0 -i skill.zip

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: スキルのリージョン。詳細については、利用可能なリージョンをご覧ください。
  • SKILL_ID: 更新するスキルの ID。
  • DISPLAY_NAME: 省略可。スキルの新しい名前。
  • DESCRIPTION: 省略可。スキルの機能の新しい説明。
  • BASE64_ZIPPED_BODY: 省略可。更新されたスキル アーカイブの Base64 エンコードされたコンテンツ。

HTTP メソッドと URL

PATCH https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

リクエストの本文（JSON）

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION",
"zippedFilesystem": "BASE64_ZIPPED_BODY"
}

curl コマンド

次の curl コマンドは、表示名、説明、圧縮されたスキルファイルを更新します。

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d '{
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "zippedFilesystem": "BASE64_ZIPPED_BODY"
    }' \
    "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID?updateMask=displayName,description,zippedFilesystem"

Python

この SDK は、解凍されたローカル ディレクトリ パスまたは事前圧縮されたパスのいずれかを渡すことで、スキルファイルの更新をサポートします。

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.update(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID",
    config={
        "display_name": "DISPLAY_NAME",
        "description": "DESCRIPTION",
        # Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
        "local_path": "SKILL_PATH",
    },
)
print(skill.name)

Node.js

この SDK は、解凍されたローカル ディレクトリ パスまたは事前圧縮されたパスのいずれかを渡すことで、スキルファイルの更新をサポートします。

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.update({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
  config: {
    displayName: 'DISPLAY_NAME',
    description: 'DESCRIPTION',
    // Optional. Local directory path (automatically compressed) or pre-zipped path (.zip)
    localPath: 'SKILL_PATH',
  },
});
console.log(skill.name);

スキルを一覧表示する

特定の場所にあるスキルに関する概要メタデータ（名前、表示名、説明など）を取得するには、ListSkills メソッドを使用します。

REST

以降のセクションでは、REST API を使用してスキルを一覧表示する方法について説明します。

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: 一覧表示するスキルのリージョン。詳細については、利用可能なリージョンをご覧ください。

HTTP メソッドと URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills

curl コマンド

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills"

出力例

{
"name": "projects/1234567890/locations/us-central1/skills/3456789012",
"createTime": "2026-05-10T00:02:12.497720Z",
"updateTime": "2026-05-10T00:02:19.064874Z",
"displayName": "cymbal_skill",
"description": "A skill for managing Cymbal projects.",
"state": "ACTIVE"
}

Python

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

pager = client.skills.list()
for skill in pager:
    print(skill.name, skill.display_name)

Node.js

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const pager = await client.skills.list();
for await (const skill of pager) {
  console.log(skill.name, skill.displayName);
}

スキルを取得する

スキルの最新リビジョンのメタデータとペイロードを取得するには、GetSkill メソッドを使用します。

REST

以降のセクションでは、REST API を使用してスキルを取得する方法について説明します。

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: スキルが配置されているリージョン。詳細については、利用可能なリージョンをご覧ください。
  • SKILL_ID: 取得するスキルの ID。

HTTP メソッドと URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

curl コマンド

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"

Python

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

skill = client.skills.get(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
print(skill)

Node.js

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const skill = await client.skills.get({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
console.log(skill);

スキルを削除する

スキルとそのすべてのリビジョンを削除するには、DeleteSkill メソッドを使用します。このオペレーションは長時間実行オペレーションです。

REST

以降のセクションでは、REST API を使用してスキルを削除する方法について説明します。

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: 削除するスキルが配置されているリージョン。詳細については、利用可能なリージョンをご覧ください。
  • SKILL_ID: 削除するスキルの ID。

HTTP メソッドと URL

DELETE https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID

curl コマンド

curl -X DELETE \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"

Python

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

client.skills.delete(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)

Node.js

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

await client.skills.delete({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});

スキル リビジョンを一覧表示する

特定のスキルの変更履歴を取得するには、ListSkillRevisions メソッドを使用します。

REST

以降のセクションでは、REST API を使用してスキル リビジョンを一覧表示する方法について説明します。

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: 必要なスキルが配置されているリージョン。詳細については、利用可能なリージョンをご覧ください。
  • SKILL_ID: スキルの ID。

HTTP メソッドと URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions

curl コマンド

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions"

出力例

{
  "skillRevisions": [
    {
      "name": "projects/1234567890/locations/us-central1/skills/cymbal_skill/revisions/4567890123",
      "createTime": "2026-05-10T00:02:12.497720Z",
      "updateTime": "2026-05-10T00:02:19.064874Z"
    }
  ]
}

Python

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

response = client.skills.revisions.list(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID"
)
for skill_revision in response.skill_revisions:
    print(skill_revision.name, skill_revision.create_time)

Node.js

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const response = await client.skills.revisions.list({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID',
});
for (const revision of response.skillRevisions || []) {
  console.log(revision.name, revision.createTime);
}

スキル リビジョンを取得する

スキルの特定のリビジョンを取得するには、GetSkillRevision メソッドを使用します。

REST

以降のセクションでは、REST API を使用してスキル リビジョンを取得する方法について説明します。

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: スキルのリージョン。詳細については、利用可能なリージョンをご覧ください。
  • SKILL_ID: スキルの ID。
  • REVISION_ID: 取得する特定のリビジョンの ID。これは、ListSkillRevisions メソッドから返される name フィールドで確認できます。たとえば、name が projects/1234567890/locations/us-central1/skills/cymbal-skill/revisions/4567890123 の場合、リビジョン ID は 4567890123 です。

HTTP メソッドと URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID

curl コマンド

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"

Python

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

revision = client.skills.revisions.get(
    name="projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID"
)
print(revision)

Node.js

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const revision = await client.skills.revisions.get({
  name: 'projects/PROJECT_ID/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID',
});
console.log(revision);

スキルを取得する

RetrieveSkills メソッドを使用して、セマンティック検索でスキルを検索します。たとえば、find skills to manage cloud resources のように、達成したいタスクを説明してスキルを検索できます。

REST

以降のセクションでは、REST API を使用してスキルを取得する方法について説明します。

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: 検索するスキルが配置されているリージョン。詳細については、利用可能なリージョンをご覧ください。
  • QUERY: 一致するスキルを検索するクエリ文字列。

HTTP メソッドと URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY

curl コマンド

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/skills:retrieve?query=QUERY"

Python

import agentplatform

client = agentplatform.Client(project="PROJECT_ID", location="LOCATION")

response = client.skills.retrieve(
    query="QUERY",
    config={"top_k": TOP_K},
)
for retrieved_skill in response.retrieved_skills:
    print(retrieved_skill.skill_name, retrieved_skill.description)

Node.js

import { Client } from '@google-cloud/agentplatform';

const client = new Client({
  project: 'PROJECT_ID',
  location: 'LOCATION',
});

const response = await client.skills.retrieve({
  query: 'QUERY',
  config: {
    topK: TOP_K,
  },
});
for (const retrievedSkill of response.retrievedSkills || []) {
  console.log(retrievedSkill.skillName, retrievedSkill.description);
}

長時間実行オペレーションの詳細を取得する

Skill Registry API の一部のメソッド（CreateSkill、UpdateSkill、DeleteSkill など）は非同期で、長時間実行オペレーションを返します。長時間実行オペレーションは、完了にかなりの時間がかかる可能性があるオペレーションに使用される API パターンです。API は、オペレーションの完了を待つのではなく、オペレーション リソースを返します。

これらのメソッドからのレスポンスには、オペレーション ID を含む name フィールドが含まれます。たとえば、name は projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/operations/OPERATION_ID のようになります。

長時間実行オペレーションのステータスを確認して詳細を取得するには、抽出した OPERATION_ID を使用して GetOperation メソッドを使用します。

REST

以降のセクションでは、REST API を使用してオペレーションを取得する方法について説明します。

リクエスト変数

リクエストのデータを使用する前に、次のように置き換えます。

  • PROJECT_ID: 実際の Cloud de Confiance by S3NS プロジェクト ID。
  • LOCATION: オペレーションが実行されているリージョン。これは、最初のリクエストで使用したリージョンと一致している必要があります。詳細については、利用可能なリージョンをご覧ください。
  • OPERATION_ID: オペレーションの ID。これは、CreateSkill、UpdateSkill、または DeleteSkill によって返される name フィールドから抽出します。

HTTP メソッドと URL

GET https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID

curl コマンド

curl -X GET \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://LOCATION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID"

次のステップ

ガイド

Agent Platform で Managed Agents API を使用してエージェントを作成または更新するときに、登録済みのスキルを関連付ける方法について説明します。

ガイド

ADK でスキル レジストリと統合する方法について説明します。