以下
SkillToolset 示例按 Google ADK 2.2 接口编写。先完成安装与模型配置
本地技能
在项目中创建skills/incident-summary/SKILL.md:
skills/incident-summary/SKILL.md
main.py:
main.py
list_skills、load_skill、load_skill_resource 和 run_skill_script;配置 registry 后还会提供 search_skills
SkillToolset 参数
执行技能脚本
Shell 脚本超时或被取消时,会终止整个进程组(包括脚本派生的子进程)并在最多 5 秒内完成清理,避免遗留孤儿进程
scripts/,在上例加载 skill 后,用以下片段替换工具集和智能体配置:
SkillToolset 不会自动安装脚本依赖。Harness、CLI 生成代码和 AgentKit 会话能力服务的相应加载入口会配置本地执行器;使用这些入口前同样需要审查技能来源
云端技能空间
先准备有读取权限的技能来源 ID,以及读取技能列表和下载文件所需的账号凭证。SKILL_SOURCE_ID 是以下示例自定义的环境变量;每个 VeSkillRegistry 只接受一个来源 ID,不能传逗号分隔列表
未提供完整 AK/SK 时会尝试运行环境绑定的 IAM Role 凭证。AgentKit 技能空间可用
AGENTKIT_TOOL_REGION 指定地域;资源、凭证、区域与平台必须匹配。SkillHub 与 AgentKit 技能空间的服务可用性分别以账号实际开通情况为准
cloud_skills.py
python cloud_skills.py 查看当前可发现的技能
初始化 registry 不会全量下载技能。
search_skills 拉取来源中的全部技能元信息,目前不按搜索词过滤;get_skill 刷新元信息并按名称下载所需技能。相同版本可复用缓存,版本变化后重新下载。缓存目录必须可写
云端技能中非标准的 frontmatter 字段,例如 allowed-tools、triggers 和 requires,会保存在 metadata 中。保留这些字段不代表自动执行其权限或依赖声明
技能空间策略
设置SKILL_SPACE_POLICY 环境变量可以按技能 ID 筛选从云端技能空间加载的技能。该变量为 JSON 对象,包含以下字段:
mode 为 allow 时仅加载 ID 在列表中的技能;mode 为 deny 时排除 ID 在列表中的技能。未设置该变量时加载全部技能
策略值最大为 8192 字节。设置格式错误的策略时不会加载任何云端技能,以避免因疏忽暴露不受限的技能集合
SKILL_SPACE_POLICY 后,VeADK 会自动将其转发到远端沙箱会话,使沙箱中的技能加载遵循相同的筛选规则。使用 execute_skills、invoke_skill、poll_skill 或 run_sandbox_agent 时无需手动传递策略,详见代码沙箱
Harness 技能中心
先按 Harness 服务部署 创建项目并配置部署凭证,再将下方示例名称和 ID 替换为可访问的技能。普通名称或 slug 表示 Skill Hub 技能,space: 前缀表示 AgentKit 技能空间
harness.yaml 使用列表保存来源:
space: 来源会加载空间内的全部技能。调用时可以追加本次所需技能:
任一技能无法下载、缺少有效
SKILL.md 或格式无效时,加载会失败,不会继续使用不完整的集合。技能中心需要读取空间及其对象存储内容的权限
技能目录结构
每个技能使用独立目录,至少包含SKILL.md;name 应与目录名一致,并填写说明用途的 description
references/ 保存按需读取的参考资料,assets/ 保存模板或素材,scripts/ 保存脚本。仅在需要时创建这些可选目录,技能说明应明确何时使用其中的文件
旧本地入口(已废弃)
Agent(skills=..., skills_mode="local") 保持兼容,但已废弃;本地技能应迁移到 SkillToolset
沙箱模式仍可使用。运行以下示例前,配置
SKILL_SOURCE_ID、模型及代码沙箱要求的凭证和 Tool ID,并确认沙箱具备所需技能及网络权限:
sandbox_skills.py
动态加载技能
enable_dynamic_load_skills=True 用于 Agent.skills 旧入口,在每轮开始前重新读取来源并更新技能列表、说明和工具。即使初始 skills 为空,也会初始化对应工具集;共享同一个可变智能体进行并发调用时,应用需管理刷新与调用之间的并发
该开关不会热重载直接传给 SkillToolset(skills=[...]) 的本地对象。云端 registry 的按需加载也不依赖此开关。外部运行时与旧技能模式的兼容限制见运行时