kagent-adk 0.7.11__py3-none-any.whl

kagent/adk/models/_ssl.py

@@ -0,0 +1,245 @@
+"""SSL/TLS utilities for configuring httpx clients with custom certificates."""
+
+import logging
+import ssl
+from datetime import datetime, timezone
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+def get_ssl_troubleshooting_message(
+    error: Exception, ca_cert_path: str | None = None, server_url: str | None = None
+) -> str:
+    """Generate actionable troubleshooting message for SSL errors.
+
+    Args:
+        error: The original SSL error.
+        ca_cert_path: Path to custom CA certificate if one was configured.
+        server_url: URL of the server that was being accessed.
+
+    Returns:
+        Formatted troubleshooting message with specific debugging steps.
+    """
+    troubleshooting_steps = [
+        "\n" + "=" * 70,
+        "SSL/TLS Connection Error",
+        "=" * 70,
+        f"Error: {error}",
+        "",
+        "Troubleshooting Steps:",
+        "",
+    ]
+
+    if ca_cert_path:
+        troubleshooting_steps.extend(
+            [
+                "1. Verify the CA certificate is correctly mounted:",
+                f"   kubectl exec <pod-name> -- cat {ca_cert_path}",
+                "",
+                "2. Inspect the certificate details:",
+                f"   kubectl exec <pod-name> -- openssl x509 -in {ca_cert_path} -text -noout",
+                "",
+                "3. Check the certificate validity period:",
+                f"   kubectl exec <pod-name> -- openssl x509 -in {ca_cert_path} -noout -dates",
+                "",
+            ]
+        )
+
+    if server_url:
+        troubleshooting_steps.extend(
+            [
+                "4. Test the server certificate chain:",
+                f"   openssl s_client -connect {server_url} -showcerts",
+                "",
+                "5. Verify the server certificate is signed by your CA:",
+                f"   openssl s_client -connect {server_url} -CAfile {ca_cert_path or '<ca-file>'} -verify 5",
+                "",
+            ]
+        )
+
+    troubleshooting_steps.extend(
+        [
+            "6. Check Kubernetes Secret contents:",
+            "   kubectl get secret <secret-name> -o yaml",
+            "   # Verify the certificate data is base64-encoded PEM format",
+            "",
+            "7. Verify the ModelConfig TLS configuration:",
+            "   kubectl get modelconfig <name> -o yaml",
+            "   # Check spec.tls.caCertSecretRef and spec.tls.caCertSecretKey",
+            "",
+            "For more information, see:",
+            "   https://kagent.dev/docs",
+            "=" * 70,
+        ]
+    )
+
+    return "\n".join(troubleshooting_steps)
+
+
+def validate_certificate(cert_path: str) -> None:
+    """Validate certificate format and log metadata (warnings only, non-blocking).
+
+    This function attempts to parse the certificate file and log useful metadata
+    including subject, serial number, and validity period. Validation issues are
+    logged as warnings but do not prevent the certificate from being loaded.
+
+    Args:
+        cert_path: Path to the certificate file in PEM format.
+
+    Note:
+        This function requires the 'cryptography' library. If not available,
+        validation is skipped with an info log message.
+    """
+    try:
+        from cryptography import x509
+        from cryptography.hazmat.backends import default_backend
+    except ImportError:
+        logger.info(
+            "cryptography library not available - skipping certificate validation. "
+            "Install with: pip install cryptography"
+        )
+        return
+
+    try:
+        with open(cert_path, "rb") as f:
+            cert_data = f.read()
+        cert = x509.load_pem_x509_certificate(cert_data, default_backend())
+
+        # Log certificate metadata
+        logger.info("Certificate subject: %s", cert.subject.rfc4514_string())
+        logger.info("Certificate serial number: %s", hex(cert.serial_number))
+        logger.info(
+            "Certificate valid from %s to %s",
+            cert.not_valid_before_utc,
+            cert.not_valid_after_utc,
+        )
+
+        # Warn about expiry (non-blocking)
+        now = datetime.now(timezone.utc)
+        if cert.not_valid_after_utc < now:
+            logger.warning(
+                "Certificate has EXPIRED on %s. Please update the certificate Secret.",
+                cert.not_valid_after_utc,
+            )
+        elif cert.not_valid_before_utc > now:
+            logger.warning(
+                "Certificate is not yet valid until %s. Check system clock or certificate validity period.",
+                cert.not_valid_before_utc,
+            )
+
+    except Exception as e:
+        logger.warning(
+            "Could not validate certificate format at %s: %s. Certificate will still be loaded, but may be invalid.",
+            cert_path,
+            e,
+        )
+
+
+def create_ssl_context(
+    disable_verify: bool,
+    ca_cert_path: str | None,
+    disable_system_cas: bool,
+) -> ssl.SSLContext | bool:
+    """Create SSL context for httpx client based on TLS configuration.
+
+    This function creates an appropriate SSL context based on three possible modes:
+    1. Verification disabled: Returns False (httpx accepts False to disable verification)
+    2. Custom CA only: Creates SSL context with custom CA certificate, no system CAs
+    3. System + Custom CA: Creates SSL context with system CAs plus custom CA certificate
+
+    Args:
+        disable_verify: If True, SSL verification is disabled (development/testing only).
+            When True, a prominent warning is logged.
+        ca_cert_path: Optional path to custom CA certificate file in PEM format.
+            If provided, the certificate is loaded into the SSL context.
+        disable_system_cas: If True, system CA certificates are NOT included in the trust store.
+            When False (default), system CAs are used (safe behavior).
+            When True with ca_cert_path, only the custom CA is trusted.
+
+    Returns:
+        - False if disable_verify=True (httpx special value to disable verification)
+        - ssl.SSLContext configured with appropriate CA certificates otherwise
+
+    Raises:
+        FileNotFoundError: If ca_cert_path is provided but file does not exist.
+        ssl.SSLError: If certificate file is invalid or cannot be loaded.
+
+    Examples:
+        >>> # Disable verification (development only)
+        >>> ctx = create_ssl_context(disable_verify=True, ca_cert_path=None, disable_system_cas=False)
+        >>> assert ctx is False
+
+        >>> # Use only custom CA certificate
+        >>> ctx = create_ssl_context(
+        ...     disable_verify=False, ca_cert_path="/etc/ssl/certs/custom/ca.crt", disable_system_cas=True
+        ... )
+        >>> assert isinstance(ctx, ssl.SSLContext)
+
+        >>> # Use system CAs plus custom CA
+        >>> ctx = create_ssl_context(
+        ...     disable_verify=False, ca_cert_path="/etc/ssl/certs/custom/ca.crt", disable_system_cas=False
+        ... )
+        >>> assert isinstance(ctx, ssl.SSLContext)
+    """
+    # Structured logging for TLS configuration at startup
+    if disable_verify:
+        logger.warning(
+            "\n"
+            "=" * 60 + "\n"
+            "⚠️  SSL VERIFICATION DISABLED ⚠️\n"
+            "=" * 60 + "\n"
+            "SSL certificate verification is disabled.\n"
+            "This should ONLY be used in development/testing.\n"
+            "Production deployments MUST use proper certificates.\n"
+            "=" * 60
+        )
+        logger.info("TLS Mode: Disabled (disable_verify=True)")
+        return False  # httpx accepts False to disable verification
+
+    # Determine TLS mode
+    if ca_cert_path and not disable_system_cas:
+        tls_mode = "Custom CA + System CAs (additive)"
+    elif ca_cert_path:
+        tls_mode = "Custom CA only (no system CAs)"
+    else:
+        tls_mode = "System CAs only (default)"
+
+    logger.info("TLS Mode: %s", tls_mode)
+
+    # Start with system CAs or empty context
+    if not disable_system_cas:
+        # Create default context which includes system CAs
+        ctx = ssl.create_default_context()
+        logger.info("Using system CA certificates")
+    else:
+        # Create empty context without system CAs
+        ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+        ctx.check_hostname = True
+        ctx.verify_mode = ssl.CERT_REQUIRED
+        logger.info("System CA certificates disabled (disable_system_cas=True)")
+
+    # Load custom CA certificate if provided
+    if ca_cert_path:
+        cert_path = Path(ca_cert_path)
+        if not cert_path.exists():
+            raise FileNotFoundError(
+                f"CA certificate file not found: {ca_cert_path}\n"
+                f"Please ensure the certificate Secret is mounted correctly.\n"
+                f"Check: kubectl get secret <secret-name> -n <namespace>"
+            )
+
+        # Validate certificate format and log metadata
+        validate_certificate(str(cert_path))
+
+        try:
+            ctx.load_verify_locations(cafile=str(cert_path))
+            logger.info("Custom CA certificate loaded from: %s", ca_cert_path)
+        except ssl.SSLError as e:
+            raise ssl.SSLError(
+                f"Failed to load CA certificate from {ca_cert_path}: {e}\n"
+                f"Please verify the certificate is in valid PEM format.\n"
+                f"You can inspect it with: openssl x509 -in {ca_cert_path} -text -noout"
+            ) from e
+
+    return ctx

kagent/adk/sandbox_code_executer.py

@@ -0,0 +1,77 @@
+# 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 subprocess
+
+from google.adk.agents.invocation_context import InvocationContext
+from google.adk.code_executors.base_code_executor import BaseCodeExecutor
+from google.adk.code_executors.code_execution_utils import CodeExecutionInput, CodeExecutionResult
+from pydantic import Field
+from typing_extensions import override
+
+
+class SandboxedLocalCodeExecutor(BaseCodeExecutor):
+    """A code executor that execute code in a sandbox in the current local context."""
+
+    # Overrides the BaseCodeExecutor attribute: this executor cannot be stateful.
+    stateful: bool = Field(default=False, frozen=True, exclude=True)
+
+    # Overrides the BaseCodeExecutor attribute: this executor cannot
+    # optimize_data_file.
+    optimize_data_file: bool = Field(default=False, frozen=True, exclude=True)
+
+    def __init__(self, **data):
+        """Initializes the SandboxedLocalCodeExecutor."""
+        if "stateful" in data and data["stateful"]:
+            raise ValueError("Cannot set `stateful=True` in SandboxedLocalCodeExecutor.")
+        if "optimize_data_file" in data and data["optimize_data_file"]:
+            raise ValueError("Cannot set `optimize_data_file=True` in SandboxedLocalCodeExecutor.")
+        super().__init__(**data)
+
+    @override
+    def execute_code(
+        self,
+        invocation_context: InvocationContext,
+        code_execution_input: CodeExecutionInput,
+    ) -> CodeExecutionResult:
+        """Executes the given code in a sandboxed local context. uses the srt command to sandbox"""
+        output = ""
+        error = ""
+
+        try:
+            # Execute the provided code by piping it to `python -` inside the sandbox.
+            proc = subprocess.run(
+                ["srt", "python", "-"],
+                input=code_execution_input.code,
+                capture_output=True,
+                text=True,
+            )
+            output = proc.stdout or ""
+            error = proc.stderr or ""
+        except FileNotFoundError as e:
+            # srt or python not found
+            output = ""
+            error = f"Execution failed: {e}"
+        except Exception as e:
+            output = ""
+            error = f"Unexpected error during execution: {e}"
+
+        # Collect the final result.
+        return CodeExecutionResult(
+            stdout=output,
+            stderr=error,
+            output_files=[],
+        )

kagent/adk/skill_fetcher.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import logging
+import os
+import tarfile
+from typing import Tuple
+
+logger = logging.getLogger(__name__)
+
+
+def _parse_image_ref(image: str) -> Tuple[str, str, str]:
+    """
+    Parse an OCI/Docker image reference into (registry, repository, reference).
+
+    reference is either a tag (default "latest") or a digest (e.g., "sha256:...").
+    Rules (compatible with Docker/OCI name parsing):
+    - If the reference contains a digest ("@"), prefer a tag if also present (repo:tag@digest),
+      otherwise keep the digest as the reference.
+    - If there is no tag nor digest, default the reference to "latest".
+    - If the first path component contains a '.' or ':' or equals 'localhost', it is treated as the registry.
+      Otherwise the registry defaults to docker hub (docker.io), with the special library namespace for single-component names.
+    """
+    name_part = image
+    ref = "latest"
+
+    if "@" in image:
+        # Split digest
+        name_part, digest = image.split("@", 1)
+        ref = digest
+
+    # Possibly has a tag: detect a colon after the last slash
+    slash = name_part.rfind("/")
+    colon = name_part.rfind(":")
+    if colon > slash:
+        ref = name_part[colon + 1 :]
+        name_part = name_part[:colon]
+    # else: keep default "latest"
+
+    # Determine registry and repo path
+    parts = name_part.split("/")
+    if len(parts) == 1:
+        # Implicit docker hub library image
+        registry = "registry-1.docker.io"
+        repo = f"library/{parts[0]}"
+    else:
+        first = parts[0]
+        if first == "localhost" or "." in first or ":" in first:
+            # Explicit registry (may include port)
+            registry = first
+            repo = "/".join(parts[1:])
+        else:
+            # Docker hub with user/org namespace
+            registry = "docker.io"
+            repo = "/".join(parts)
+
+    return registry, repo, ref
+
+
+def fetch_using_crane_to_dir(image: str, destination_folder: str, insecure: bool = False) -> None:
+    """Fetch a skill using crane and extract it to destination_folder."""
+    import subprocess
+
+    tar_path = os.path.join(destination_folder, "skill.tar")
+    os.makedirs(destination_folder, exist_ok=True)
+    command = ["crane", "export", image, tar_path]
+    if insecure:
+        command.insert(1, "--insecure")
+    # Use crane to pull the image as a tarball
+    subprocess.run(
+        command,
+        check=True,
+    )
+
+    # Extract the tarball
+    with tarfile.open(tar_path, "r") as tar:
+        tar.extractall(path=destination_folder, filter=tarfile.data_filter)
+
+    # Remove the tarball
+    os.remove(tar_path)
+
+
+def fetch_skill(skill_image: str, destination_folder: str, insecure: bool = False) -> None:
+    """
+    Fetch a skill packaged as an OCI/Docker image and write its files to destination_folder.
+
+    To build a compatible skill image from a folder (containing SKILL.md), use a simple Dockerfile:
+        FROM scratch
+        COPY . /
+
+    Args:
+        skill_image: The image reference (e.g., "alpine:latest", "ghcr.io/org/skill:tag", or with a digest).
+        destination_folder: The folder where the skill files should be written.
+    """
+    registry, repo, ref = _parse_image_ref(skill_image)
+
+    # skill name is the last part of the repo
+    repo_parts = repo.split("/")
+    skill_name = repo_parts[-1]
+    logger.info(
+        f"about to fetching skill {skill_name} from image {skill_image} (registry: {registry}, repo: {repo}, ref: {ref})"
+    )
+
+    fetch_using_crane_to_dir(skill_image, os.path.join(destination_folder, skill_name), insecure)

kagent/adk/tools/README.md

@@ -0,0 +1,217 @@
+# ADK Skills
+
+Filesystem-based skills with progressive disclosure and two-tool architecture for domain expertise.
+
+---
+
+## Quick Start
+
+### Recommended: Plugin-Based (Multi-Agent Apps)
+
+```python
+from kagent.adk.skills import SkillsPlugin
+
+# Plugin automatically initializes sessions and registers all skills tools
+app = App(
+    root_agent=agent,
+    plugins=[SkillsPlugin(skills_directory="./skills")]
+)
+```
+
+**Benefits:**
+
+- ✅ Session paths initialized before any tool runs
+- ✅ Automatic tool registration on all agents
+- ✅ Handles custom skills directories correctly
+- ✅ No tool call order dependencies
+
+### Alternative: Direct Tool Usage
+
+```python
+from kagent.adk.skills import SkillsTool
+from kagent.adk.tools import BashTool, ReadFileTool, WriteFileTool, EditFileTool
+
+agent = Agent(
+    tools=[
+        SkillsTool(skills_directory="./skills"),
+        BashTool(skills_directory="./skills"),
+        ReadFileTool(),
+        WriteFileTool(),
+        EditFileTool(),
+    ]
+)
+```
+
+**Note:** Without SkillsPlugin, sessions auto-initialize with `/skills` directory. For custom skills paths, use the plugin.
+
+---
+
+## Session Initialization
+
+Skills uses a **plugin-based initialization pattern** to ensure session working directories are set up before any tools run.
+
+### How It Works
+
+```text
+App Starts
+    ↓
+SkillsPlugin initialized with skills_directory
+    ↓
+First Agent Turn
+    ↓
+before_agent_callback() hook fires
+    ↓
+Session path initialized with skills symlink
+    ↓
+Tools registered on agent
+    ↓
+Tools execute (session already initialized)
+```
+
+**Key Points:**
+
+- `SkillsPlugin.before_agent_callback()` fires **before any tool invocation**
+- Creates `/tmp/kagent/{session_id}/` with `skills/` symlink
+- All tools use `get_session_path(session_id)` which returns cached path
+- **No tool call order dependencies** - session always ready
+
+**Without Plugin:**
+
+- Tools auto-initialize session with default `/skills` on first call
+- Works fine if skills are at `/skills` location
+- For custom paths, use SkillsPlugin
+
+---
+
+## Architecture
+
+### Skill Structure
+
+```text
+skills/
+├── data-analysis/
+│   ├── SKILL.md        # Metadata (YAML frontmatter) + instructions
+│   └── scripts/        # Python scripts, configs, etc.
+│       └── analyze.py
+```
+
+**SKILL.md Example:**
+
+```markdown
+---
+name: data-analysis
+description: Analyze CSV/Excel files
+---
+
+# Data Analysis
+
+...instructions for the agent...
+```
+
+### Tool Workflow
+
+**Three Phases:**
+
+1. **Discovery** - Agent sees available skills in SkillsTool description
+2. **Loading** - Agent calls `skills(command='data-analysis')` → gets full SKILL.md
+3. **Execution** - Agent uses BashTool + file tools to run scripts per instructions
+
+| Tool           | Purpose                      | Example                                               |
+| -------------- | ---------------------------- | ----------------------------------------------------- |
+| **SkillsTool** | Load skill instructions      | `skills(command='data-analysis')`                     |
+| **BashTool**   | Execute commands             | `bash("cd skills/data-analysis && python script.py")` |
+| **ReadFile**   | Read files with line numbers | `read_file("skills/data-analysis/config.json")`       |
+| **WriteFile**  | Create/overwrite files       | `write_file("outputs/report.pdf", data)`              |
+| **EditFile**   | Precise string replacements  | `edit_file("script.py", old="x", new="y")`            |
+
+### Working Directory Structure
+
+Each session gets an isolated working directory with symlinked skills:
+
+```text
+/tmp/kagent/{session_id}/
+├── skills/      → symlink to /skills (read-only, shared across sessions)
+├── uploads/     → staged user files (writable)
+├── outputs/     → generated files for download (writable)
+└── *.py         → temporary scripts (writable)
+```
+
+**Path Resolution:**
+
+- Relative paths resolve from working directory: `skills/data-analysis/script.py`
+- Absolute paths work too: `/tmp/kagent/{session_id}/outputs/report.pdf`
+- Skills symlink enables natural relative references while maintaining security
+
+---
+
+## Artifact Handling
+
+User uploads and downloads are managed through artifact tools:
+
+```python
+# 1. Stage uploaded file from artifact service
+stage_artifacts(artifact_names=["sales_data.csv"])
+# → Writes to: uploads/sales_data.csv
+
+# 2. Agent processes file
+bash("python skills/data-analysis/scripts/analyze.py uploads/sales_data.csv")
+# → Script writes: outputs/report.pdf
+
+# 3. Return generated file
+return_artifacts(file_paths=["outputs/report.pdf"])
+# → Saves to artifact service for user download
+```
+
+**Flow:** User Upload → Artifact Service → `uploads/` → Processing → `outputs/` → Artifact Service → User Download
+
+---
+
+## Security
+
+**Read-only skills directory:**
+
+- Skills at `/skills` are read-only (enforced by sandbox)
+- Symlink at `skills/` inherits read-only permissions
+- Agents cannot modify skill code or instructions
+
+**File tools:**
+
+- Path traversal protection (no `..`)
+- Session isolation (each session has separate working directory)
+- File size limits (100 MB max)
+
+**Bash tool:**
+
+- Sandboxed execution via Anthropic Sandbox Runtime
+- Command timeouts (30s default, 120s for pip install)
+- Working directory restrictions
+
+---
+
+## Example Agent Flow
+
+```python
+# User asks: "Analyze my sales data"
+
+# 1. Agent discovers available skills
+#    → SkillsTool description lists: data-analysis, pdf-processing, etc.
+
+# 2. Agent loads skill instructions
+agent: skills(command='data-analysis')
+#    → Returns full SKILL.md with detailed instructions
+
+# 3. Agent stages uploaded file
+agent: stage_artifacts(artifact_names=["sales_data.csv"])
+#    → File available at: uploads/sales_data.csv
+
+# 4. Agent reads skill script to understand it
+agent: read_file("skills/data-analysis/scripts/analyze.py")
+
+# 5. Agent executes analysis
+agent: bash("cd skills/data-analysis && python scripts/analyze.py ../../uploads/sales_data.csv")
+#    → Script generates: outputs/analysis_report.pdf
+
+# 6. Agent returns result
+agent: return_artifacts(file_paths=["outputs/analysis_report.pdf"])
+#    → User can download report.pdf
+```

kagent/adk/tools/__init__.py

@@ -0,0 +1,15 @@
+from .bash_tool import BashTool
+from .file_tools import EditFileTool, ReadFileTool, WriteFileTool
+from .skill_tool import SkillsTool
+from .skills_plugin import add_skills_tool_to_agent
+from .skills_toolset import SkillsToolset
+
+__all__ = [
+    "SkillsTool",
+    "SkillsToolset",
+    "BashTool",
+    "EditFileTool",
+    "ReadFileTool",
+    "WriteFileTool",
+    "add_skills_tool_to_agent",
+]