kagent-adk 0.7.11__py3-none-any.whl

kagent/adk/tools/bash_tool.py

@@ -0,0 +1,74 @@
+"""Simplified bash tool for executing shell commands in skills context."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict
+
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types
+
+from kagent.skills import execute_command, get_bash_description, get_session_path
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class BashTool(BaseTool):
+    """Execute bash commands safely in the skills environment.
+
+    This tool uses the Anthropic Sandbox Runtime (srt) to execute commands with:
+    - Filesystem restrictions (controlled read/write access)
+    - Network restrictions (controlled domain access)
+    - Process isolation at the OS level
+
+    Use it for command-line operations like running scripts, installing packages, etc.
+    For file operations (read/write/edit), use the dedicated file tools instead.
+    """
+
+    def __init__(self, skills_directory: str | Path):
+        super().__init__(
+            name="bash",
+            description=get_bash_description(),
+        )
+        self.skills_directory = Path(skills_directory).resolve()
+        if not self.skills_directory.exists():
+            raise ValueError(f"Skills directory does not exist: {self.skills_directory}")
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "command": types.Schema(
+                        type=types.Type.STRING,
+                        description="Bash command to execute. Use && to chain commands.",
+                    ),
+                    "description": types.Schema(
+                        type=types.Type.STRING,
+                        description="Clear, concise description of what this command does (5-10 words)",
+                    ),
+                },
+                required=["command"],
+            ),
+        )
+
+    async def run_async(self, *, args: Dict[str, Any], tool_context: ToolContext) -> str:
+        """Execute a bash command safely using the Anthropic Sandbox Runtime."""
+        command = args.get("command", "").strip()
+        description = args.get("description", "")
+
+        if not command:
+            return "Error: No command provided"
+
+        try:
+            working_dir = get_session_path(session_id=tool_context.session.id)
+            result = await execute_command(command, working_dir)
+            logger.info(f"Executed bash command: {command}, description: {description}")
+            return result
+        except Exception as e:
+            error_msg = f"Error executing command '{command}': {e}"
+            logger.error(error_msg)
+            return error_msg

kagent/adk/tools/file_tools.py

@@ -0,0 +1,192 @@
+"""File operation tools for agent skills.
+
+This module provides Read, Write, and Edit tools that agents can use to work with
+files on the filesystem within the sandbox environment.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict
+
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types
+
+from kagent.skills import (
+    edit_file_content,
+    get_edit_file_description,
+    get_read_file_description,
+    get_session_path,
+    get_write_file_description,
+    read_file_content,
+    write_file_content,
+)
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class ReadFileTool(BaseTool):
+    """Read files with line numbers for precise editing."""
+
+    def __init__(self):
+        super().__init__(
+            name="read_file",
+            description=get_read_file_description(),
+        )
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "file_path": types.Schema(
+                        type=types.Type.STRING,
+                        description="Path to the file to read (absolute or relative to working directory)",
+                    ),
+                    "offset": types.Schema(
+                        type=types.Type.INTEGER,
+                        description="Optional line number to start reading from (1-indexed)",
+                    ),
+                    "limit": types.Schema(
+                        type=types.Type.INTEGER,
+                        description="Optional number of lines to read",
+                    ),
+                },
+                required=["file_path"],
+            ),
+        )
+
+    async def run_async(self, *, args: Dict[str, Any], tool_context: ToolContext) -> str:
+        """Read a file with line numbers."""
+        file_path_str = args.get("file_path", "").strip()
+        offset = args.get("offset")
+        limit = args.get("limit")
+
+        if not file_path_str:
+            return "Error: No file path provided"
+
+        try:
+            working_dir = get_session_path(session_id=tool_context.session.id)
+            path = Path(file_path_str)
+            if not path.is_absolute():
+                path = working_dir / path
+            path = path.resolve()
+
+            return read_file_content(path, offset, limit)
+        except (FileNotFoundError, IsADirectoryError, IOError) as e:
+            return f"Error reading file {file_path_str}: {e}"
+
+
+class WriteFileTool(BaseTool):
+    """Write content to files (overwrites existing files)."""
+
+    def __init__(self):
+        super().__init__(
+            name="write_file",
+            description=get_write_file_description(),
+        )
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "file_path": types.Schema(
+                        type=types.Type.STRING,
+                        description="Path to the file to write (absolute or relative to working directory)",
+                    ),
+                    "content": types.Schema(
+                        type=types.Type.STRING,
+                        description="Content to write to the file",
+                    ),
+                },
+                required=["file_path", "content"],
+            ),
+        )
+
+    async def run_async(self, *, args: Dict[str, Any], tool_context: ToolContext) -> str:
+        """Write content to a file."""
+        file_path_str = args.get("file_path", "").strip()
+        content = args.get("content", "")
+
+        if not file_path_str:
+            return "Error: No file path provided"
+
+        try:
+            working_dir = get_session_path(session_id=tool_context.session.id)
+            path = Path(file_path_str)
+            if not path.is_absolute():
+                path = working_dir / path
+            path = path.resolve()
+
+            return write_file_content(path, content)
+        except IOError as e:
+            error_msg = f"Error writing file {file_path_str}: {e}"
+            logger.error(error_msg)
+            return error_msg
+
+
+class EditFileTool(BaseTool):
+    """Edit files by replacing exact string matches."""
+
+    def __init__(self):
+        super().__init__(
+            name="edit_file",
+            description=get_edit_file_description(),
+        )
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "file_path": types.Schema(
+                        type=types.Type.STRING,
+                        description="Path to the file to edit (absolute or relative to working directory)",
+                    ),
+                    "old_string": types.Schema(
+                        type=types.Type.STRING,
+                        description="The exact text to replace (must exist in file)",
+                    ),
+                    "new_string": types.Schema(
+                        type=types.Type.STRING,
+                        description="The text to replace it with (must be different from old_string)",
+                    ),
+                    "replace_all": types.Schema(
+                        type=types.Type.BOOLEAN,
+                        description="Replace all occurrences (default: false, only replaces first occurrence)",
+                    ),
+                },
+                required=["file_path", "old_string", "new_string"],
+            ),
+        )
+
+    async def run_async(self, *, args: Dict[str, Any], tool_context: ToolContext) -> str:
+        """Edit a file by replacing old_string with new_string."""
+        file_path_str = args.get("file_path", "").strip()
+        old_string = args.get("old_string", "")
+        new_string = args.get("new_string", "")
+        replace_all = args.get("replace_all", False)
+
+        if not file_path_str:
+            return "Error: No file path provided"
+
+        try:
+            working_dir = get_session_path(session_id=tool_context.session.id)
+            path = Path(file_path_str)
+            if not path.is_absolute():
+                path = working_dir / path
+            path = path.resolve()
+
+            return edit_file_content(path, old_string, new_string, replace_all)
+        except (FileNotFoundError, IsADirectoryError, ValueError, IOError) as e:
+            error_msg = f"Error editing file {file_path_str}: {e}"
+            logger.error(error_msg)
+            return error_msg

kagent/adk/tools/skill_tool.py

@@ -0,0 +1,104 @@
+"""Tool for discovering and loading skills."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict
+
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types
+
+from kagent.skills import (
+    discover_skills,
+    generate_skills_tool_description,
+    load_skill_content,
+)
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class SkillsTool(BaseTool):
+    """Discover and load skill instructions.
+
+    This tool dynamically discovers available skills and embeds their metadata in the
+    tool description. Agent invokes a skill by name to load its full instructions.
+    """
+
+    def __init__(self, skills_directory: str | Path):
+        self.skills_directory = Path(skills_directory).resolve()
+        if not self.skills_directory.exists():
+            raise ValueError(f"Skills directory does not exist: {self.skills_directory}")
+
+        self._skill_cache: Dict[str, str] = {}
+
+        # Generate description with available skills embedded
+        description = self._generate_description_with_skills()
+
+        super().__init__(
+            name="skills",
+            description=description,
+        )
+
+    def _generate_description_with_skills(self) -> str:
+        """Generate tool description with available skills embedded."""
+        skills = discover_skills(self.skills_directory)
+        return generate_skills_tool_description(skills)
+
+    def _get_declaration(self) -> types.FunctionDeclaration:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "command": types.Schema(
+                        type=types.Type.STRING,
+                        description='The skill name (no arguments). E.g., "data-analysis" or "pdf-processing"',
+                    ),
+                },
+                required=["command"],
+            ),
+        )
+
+    async def run_async(self, *, args: Dict[str, Any], tool_context: ToolContext) -> str:
+        """Execute skill loading by name."""
+        skill_name = args.get("command", "").strip()
+
+        if not skill_name:
+            return "Error: No skill name provided"
+
+        return self._invoke_skill(skill_name)
+
+    def _invoke_skill(self, skill_name: str) -> str:
+        """Load and return the full content of a skill."""
+        # Check cache first
+        if skill_name in self._skill_cache:
+            return self._skill_cache[skill_name]
+
+        try:
+            content = load_skill_content(self.skills_directory, skill_name)
+            formatted_content = self._format_skill_content(skill_name, content)
+
+            # Cache the formatted content
+            self._skill_cache[skill_name] = formatted_content
+
+            return formatted_content
+        except (FileNotFoundError, IOError) as e:
+            logger.error(f"Failed to load skill {skill_name}: {e}")
+            return f"Error loading skill '{skill_name}': {e}"
+        except Exception as e:
+            logger.error(f"An unexpected error occurred while loading skill {skill_name}: {e}")
+            return f"An unexpected error occurred while loading skill '{skill_name}': {e}"
+
+    def _format_skill_content(self, skill_name: str, content: str) -> str:
+        """Format skill content for display to the agent."""
+        header = (
+            f'<command-message>The "{skill_name}" skill is loading</command-message>\n\n'
+            f"Base directory for this skill: {self.skills_directory}/{skill_name}\n\n"
+        )
+        footer = (
+            "\n\n---\n"
+            "The skill has been loaded. Follow the instructions above and use the bash tool to execute commands."
+        )
+        return header + content + footer

kagent/adk/tools/skills_plugin.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from google.adk.agents import BaseAgent, LlmAgent
+
+from ..tools import BashTool, EditFileTool, ReadFileTool, WriteFileTool
+from .skill_tool import SkillsTool
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+def add_skills_tool_to_agent(skills_directory: str | Path, agent: BaseAgent) -> None:
+    """Utility function to add Skills and Bash tools to a given agent.
+
+    Args:
+      agent: The LlmAgent instance to which the tools will be added.
+      skills_directory: Path to directory containing skill folders.
+    """
+
+    if not isinstance(agent, LlmAgent):
+        return
+
+    skills_directory = Path(skills_directory)
+    existing_tool_names = {getattr(t, "name", None) for t in agent.tools}
+
+    # Add SkillsTool if not already present
+    if "skills" not in existing_tool_names:
+        agent.tools.append(SkillsTool(skills_directory))
+        logger.debug(f"Added skills invoke tool to agent: {agent.name}")
+
+    # Add BashTool if not already present
+    if "bash" not in existing_tool_names:
+        agent.tools.append(BashTool(skills_directory))
+        logger.debug(f"Added bash tool to agent: {agent.name}")
+
+    if "read_file" not in existing_tool_names:
+        agent.tools.append(ReadFileTool())
+        logger.debug(f"Added read file tool to agent: {agent.name}")
+
+    if "write_file" not in existing_tool_names:
+        agent.tools.append(WriteFileTool())
+        logger.debug(f"Added write file tool to agent: {agent.name}")
+
+    if "edit_file" not in existing_tool_names:
+        agent.tools.append(EditFileTool())
+        logger.debug(f"Added edit file tool to agent: {agent.name}")

kagent/adk/tools/skills_toolset.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import List, Optional
+
+try:
+    from typing_extensions import override
+except ImportError:
+    from typing import override
+
+from google.adk.agents.readonly_context import ReadonlyContext
+from google.adk.tools import BaseTool
+from google.adk.tools.base_toolset import BaseToolset
+
+from ..tools import BashTool, EditFileTool, ReadFileTool, WriteFileTool
+from .skill_tool import SkillsTool
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class SkillsToolset(BaseToolset):
+    """Toolset that provides Skills functionality for domain expertise execution.
+
+    This toolset provides skills access through specialized tools:
+    1. SkillsTool - Discover and load skill instructions
+    2. ReadFileTool - Read files with line numbers
+    3. WriteFileTool - Write/create files
+    4. EditFileTool - Edit files with precise replacements
+    5. BashTool - Execute shell commands
+
+    Skills provide specialized domain knowledge and scripts that the agent can use
+    to solve complex tasks. The toolset enables discovery of available skills,
+    file manipulation, and command execution.
+
+    Note: For file upload/download, use the ArtifactsToolset separately.
+    """
+
+    def __init__(self, skills_directory: str | Path):
+        """Initialize the skills toolset.
+
+        Args:
+          skills_directory: Path to directory containing skill folders.
+        """
+        super().__init__()
+        self.skills_directory = Path(skills_directory)
+
+        # Create skills tools
+        self.skills_tool = SkillsTool(skills_directory)
+        self.read_file_tool = ReadFileTool()
+        self.write_file_tool = WriteFileTool()
+        self.edit_file_tool = EditFileTool()
+        self.bash_tool = BashTool(skills_directory)
+
+    @override
+    async def get_tools(self, readonly_context: Optional[ReadonlyContext] = None) -> List[BaseTool]:
+        """Get all skills tools.
+
+        Returns:
+          List containing all skills tools: skills, read, write, edit, and bash.
+        """
+        return [
+            self.skills_tool,
+            self.read_file_tool,
+            self.write_file_tool,
+            self.edit_file_tool,
+            self.bash_tool,
+        ]