Skip to content

ADK 智能体技能 (Skills)

Supported in ADKPython v1.25.0Experimental

智能体 技能 (Skill) 是一个自包含的功能单元，ADK 智能体可以使用它来执行特定任务。智能体技能封装了任务所需的必要指令、资源和工具，基于智能体技能规范 (Agent Skill specification)。技能的结构允许它增量加载，以最小化对智能体运行上下文窗口的影响。

实验性

技能功能是实验性的，存在一些可用的已知限制。我们欢迎你的反馈！

开始使用

使用 SkillToolset 类将一个或多个技能包含在你的智能体定义中，然后添加到智能体的工具列表中。你可以在代码中定义技能，或从文件定义加载技能，如下所示：

import pathlib

from google.adk import Agent
from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset

# 从目录加载天气技能
weather_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "weather_skill"
)

# 创建技能工具集
my_skill_toolset = skill_toolset.SkillToolset(
    skills=[weather_skill]
)

# 定义根智能体
root_agent = Agent(
    model="gemini-2.5-flash",
    name="skill_user_agent",
    description="一个可以利用专业技能的智能体。",
    instruction=(
        "你是一个有用的助手，可以利用技能来执行任务。"
    ),
    tools=[
        my_skill_toolset,
    ],
)

有关带有技能的 ADK 智能体的完整代码示例（包括基于文件的和内联的技能定义），请参阅代码示例 skills_agent。

定义技能

技能功能允许你创建技能指令和资源的模块化包，智能体可以根据需要加载。这种方法有助于你组织智能体的能力，并由于仅在需要时加载指令而优化上下文窗口。技能的结构分为三个级别：

  • L1 (元数据)： 提供用于技能发现的元数据。此信息定义在 SKILL.md 文件的 Frontmatter 部分，包括技能名称和描述等属性。
  • L2 (指令)： 包含技能的主要指令，当技能被智能体触发时加载。此信息定义在 SKILL.md 文件的正文中。
  • L3 (资源)： 包括其他资源，如参考材料、资产和脚本，可以根据需要加载。这些资源组织在以下目录中：
    • references/：具有扩展指令、工作流或指南的其他 Markdown 文件。
    • assets/：资源材料，如数据库模式、API 文档、模板或示例。
    • scripts/：智能体运行环境支持的可执行脚本。

通过文件定义技能

以下目录结构显示了在 ADK 智能体项目中包含技能的推荐方式。下面显示的 example_skill/ 目录以及任何并行的技能目录必须遵循智能体技能规范 (Agent Skill specification) 文件结构。只有 SKILL.md 文件是必须的。

my_agent/
    agent.py
    .env
    skills/
        example_skill/        # 技能
            SKILL.md          # 主要指令（必须）
            references/
                REFERENCE.md  # 详细的 API 参考
                FORMS.md      # 表单填写指南
                *.md          # 领域特定信息
            assets/
                *.*           # 模板、图像、数据
            scripts/
                *.py          # 工具脚本

尚不支持脚本执行

目前尚不支持脚本执行，这是一个已知限制。

在代码中定义技能

在 ADK 智能体中，你还可以使用 Skill 模型类在智能体的代码中定义技能，如下所示。这种定义技能的方法使你能够从 ADK 智能体代码中动态修改技能。

from google.adk.skills import models

# 在代码中定义一个简单的问候技能
greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "一个友好的问候技能，可以向特定的人打招呼。"
        ),
    ),
    instructions=(
        "步骤 1：阅读 'references/hello_world.txt' 文件以了解如何"
        " 问候用户。步骤 2：根据参考资料返回问候语。"
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "你好！很高兴你能在这里！",
            "example.md": "这是一个示例参考资料。",
        },
    ),
)

已知限制

技能功能是实验性的，包含以下限制：

  • 脚本执行： 技能功能目前不支持脚本执行（scripts/ 目录）。

下一步

查看这些用于构建带有技能的智能体的资源：