程序包 io.agentscope.core.skill

类 SkillBox

java.lang.Object
io.agentscope.core.skill.SkillBox
所有已实现的接口:
StateModule
public class SkillBox extends Object implements StateModule

  • 构造器详细资料

    • SkillBox

      public SkillBox(Toolkit toolkit)

    • SkillBox

      public SkillBox(Toolkit toolkit, String instruction)
      Creates a SkillBox with a toolkit and custom skill prompt instruction.
      参数:
      toolkit - The toolkit to bind
      instruction - Custom instruction header (null or blank uses default)

  • 方法详细资料

    • getSkillPrompt

      public String getSkillPrompt()
      Gets the skill system prompt for registered skills.

      This prompt provides information about available skills that the agent can dynamically load and use during execution.

      返回:
      The skill system prompt, or empty string if no skills exist

    • setExposeAllSkillMetadata

      public void setExposeAllSkillMetadata(boolean exposeAllMetadata)
      Controls whether the skill prompt exposes all metadata fields or only the core fields.

      When disabled, only name, description, and skill-id are included in the skill prompt.

      参数:
      exposeAllMetadata - true to expose all metadata, false to expose only the core fields

    • registration

      public SkillBox.SkillRegistration registration()
      Create a fluent builder for registering skills with optional configuration.

      Example usage: 

      
 // Register skill
 skillBox.registration()
     .skill(skill)
     .apply();

 // Register skill with tool
 skillBox.registration()
     .skill(skill) // same reference skill will not be registered again
     .tool(toolObject)
     .apply();
      返回:
      A new ToolRegistration builder

    • bindToolkit

      public void bindToolkit(Toolkit toolkit)
      Binds a toolkit to the skill box.

      This method binds the toolkit to both the skill box and its internal skill tool factory. Since ReActAgent uses a deep copy of the Toolkit, rebinding is necessary to ensure the skill tool factory references the correct toolkit instance.

      参数:
      toolkit - The toolkit to bind to the skill box
      抛出:
      IllegalArgumentException - if the toolkit is null

    • syncToolGroupStates

      public void syncToolGroupStates()
      Synchronize tool group states based on skill activation status with a specific toolkit.

      Updates the toolkit's tool groups to reflect the current activation state of skills. Active skills will have their tool groups enabled, inactive skills will have their tool groups disabled.

    • isSkillActive

      public boolean isSkillActive(String skillId)
      Where the skill is active. If a skill is active, this means skill is being using by LLM. LLM use load tool activate the skill.
      参数:
      skillId -
      返回:
      true if the skill is active

    • registerSkill

      public void registerSkill(AgentSkill skill)
      Registers an agent skill.

      Skills can be dynamically loaded by agents using skill access tools. When a skill is loaded, its associated tools become available to the agent.

      Version Management:

      • First registration: Creates initial version of the skill
      • Subsequent registrations with same skill object (by reference): No new version created
      • Registrations with different skill object: Creates new version (snapshot)

      Usage example: 

      
 AgentSkill mySkill = new AgentSkill("my_skill", "Description", "Content", null);

 skillBox.registerSkill(mySkill);
 skillBox.registerSkill(my_skill); // do nothing
      参数:
      skill - The agent skill to register
      抛出:
      IllegalArgumentException - if skill is null

    • getAllSkillIds

      public Set<String> getAllSkillIds()
      Gets all skill IDs.
      返回:
      All skill IDs

    • getSkill

      public AgentSkill getSkill(String skillId)
      Gets a skill by ID (latest version).
      参数:
      skillId - The skill ID
      返回:
      The skill instance, or null if not found
      抛出:
      IllegalArgumentException - if skillId is null

    • removeSkill

      public void removeSkill(String skillId)
      Removes a skill completely.
      参数:
      skillId - The skill ID
      抛出:
      IllegalArgumentException - if skillId is null

    • exists

      public boolean exists(String skillId)
      Checks if a skill exists.
      参数:
      skillId - The skill ID
      返回:
      true if the skill exists, false otherwise
      抛出:
      IllegalArgumentException - if skillId is null

    • deactivateAllSkills

      public void deactivateAllSkills()
      Deactivates all skills.

      This method sets all registered skills to inactive state, which means their associated tool groups will not be available to the agent until the skills are accessed again via skill access tools.

      This is typically called at the start of each agent call to ensure a clean state.

    • registerSkillLoadTool

      public void registerSkillLoadTool()
      Registers skill access tools to the provided toolkit.

      This method registers the following tool:

      • load_skill_through_path - Load skill resources or SKILL.md content. When a resource is not found, it automatically returns a list of available resources with SKILL.md as the first item.
      抛出:
      IllegalArgumentException - if toolkit is null

    • codeExecution

      public SkillBox.CodeExecutionBuilder codeExecution()
      Create a fluent builder for configuring code execution with custom options.

      This is the recommended way to enable code execution capabilities for skills. The builder allows selective enabling of tools and customization of ShellCommandTool.

      Example usage: 

      
 // Simple - enable all tools with default configuration
 skillBox.codeExecution()
     .withShell()
     .withRead()
     .withWrite()
     .enable();

 // Custom shell tool with approval callback
 ShellCommandTool customShell = new ShellCommandTool(
     null,  // baseDir will be overridden
     Set.of("python3", "node", "npm"),
     command -> askUserApproval(command)
 );

 skillBox.codeExecution()
     .workDir("/path/to/workdir")
     .withShell(customShell)  // Clone with workDir
     .withRead()
     .withWrite()
     .enable();

 // Only enable read and write tools
 skillBox.codeExecution()
     .withRead()
     .withWrite()
     .enable();
      返回:
      A new CodeExecutionBuilder for configuration

    • setAutoUploadSkill

      public void setAutoUploadSkill(boolean autoUploadSkill)
      Sets whether skill files are automatically uploaded.
      参数:
      autoUploadSkill - true to automatically upload skill files

    • isAutoUploadSkill

      public boolean isAutoUploadSkill()
      Checks whether skill files are automatically uploaded.
      返回:
      true if skill files are automatically uploaded

    • getCodeExecutionWorkDir

      public Path getCodeExecutionWorkDir()
      Gets the working directory for code execution.
      返回:
      The working directory path, or null if using temporary directory

    • getUploadDir

      public Path getUploadDir()
      Gets the upload directory for skill files.
      返回:
      The upload directory path, or null if not configured

    • uploadSkillFiles

      public void uploadSkillFiles()
      Uploads skill files to the upload directory with the configured filter.

      Upload directory resolution:

      • If uploadDir is configured, use it.
      • Otherwise, use workDir/skills (workDir may be a temporary directory).

      If a file already exists, it will be overwritten.