kagent-adk 0.7.0__tar.gz → 0.7.2__tar.gz

{kagent_adk-0.7.0 → kagent_adk-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kagent-adk
-Version: 0.7.0
+Version: 0.7.2
 Summary: kagent-adk is an sdk for integrating adk agents with kagent
 Requires-Python: >=3.11.0
 Requires-Dist: a2a-sdk>=0.3.1

{kagent_adk-0.7.0 → kagent_adk-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "kagent-adk"
-version = "0.7.0"
+version = "0.7.2"
 description = "kagent-adk is an sdk for integrating adk agents with kagent"
 readme = "README.md"
 requires-python = ">=3.11.0"

{kagent_adk-0.7.0 → kagent_adk-0.7.2}/src/kagent/adk/_a2a.py

@@ -2,7 +2,7 @@
 import faulthandler
 import logging
 import os
-from typing import Callable
+from typing import Callable, List
 
 import httpx
 from a2a.server.apps import A2AFastAPIApplication
@@ -14,8 +14,11 @@ from fastapi import FastAPI, Request
 from fastapi.responses import PlainTextResponse
 from google.adk.agents import BaseAgent
 from google.adk.apps import App
+from google.adk.plugins import BasePlugin
 from google.adk.runners import Runner
 from google.adk.sessions import InMemorySessionService
+from google.adk.artifacts import InMemoryArtifactService
+
 from google.genai import types
 
 from kagent.core.a2a import KAgentRequestContextBuilder, KAgentTaskStore
@@ -64,11 +67,13 @@ class KAgentApp:
         agent_card: AgentCard,
         kagent_url: str,
         app_name: str,
+        plugins: List[BasePlugin] = None,
     ):
         self.root_agent = root_agent
         self.kagent_url = kagent_url
         self.app_name = app_name
         self.agent_card = agent_card
+        self.plugins = plugins if plugins is not None else []
 
     def build(self) -> FastAPI:
         token_service = KAgentTokenService(self.app_name)
@@ -77,17 +82,17 @@ class KAgentApp:
         )
         session_service = KAgentSessionService(http_client)
 
-        plugins = []
         if sts_well_known_uri:
             sts_integration = ADKSTSIntegration(sts_well_known_uri)
-            plugins.append(ADKTokenPropagationPlugin(sts_integration))
+            self.plugins.append(ADKTokenPropagationPlugin(sts_integration))
 
-        adk_app = App(name=self.app_name, root_agent=self.root_agent, plugins=plugins)
+        adk_app = App(name=self.app_name, root_agent=self.root_agent, plugins=self.plugins)
 
         def create_runner() -> Runner:
             return Runner(
                 app=adk_app,
                 session_service=session_service,
+                artifact_service=InMemoryArtifactService(),
             )
 
         agent_executor = A2aAgentExecutor(

{kagent_adk-0.7.0 → kagent_adk-0.7.2}/src/kagent/adk/_agent_executor.py

@@ -33,7 +33,7 @@ from kagent.core.a2a import TaskResultAggregator, get_kagent_metadata_key
 from .converters.event_converter import convert_event_to_a2a_events
 from .converters.request_converter import convert_a2a_request_to_adk_run_args
 
-logger = logging.getLogger("google_adk." + __name__)
+logger = logging.getLogger("kagent_adk." + __name__)
 
 
 class A2aAgentExecutorConfig(BaseModel):

{kagent_adk-0.7.0 → kagent_adk-0.7.2}/src/kagent/adk/cli.py

@@ -14,6 +14,7 @@ from kagent.core import KAgentConfig, configure_tracing
 from . import AgentConfig, KAgentApp
 
 logger = logging.getLogger(__name__)
+logging.getLogger("google_adk.google.adk.tools.base_authenticated_tool").setLevel(logging.ERROR)
 
 app = typer.Typer()
 

kagent_adk-0.7.2/src/kagent/adk/skills/README.md

@@ -0,0 +1,217 @@
+# ADK Skills
+
+Filesystem-based skills with progressive disclosure and two-tool architecture.
+
+---
+
+## Overview
+
+Skills enable agents to specialize in domain expertise without bloating the main context. The **two-tool pattern** separates concerns:
+
+- **SkillsTool** - Loads skill instructions
+- **BashTool** - Executes commands
+- **Semantic clarity** leads to better LLM reasoning
+
+### Skill Structure
+
+```text
+skills/
+├── data-analysis/
+│   ├── SKILL.md        # Metadata + instructions (YAML frontmatter)
+│   └── scripts/
+│       └── analyze.py
+└── pdf-processing/
+    ├── SKILL.md
+    └── scripts/
+```
+
+**SKILL.md:**
+
+```markdown
+---
+name: data-analysis
+description: Analyze CSV/Excel files
+---
+
+# Data Analysis
+
+...instructions...
+```
+
+---
+
+## Quick Start
+
+**Two-Tool Pattern (Recommended):**
+
+```python
+from kagent.adk.skills import SkillsTool, BashTool, StageArtifactsTool
+
+agent = Agent(
+    tools=[
+        SkillsTool(skills_directory="./skills"),
+        BashTool(skills_directory="./skills"),
+        StageArtifactsTool(skills_directory="./skills"),
+    ]
+)
+```
+
+**With Plugin (Multi-Agent Apps):**
+
+```python
+from kagent.adk.skills import SkillsPlugin
+
+app = App(root_agent=agent, plugins=[SkillsPlugin(skills_directory="./skills")])
+```
+
+**Legacy Single-Tool (Backward Compat):**
+
+```python
+from kagent.adk.skills import SkillsShellTool
+
+agent = Agent(tools=[SkillsShellTool(skills_directory="./skills")])
+```
+
+---
+
+## How It Works
+
+### Two-Tool Workflow
+
+```mermaid
+sequenceDiagram
+    participant A as Agent
+    participant S as SkillsTool
+    participant B as BashTool
+
+    A->>S: skills(command='data-analysis')
+    S-->>A: Full SKILL.md + base path
+    A->>B: bash("cd skills/data-analysis && python scripts/analyze.py file.csv")
+    B-->>A: Results
+```
+
+**Three Phases:**
+
+1. **Discovery** - Agent sees available skills in tool description
+2. **Loading** - Invoke skill with `command='skill-name'` → returns full SKILL.md
+3. **Execution** - Use BashTool with instructions from SKILL.md
+
+---
+
+## Architecture
+
+```mermaid
+graph LR
+    Agent[Agent] -->|Load<br/>skill details| SkillsTool["SkillsTool<br/>(Discovery)"]
+    Agent -->|Execute<br/>commands| BashTool["BashTool<br/>(Execution)"]
+    SkillsTool -->|Embedded in<br/>description| Skills["Available<br/>Skills List"]
+```
+
+| Tool                   | Purpose             | Input                  | Output                    |
+| ---------------------- | ------------------- | ---------------------- | ------------------------- |
+| **SkillsTool**         | Load skill metadata | `command='skill-name'` | Full SKILL.md + base path |
+| **BashTool**           | Execute safely      | Command string         | Script output             |
+| **StageArtifactsTool** | Stage uploads       | Artifact names         | File paths in `uploads/`  |
+
+---
+
+## File Handling
+
+User uploads → Artifact → Stage → Execute:
+
+```python
+# 1. Stage uploaded file
+stage_artifacts(artifact_names=["artifact_123"])
+
+# 2. Use in skill script
+bash("cd skills/data-analysis && python scripts/analyze.py uploads/artifact_123")
+```
+
+---
+
+## Security
+
+**SkillsTool:**
+
+- ✅ Read-only (no execution)
+- ✅ Validates skill existence
+- ✅ Caches results
+
+**BashTool:**
+
+- ✅ Whitelisted commands only (`ls`, `cat`, `python`, `pip`, etc.)
+- ✅ No destructive ops (`rm`, `mv`, `chmod` blocked)
+- ✅ Directory restrictions (no `..`)
+- ✅ 30-second timeout
+- ✅ Subprocess isolation
+
+---
+
+## Components
+
+| File                      | Purpose                      |
+| ------------------------- | ---------------------------- |
+| `skills_invoke_tool.py`   | Discovery & loading          |
+| `bash_tool.py`            | Command execution            |
+| `stage_artifacts_tool.py` | File staging                 |
+| `skills_plugin.py`        | Auto-registration (optional) |
+| `skills_shell_tool.py`    | Legacy all-in-one            |
+
+---
+
+## Examples
+
+### Example 1: Data Analysis
+
+```python
+# Agent loads skill
+agent.invoke(tools=[
+    SkillsTool(skills_directory="./skills"),
+    BashTool(skills_directory="./skills"),
+], prompt="Analyze this CSV file")
+
+# Agent flow:
+# 1. Calls: skills(command='data-analysis')
+# 2. Gets: Full SKILL.md with instructions
+# 3. Calls: bash("cd skills/data-analysis && python scripts/analyze.py file.csv")
+# 4. Returns: Analysis results
+```
+
+### Example 2: Multi-Agent App
+
+```python
+# Register skills on all agents
+app = App(
+    root_agent=agent,
+    plugins=[SkillsPlugin(skills_directory="./skills")]
+)
+```
+
+---
+
+## Comparison with Claude
+
+ADK follows Claude's two-tool pattern exactly:
+
+| Aspect         | Claude              | ADK                    |
+| -------------- | ------------------- | ---------------------- |
+| Discovery tool | Skills tool         | SkillsTool ✅          |
+| Execution tool | Bash tool           | BashTool ✅            |
+| Parameter      | `command`           | `command` ✅           |
+| Pattern        | Two-tool separation | Two-tool separation ✅ |
+
+---
+
+## What Changed
+
+**Before:** Single `SkillsShellTool` (all-in-one)  
+**Now:** Two-tool architecture (discovery + execution)
+
+| Feature                | Before    | After             |
+| ---------------------- | --------- | ----------------- |
+| Semantic clarity       | Mixed     | Separated ✅      |
+| LLM reasoning          | Implicit  | Explicit ✅       |
+| Progressive disclosure | Guideline | Enforced ✅       |
+| Industry alignment     | Custom    | Claude pattern ✅ |
+
+All previous code still works (backward compatible via `SkillsShellTool`).

kagent_adk-0.7.2/src/kagent/adk/skills/__init__.py

@@ -0,0 +1,29 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .bash_tool import BashTool
+from .skill_system_prompt import generate_shell_skills_system_prompt
+from .skill_tool import SkillsTool
+from .skills_plugin import SkillsPlugin
+from .skills_toolset import SkillsToolset
+from .stage_artifacts_tool import StageArtifactsTool
+
+__all__ = [
+    "BashTool",
+    "SkillsTool",
+    "SkillsPlugin",
+    "SkillsToolset",
+    "StageArtifactsTool",
+    "generate_shell_skills_system_prompt",
+]

kagent_adk-0.7.2/src/kagent/adk/skills/bash_tool.py

@@ -0,0 +1,244 @@
+"""Simplified bash tool for executing shell commands in skills context."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import shlex
+from pathlib import Path
+from typing import Any, Dict, List, Set, Union
+
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types
+
+from .stage_artifacts_tool import get_session_staging_path
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class BashTool(BaseTool):
+    """Execute bash commands safely in the skills environment.
+
+    This tool is for terminal operations and script execution. Use it after loading
+    skill instructions with the skills tool.
+    """
+
+    DANGEROUS_COMMANDS: Set[str] = {
+        "rm",
+        "rmdir",
+        "mv",
+        "cp",
+        "chmod",
+        "chown",
+        "sudo",
+        "su",
+        "kill",
+        "reboot",
+        "shutdown",
+        "dd",
+        "mount",
+        "umount",
+        "alias",
+        "export",
+        "source",
+        ".",
+        "eval",
+        "exec",
+    }
+
+    def __init__(self, skills_directory: str | Path):
+        super().__init__(
+            name="bash",
+            description=(
+                "Execute bash commands in the skills environment.\n\n"
+                "Use this tool to:\n"
+                "- Execute Python scripts from files (e.g., 'python scripts/script.py')\n"
+                "- Install dependencies (e.g., 'pip install -r requirements.txt')\n"
+                "- Navigate and inspect files (e.g., 'ls', 'cat file.txt')\n"
+                "- Run shell commands with relative or absolute paths\n\n"
+                "Important:\n"
+                "- Always load skill instructions first using the skills tool\n"
+                "- Execute scripts from within their skill directory using 'cd skills/SKILL_NAME && ...'\n"
+                "- For Python code execution: ALWAYS write code to a file first, then run it with 'python file.py'\n"
+                "- Never use 'python -c \"code\"' - write to file first instead\n"
+                "- Quote paths with spaces (e.g., 'cd \"path with spaces\"')\n"
+                "- pip install commands may take longer (120s timeout)\n"
+                "- Python scripts have 60s timeout, other commands 30s\n\n"
+                "Security:\n"
+                "- Only whitelisted commands allowed (ls, cat, python, pip, etc.)\n"
+                "- No destructive operations (rm, mv, chown, etc. blocked)\n"
+                "- The sandbox environment provides additional isolation"
+            ),
+        )
+        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."""
+        command = args.get("command", "").strip()
+        description = args.get("description", "")
+
+        if not command:
+            return "Error: No command provided"
+
+        if description:
+            logger.info(f"Executing: {description}")
+
+        try:
+            parsed_commands = self._parse_and_validate_command(command)
+            result = await self._execute_command_safely(parsed_commands, tool_context)
+            logger.info(f"Executed bash command: {command}")
+            return result
+        except Exception as e:
+            error_msg = f"Error executing command '{command}': {e}"
+            logger.error(error_msg)
+            return error_msg
+
+    def _parse_and_validate_command(self, command: str) -> List[List[str]]:
+        """Parse and validate command for security."""
+        if "&&" in command:
+            parts = [part.strip() for part in command.split("&&")]
+        else:
+            parts = [command]
+
+        parsed_parts = []
+        for part in parts:
+            parsed_part = shlex.split(part)
+            validation_error = self._validate_command_part(parsed_part)
+            if validation_error:
+                raise ValueError(validation_error)
+            parsed_parts.append(parsed_part)
+        return parsed_parts
+
+    def _validate_command_part(self, command_parts: List[str]) -> Union[str, None]:
+        """Validate a single command part for security."""
+        if not command_parts:
+            return "Empty command"
+
+        base_command = command_parts[0]
+
+        if base_command in self.DANGEROUS_COMMANDS:
+            return f"Command '{base_command}' is not allowed for security reasons."
+
+        return None
+
+    async def _execute_command_safely(self, parsed_commands: List[List[str]], tool_context: ToolContext) -> str:
+        """Execute parsed commands in the sandboxed environment."""
+        staging_root = get_session_staging_path(
+            session_id=tool_context.session.id,
+            app_name=tool_context._invocation_context.app_name,
+            skills_directory=self.skills_directory,
+        )
+        original_cwd = os.getcwd()
+        output_parts = []
+
+        try:
+            os.chdir(staging_root)
+
+            for i, command_parts in enumerate(parsed_commands):
+                if i > 0:
+                    output_parts.append(f"\n--- Command {i + 1} ---")
+
+                if command_parts[0] == "cd":
+                    if len(command_parts) > 1:
+                        target_path = command_parts[1]
+                        try:
+                            # Resolve the path relative to current directory
+                            target_abs = (Path(os.getcwd()) / target_path).resolve()
+                            os.chdir(target_abs)
+                            current_cwd = os.getcwd()
+                            output_parts.append(f"Changed directory to {target_path}")
+                            logger.info(f"Changed to {target_path}. Current cwd: {current_cwd}")
+                        except (OSError, RuntimeError) as e:
+                            output_parts.append(f"Error changing directory: {e}")
+                            logger.error(f"Failed to cd to {target_path}: {e}")
+                    continue
+
+                # Determine timeout based on command type
+                timeout = self._get_command_timeout(command_parts)
+                current_cwd = os.getcwd()
+
+                try:
+                    process = await asyncio.create_subprocess_exec(
+                        *command_parts,
+                        stdout=asyncio.subprocess.PIPE,
+                        stderr=asyncio.subprocess.PIPE,
+                        cwd=current_cwd,
+                    )
+                    try:
+                        stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
+                    except asyncio.TimeoutError:
+                        process.kill()
+                        await process.wait()
+                        error_msg = f"Command '{' '.join(command_parts)}' timed out after {timeout}s"
+                        output_parts.append(f"Error: {error_msg}")
+                        logger.error(error_msg)
+                        break
+
+                    stdout_str = stdout.decode("utf-8", errors="replace") if stdout else ""
+                    stderr_str = stderr.decode("utf-8", errors="replace") if stderr else ""
+
+                    if process.returncode != 0:
+                        output = stderr_str or stdout_str
+                        error_output = f"Command failed with exit code {process.returncode}:\n{output}"
+                        output_parts.append(error_output)
+                        # Don't break on pip errors, continue to allow retry
+                        if command_parts[0] not in ("pip", "pip3"):
+                            break
+                    else:
+                        # Combine stdout and stderr for complete output
+                        combined_output = stdout_str
+                        if stderr_str and "WARNING" not in stderr_str:
+                            combined_output += f"\n{stderr_str}"
+                        output_parts.append(
+                            combined_output.strip() if combined_output.strip() else "Command completed successfully."
+                        )
+                except Exception as e:
+                    error_msg = f"Error executing '{' '.join(command_parts)}': {str(e)}"
+                    output_parts.append(error_msg)
+                    logger.error(error_msg)
+                    break
+
+            return "\n".join(output_parts)
+
+        except Exception as e:
+            return f"Error executing command: {e}"
+        finally:
+            os.chdir(original_cwd)
+
+    def _get_command_timeout(self, command_parts: List[str]) -> int:
+        """Determine appropriate timeout for command type."""
+        if not command_parts:
+            return 30
+
+        base_command = command_parts[0]
+
+        # Extended timeouts for package management operations
+        if base_command in ("pip", "pip3"):
+            return 120  # 2 minutes for pip operations
+        elif base_command in ("python", "python3"):
+            return 60  # 1 minute for python scripts
+        else:
+            return 30  # 30 seconds for other commands

kagent_adk-0.7.2/src/kagent/adk/skills/skill_system_prompt.py

@@ -0,0 +1,165 @@
+"""Optional comprehensive system prompt for skills-focused agents.
+
+This module provides an enhanced, verbose system prompt for agents that are
+heavily focused on skills usage. It is NOT required for basic skills functionality,
+as the SkillsShellTool already includes sufficient guidance in its description.
+
+Use this when:
+- You want extremely detailed procedural guidance for the agent
+- The agent's primary purpose is to work with skills
+- You want to emphasize specific workflows or best practices
+
+For most use cases, simply adding SkillsShellTool to your agent is sufficient.
+The tool's description already includes all necessary guidance for skills usage.
+
+Example usage:
+    # Basic usage (recommended for most cases):
+    agent = Agent(
+        tools=[SkillsShellTool(skills_directory="./skills")]
+    )
+
+    # Enhanced usage (for skills-focused agents):
+    agent = Agent(
+        instruction=generate_shell_skills_system_prompt("./skills"),
+        tools=[SkillsShellTool(skills_directory="./skills")]
+    )
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from google.adk.agents.readonly_context import ReadonlyContext
+
+
+def generate_shell_skills_system_prompt(
+    skills_directory: str | Path, readonly_context: Optional[ReadonlyContext] = None
+) -> str:
+    """Generate a comprehensive, verbose system prompt for shell-based skills usage.
+
+    This function provides an enhanced system prompt with detailed procedural guidance
+    for agents that heavily focus on skills usage. It supplements the guidance already
+    present in the SkillsShellTool's description.
+
+    Note: This is optional. The SkillsShellTool already includes sufficient guidance
+    in its description for most use cases.
+
+    Args:
+        skills_directory: Path to directory containing skill folders (currently unused,
+                         kept for API compatibility)
+        readonly_context: Optional context (currently unused, kept for API compatibility)
+
+    Returns:
+        A comprehensive system prompt string with detailed skills usage guidance.
+    """
+    prompt = """# Skills System - Two-Tool Architecture
+
+You have access to specialized skills through two complementary tools: the `skills` tool and the `bash` tool.
+
+## Overview
+
+Skills provide specialized domain expertise through instructions, scripts, and reference materials. You access them using a two-phase approach:
+1. **Discovery & Loading**: Use the `skills` tool to invoke a skill and load its instructions
+2. **Execution**: Use the `bash` tool to execute commands based on the skill's guidance
+
+## Workflow for User-Uploaded Files
+
+When a user uploads a file, it is saved as an artifact. To use it with skills, follow this two-step process:
+
+1.  **Stage the Artifact:** Use the `stage_artifacts` tool to copy the file from the artifact store to your local `uploads/` directory. The system will tell you the artifact name (e.g., `artifact_...`).
+    ```
+    stage_artifacts(artifact_names=["artifact_..."])
+    ```
+2.  **Use the Staged File:** After staging, the tool will return the new path (e.g., `uploads/artifact_...`). You can now use this path in your `bash` commands.
+    ```
+    bash("python skills/data-analysis/scripts/data_quality_check.py uploads/artifact_...")
+    ```
+
+## Using the Skills Tool
+
+The `skills` tool discovers and loads skill instructions:
+
+### Discovery
+Available skills are listed in the tool's description under `<available_skills>`. Review these to find relevant capabilities.
+
+### Loading a Skill
+Invoke a skill by name to load its full SKILL.md instructions:
+- `skills(command="data-analysis")` - Load data analysis skill
+- `skills(command="pdf-processing")` - Load PDF processing skill
+
+When you invoke a skill, you'll see: `<command-message>The "skill-name" skill is loading</command-message>` followed by the skill's complete instructions.
+
+## Using the Bash Tool
+
+The `bash` tool executes commands in a sandboxed environment. Use it after loading a skill's instructions:
+
+### Common Commands
+- `bash("cd skills/SKILL_NAME && python scripts/SCRIPT.py arg1")` - Execute a skill's script
+- `bash("pip install -r skills/SKILL_NAME/requirements.txt")` - Install dependencies
+- `bash("ls skills/SKILL_NAME")` - List skill files
+- `bash("cat skills/SKILL_NAME/reference.md")` - Read additional documentation
+
+### Command Chaining
+Chain multiple commands with `&&`:
+```
+bash("cd skills/data-analysis && pip install -r requirements.txt && python scripts/analyze.py data.csv")
+```
+
+## Progressive Disclosure Strategy
+
+1.  **Review Available Skills**: Check the `<available_skills>` section in the skills tool description to find relevant capabilities
+2.  **Invoke Relevant Skill**: Use `skills(command="skill-name")` to load full instructions
+3.  **Follow Instructions**: Read the loaded SKILL.md carefully
+4.  **Execute with Bash**: Use `bash` tool to run commands, install dependencies, and execute scripts as instructed
+
+## Best Practices
+
+### 1. **Dependency Management**
+- **Before using a script**, check for a `requirements.txt` file
+- Install dependencies with: `bash("pip install -r skills/SKILL_NAME/requirements.txt")`
+
+### 2. **Efficient Workflow**
+- Only invoke skills when needed for the task
+- Don't invoke a skill that's already loaded in the conversation
+- Read skill instructions carefully before executing
+
+### 3. **Script Usage**
+- **Always** execute scripts from within their skill directory: `bash("cd skills/SKILL_NAME && python scripts/SCRIPT.py")`
+- Check script documentation in the SKILL.md before running
+- Quote paths with spaces: `bash("cd \"path with spaces\" && python script.py")`
+
+### 4. **Error Handling**
+- If a bash command fails, read the error message carefully
+- Check that dependencies are installed
+- Verify file paths are correct
+- Ensure you're in the correct directory
+
+## Security and Safety
+
+Both tools are sandboxed for safety:
+
+**Skills Tool:**
+- Read-only access to skill files
+- No execution capability
+- Only loads documented skills
+
+**Bash Tool:**
+- **Safe Commands Only**: Only whitelisted commands like `ls`, `cat`, `grep`, `pip`, and `python` are allowed
+- **No Destructive Changes**: Commands like `rm`, `mv`, or `chmod` are blocked
+- **Directory Restrictions**: You cannot access files outside of the skills directory
+- **Timeout Protection**: Commands limited to 30 seconds
+
+## Example Workflow
+
+User asks: "Analyze this CSV file"
+
+1. **Review Skills**: Check `<available_skills>` in skills tool → See "data-analysis" skill
+2. **Invoke Skill**: `skills(command="data-analysis")` → Receive full instructions
+3. **Stage File**: `stage_artifacts(artifact_names=["artifact_123"])` → File at `uploads/artifact_123`
+4. **Install Deps**: `bash("pip install -r skills/data-analysis/requirements.txt")` → Dependencies installed
+5. **Execute Script**: `bash("cd skills/data-analysis && python scripts/analyze.py uploads/artifact_123")` → Get results
+6. **Present Results**: Share analysis with user
+
+Remember: Skills are your specialized knowledge repositories. Use the skills tool to discover and load them, then use the bash tool to execute their instructions."""
+    return prompt

kagent_adk-0.7.2/src/kagent/adk/skills/skill_tool.py

@@ -0,0 +1,202 @@
+"""Tool for discovering and loading skills."""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import yaml
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types
+from pydantic import BaseModel
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class Skill(BaseModel):
+    """Represents the metadata for a skill.
+
+    This is a simple data container used during the initial skill discovery
+    phase to hold the information parsed from a skill's SKILL.md frontmatter.
+    """
+
+    name: str
+    """The unique name/identifier of the skill."""
+
+    description: str
+    """A description of what the skill does and when to use it."""
+
+    license: Optional[str] = None
+    """Optional license information for the skill."""
+
+
+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."""
+        base_description = (
+            "Execute a skill within the main conversation\n\n"
+            "<skills_instructions>\n"
+            "When users ask you to perform tasks, check if any of the available skills below can help "
+            "complete the task more effectively. Skills provide specialized capabilities and domain knowledge.\n\n"
+            "How to use skills:\n"
+            "- Invoke skills using this tool with the skill name only (no arguments)\n"
+            "- When you invoke a skill, the skill's full SKILL.md will load with detailed instructions\n"
+            "- Follow the skill's instructions and use the bash tool to execute commands\n"
+            "- Examples:\n"
+            '  - command: "data-analysis" - invoke the data-analysis skill\n'
+            '  - command: "pdf-processing" - invoke the pdf-processing skill\n\n'
+            "Important:\n"
+            "- Only use skills listed in <available_skills> below\n"
+            "- Do not invoke a skill that is already loaded in the conversation\n"
+            "- After loading a skill, use the bash tool for execution\n"
+            "</skills_instructions>\n\n"
+        )
+
+        # Discover and append available skills
+        skills_xml = self._discover_skills()
+        return base_description + skills_xml
+
+    def _discover_skills(self) -> str:
+        """Discover available skills and format as XML."""
+        if not self.skills_directory.exists():
+            return "<available_skills>\n<!-- No skills directory found -->\n</available_skills>\n"
+
+        skills_entries = []
+        for skill_dir in sorted(self.skills_directory.iterdir()):
+            if not skill_dir.is_dir():
+                continue
+
+            skill_file = skill_dir / "SKILL.md"
+            if not skill_file.exists():
+                continue
+
+            try:
+                metadata = self._parse_skill_metadata(skill_file)
+                if metadata:
+                    skill_xml = (
+                        "<skill>\n"
+                        f"<name>{metadata['name']}</name>\n"
+                        f"<description>{metadata['description']}</description>\n"
+                        "</skill>"
+                    )
+                    skills_entries.append(skill_xml)
+            except Exception as e:
+                logger.error(f"Failed to parse skill {skill_dir.name}: {e}")
+
+        if not skills_entries:
+            return "<available_skills>\n<!-- No skills found -->\n</available_skills>\n"
+
+        return "<available_skills>\n" + "\n".join(skills_entries) + "\n</available_skills>\n"
+
+    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]
+
+        # Find skill directory
+        skill_dir = self.skills_directory / skill_name
+        if not skill_dir.exists() or not skill_dir.is_dir():
+            return f"Error: Skill '{skill_name}' not found. Check the available skills list in the tool description."
+
+        skill_file = skill_dir / "SKILL.md"
+        if not skill_file.exists():
+            return f"Error: Skill '{skill_name}' has no SKILL.md file."
+
+        try:
+            with open(skill_file, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            formatted_content = self._format_skill_content(skill_name, content)
+
+            # Cache the formatted content
+            self._skill_cache[skill_name] = formatted_content
+
+            return formatted_content
+
+        except Exception as e:
+            logger.error(f"Failed to load skill {skill_name}: {e}")
+            return f"Error loading skill '{skill_name}': {e}"
+
+    def _parse_skill_metadata(self, skill_file: Path) -> Dict[str, str] | None:
+        """Parse YAML frontmatter from a SKILL.md file."""
+        try:
+            with open(skill_file, "r", encoding="utf-8") as f:
+                content = f.read()
+
+            if not content.startswith("---"):
+                return None
+
+            parts = content.split("---", 2)
+            if len(parts) < 3:
+                return None
+
+            metadata = yaml.safe_load(parts[1])
+            if isinstance(metadata, dict) and "name" in metadata and "description" in metadata:
+                return {
+                    "name": metadata["name"],
+                    "description": metadata["description"],
+                }
+            return None
+        except Exception as e:
+            logger.error(f"Failed to parse metadata from {skill_file}: {e}")
+            return None
+
+    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: skills/{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-0.7.2/src/kagent/adk/skills/skills_plugin.py

@@ -0,0 +1,90 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+from google.adk.agents import BaseAgent, LlmAgent
+from google.adk.agents.callback_context import CallbackContext
+from google.adk.plugins import BasePlugin
+from google.genai import types
+
+from .bash_tool import BashTool
+from .skill_tool import SkillsTool
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class SkillsPlugin(BasePlugin):
+    """Convenience plugin for multi-agent apps to automatically register Skills tools.
+
+    This plugin is purely a convenience wrapper that automatically adds the SkillsTool
+    and BashTool to all LLM agents in an application. It does not add any additional
+    functionality beyond tool registration.
+
+    For single-agent use cases or when you prefer explicit control, you can skip this plugin
+    and directly add both tools to your agent's tools list.
+
+    Example:
+        # Without plugin (direct tool usage):
+        agent = Agent(
+            tools=[
+                SkillsTool(skills_directory="./skills"),
+                BashTool(skills_directory="./skills"),
+            ]
+        )
+
+        # With plugin (auto-registration for multi-agent apps):
+        app = App(
+            root_agent=agent,
+            plugins=[SkillsPlugin(skills_directory="./skills")]
+        )
+    """
+
+    def __init__(self, skills_directory: str | Path, name: str = "skills_plugin"):
+        """Initialize the skills plugin.
+
+        Args:
+          skills_directory: Path to directory containing skill folders.
+          name: Name of the plugin instance.
+        """
+        super().__init__(name)
+        self.skills_directory = Path(skills_directory)
+        self.skills_invoke_tool = SkillsTool(skills_directory)
+        self.bash_tool = BashTool(skills_directory)
+
+    async def before_agent_callback(
+        self, *, agent: BaseAgent, callback_context: CallbackContext
+    ) -> Optional[types.Content]:
+        """Add skills tools to agents if not already present."""
+
+        if not isinstance(agent, LlmAgent):
+            return None
+
+        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(self.skills_invoke_tool)
+            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(self.bash_tool)
+            logger.debug(f"Added bash tool to agent: {agent.name}")
+
+        return None

kagent_adk-0.7.2/src/kagent/adk/skills/skills_toolset.py

@@ -0,0 +1,54 @@
+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 .bash_tool import BashTool
+from .skill_tool import SkillsTool
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+class SkillsToolset(BaseToolset):
+    """Toolset that provides Skills functionality through two focused tools.
+
+    This toolset provides skills access through two complementary tools following
+    progressive disclosure:
+    1. SkillsTool - Discover and load skill instructions
+    2. BashTool - Execute commands based on skill guidance
+
+    This separation provides clear semantic distinction between skill discovery
+    (what can I do?) and skill execution (how do I do it?).
+    """
+
+    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 the two tools for skills operations
+        self.skills_invoke_tool = SkillsTool(skills_directory)
+        self.bash_tool = BashTool(skills_directory)
+
+    @override
+    async def get_tools(self, readonly_context: Optional[ReadonlyContext] = None) -> List[BaseTool]:
+        """Get both skills tools.
+
+        Returns:
+          List containing SkillsTool and BashTool.
+        """
+        return [self.skills_invoke_tool, self.bash_tool]

kagent_adk-0.7.2/src/kagent/adk/skills/stage_artifacts_tool.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, List
+
+from typing_extensions import override
+
+from google.adk.tools import BaseTool, ToolContext
+from google.genai import types
+
+logger = logging.getLogger("kagent_adk." + __name__)
+
+
+def get_session_staging_path(session_id: str, app_name: str, skills_directory: Path) -> Path:
+    """Creates (if needed) and returns the path to a session's staging directory.
+
+    This function provides a consistent, isolated filesystem environment for each
+    session. It creates a root directory for the session and populates it with
+    an 'uploads' folder and a symlink to the static 'skills' directory.
+
+    Args:
+        session_id: The unique ID of the current session.
+        app_name: The name of the application, used for namespacing.
+        skills_directory: The path to the static skills directory.
+
+    Returns:
+        The resolved path to the session's root staging directory.
+    """
+    base_path = Path(tempfile.gettempdir()) / "adk_sessions" / app_name
+    session_path = base_path / session_id
+
+    # Create the session and uploads directories
+    (session_path / "uploads").mkdir(parents=True, exist_ok=True)
+
+    # Symlink the static skills directory into the session directory
+    if skills_directory and skills_directory.exists():
+        skills_symlink = session_path / "skills"
+        if not skills_symlink.exists():
+            try:
+                os.symlink(
+                    skills_directory.resolve(),
+                    skills_symlink,
+                    target_is_directory=True,
+                )
+            except OSError as e:
+                logger.error(f"Failed to create skills symlink: {e}")
+
+    return session_path.resolve()
+
+
+class StageArtifactsTool(BaseTool):
+    """A tool to stage artifacts from the artifact service to the local filesystem.
+
+    This tool bridges the gap between the artifact store and the skills system,
+    enabling skills to work with user-uploaded files through a two-phase workflow:
+    1. Stage: Copy artifacts from artifact store to local 'uploads/' directory
+    2. Execute: Use the staged files in bash commands with skills
+
+    This is essential for the skills workflow where user-uploaded files must be
+    accessible to skill scripts and commands.
+    """
+
+    def __init__(self, skills_directory: Path):
+        super().__init__(
+            name="stage_artifacts",
+            description=(
+                "Stage artifacts from the artifact store to a local filesystem path, "
+                "making them available for use with skills and the bash tool.\n\n"
+                "WORKFLOW:\n"
+                "1. When a user uploads a file, it's stored as an artifact (e.g., 'artifact_xyz')\n"
+                "2. Use this tool to copy the artifact to your local 'uploads/' directory\n"
+                "3. Then reference the staged file path in bash commands\n\n"
+                "USAGE EXAMPLE:\n"
+                "- stage_artifacts(artifact_names=['artifact_xyz'])\n"
+                "  Returns: 'Successfully staged 1 artifact(s) to: uploads/artifact_xyz'\n"
+                "- Use the returned path in bash: bash('python skills/data-analysis/scripts/process.py uploads/artifact_xyz')\n\n"
+                "PARAMETERS:\n"
+                "- artifact_names: List of artifact names to stage (required)\n"
+                "- destination_path: Target directory within session (default: 'uploads/')\n\n"
+                "BEST PRACTICES:\n"
+                "- Always stage artifacts before using them in skills\n"
+                "- Use default 'uploads/' destination for consistency\n"
+                "- Stage all artifacts at the start of your workflow\n"
+                "- Check returned paths to confirm successful staging"
+            ),
+        )
+        self._skills_directory = skills_directory
+
+    def _get_declaration(self) -> types.FunctionDeclaration | None:
+        return types.FunctionDeclaration(
+            name=self.name,
+            description=self.description,
+            parameters=types.Schema(
+                type=types.Type.OBJECT,
+                properties={
+                    "artifact_names": types.Schema(
+                        type=types.Type.ARRAY,
+                        description=(
+                            "List of artifact names to stage. These are artifact identifiers "
+                            "provided by the system when files are uploaded (e.g., 'artifact_abc123'). "
+                            "The tool will copy each artifact from the artifact store to the destination directory."
+                        ),
+                        items=types.Schema(type=types.Type.STRING),
+                    ),
+                    "destination_path": types.Schema(
+                        type=types.Type.STRING,
+                        description=(
+                            "Relative path within the session directory to save the files. "
+                            "Default is 'uploads/' where user-uploaded files are conventionally stored. "
+                            "Path must be within the session directory for security. "
+                            "Useful for organizing different types of artifacts (e.g., 'uploads/input/', 'uploads/processed/')."
+                        ),
+                        default="uploads/",
+                    ),
+                },
+                required=["artifact_names"],
+            ),
+        )
+
+    @override
+    async def run_async(self, *, args: dict[str, Any], tool_context: ToolContext) -> str:
+        artifact_names: List[str] = args.get("artifact_names", [])
+        destination_path_str: str = args.get("destination_path", "uploads/")
+
+        if not tool_context._invocation_context.artifact_service:
+            return "Error: Artifact service is not available in this context."
+
+        try:
+            staging_root = get_session_staging_path(
+                session_id=tool_context.session.id,
+                app_name=tool_context._invocation_context.app_name,
+                skills_directory=self._skills_directory,
+            )
+            destination_dir = (staging_root / destination_path_str).resolve()
+
+            # Security: Ensure the destination is within the staging path
+            if staging_root not in destination_dir.parents and destination_dir != staging_root:
+                return f"Error: Invalid destination path '{destination_path_str}'."
+
+            destination_dir.mkdir(parents=True, exist_ok=True)
+
+            output_paths = []
+            for name in artifact_names:
+                artifact = await tool_context.load_artifact(name)
+                if artifact is None or artifact.inline_data is None:
+                    logger.warning('Artifact "%s" not found or has no data, skipping', name)
+                    continue
+
+                output_file = destination_dir / name
+                output_file.write_bytes(artifact.inline_data.data)
+                relative_path = output_file.relative_to(staging_root)
+                output_paths.append(str(relative_path))
+
+            if not output_paths:
+                return "No valid artifacts were staged."
+
+            return f"Successfully staged {len(output_paths)} artifact(s) to: {', '.join(output_paths)}"
+
+        except Exception as e:
+            logger.error("Error staging artifacts: %s", e, exc_info=True)
+            return f"An error occurred while staging artifacts: {e}"