程序包 io.agentscope.core.skill

类 SkillBox

java.lang.Object
io.agentscope.core.skill.SkillBox
public class SkillBox extends Object
Manages a collection of AgentSkill instances and exposes them as tools. Since 2.0.0, SkillBox is intended for internal use only; prefer skill repositories (AgentSkillRepository) for defining and loading skills.

  • 构造器详细资料

    • 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

    • getSkillPrompt

      public String getSkillPrompt(SkillFilter filter)
      Gets the skill system prompt filtered by the given SkillFilter.
      参数:
      filter - the filter deciding which skills to include (null treated as all)
      返回:
      The skill system prompt, or empty string if no skills pass the filter

    • 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

    • setSkillActive

      public void setSkillActive(String skillId, boolean active)
      Sets the activation state of a specific skill.

      When a skill is set to inactive, its associated tool group will be disabled in the underlying toolkit, preventing the agent from accessing its tools until it is activated again.

      This method automatically synchronizes the state change with the bound toolkit.

      Warning on Deactivation: Setting a skill to inactive only unbinds its associated tool group. It does not automatically remove the skill's context or prompt instructions from the agent's memory. This is a risky operation, as the agent might still attempt to invoke the inactive tool based on its retained memory context, leading to execution failures. For a complete and ideal deactivation, it is recommended to implement custom hooks to unbind both the tool group and its associated context from memory.

      参数:
      skillId - The ID of the skill to modify
      active - true to activate the skill, false to deactivate
      抛出:
      IllegalArgumentException - if skillId is null or the skill does not exist

    • 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

    • 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

    • setWorkDir

      public void setWorkDir(Path workDir)
      Sets a stable working directory for resource uploads and code execution. Callers can use this to share one workDir across multiple SkillBox instances (e.g. DynamicSkillMiddleware rebuilds the box every call, but the workDir lives for the agent's lifetime so uploadSkillFiles no longer mints a fresh agentscope-code-execution-* tempdir each round).
      参数:
      workDir - the directory under which skills/<skillId>/ subtrees are written; null (the default) preserves the legacy per-instance tempdir behavior

    • getSkillPromptProvider

      public AgentSkillPromptProvider getSkillPromptProvider()
      Exposes the skill prompt provider so callers (e.g. DynamicSkillMiddleware) can toggle codeExecutionEnable, swap the instruction template, or query the resolved uploadDir without re-walking the SkillBox internals.

    • 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.