agentrun-sdk 0.1.2__py3-none-any.whl

agentrun_operation_sdk/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI commands for the Bedrock AgentCore Starter Toolkit."""

agentrun_operation_sdk/cli/cli.py

@@ -0,0 +1,19 @@
+import typer
+from ..utils.logging_config import setup_toolkit_logging
+from .runtime.commands import create, configure
+
+app = typer.Typer(name="agentrun", help="HWAgentRun CLI", add_completion=False, rich_markup_mode="rich")
+
+setup_toolkit_logging(mode="cli")
+
+app.command("create")(create)
+app.command("configure")(configure)
+
+
+def main():
+    """Entry point for the CLI application."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

agentrun_operation_sdk/cli/common.py

@@ -0,0 +1,21 @@
+from typing import NoReturn, Optional
+import typer
+from rich.console import Console
+
+console = Console()
+
+def _handle_error(message: str, exception: Optional[Exception] = None) -> NoReturn:
+    """Handle errors with consistent formatting and exit."""
+    console.print(f"[red]❌ {message}[/red]")
+    if exception:
+        raise typer.Exit(1) from exception
+    else:
+        raise typer.Exit(1)
+
+def _print_success(message: str) -> None:
+    """Print success message with consistent formatting."""
+    console.print(f"[green]✓[/green] {message}")
+
+def _handle_warn(message: str) -> None:
+    """Handle errors with consistent formatting and exit."""
+    console.print(f"⚠️  {message}", new_line_start=True, style="bold yellow underline")

agentrun_operation_sdk/cli/runtime/__init__.py

@@ -0,0 +1 @@
+"""BedrockAgentCore Starter Toolkit cli runtime package."""

agentrun_operation_sdk/cli/runtime/commands.py

@@ -0,0 +1,203 @@
+import typer
+from pathlib import Path
+from typing import Optional, List
+from rich.panel import Panel
+from prompt_toolkit import prompt
+from prompt_toolkit.completion import PathCompleter
+from ..common import console, _handle_error, _print_success
+from ...operations.runtime import (
+    validate_agent_name,
+    launch_agentrun,
+    configure_agentrun
+)
+from ...utils.runtime.entrypoint import parse_entrypoint
+
+
+def _validate_requirements_file(file_path: str) -> str:
+    """Validate requirements file and return the path."""
+    from ...utils.runtime.entrypoint import validate_requirements_file
+
+    try:
+        deps = validate_requirements_file(Path.cwd(), file_path)
+        _print_success(f"Using requirements file: [dim]{deps.resolved_path}[/dim]")
+        return file_path
+    except (FileNotFoundError, ValueError) as e:
+        _handle_error(str(e), e)
+
+
+def _prompt_for_requirements_file(prompt_text: str, default: str = "") -> Optional[str]:
+    """Prompt user for requirements file path with validation."""
+    response = prompt(prompt_text, completer=PathCompleter(), default=default)
+
+    if response.strip():
+        return _validate_requirements_file(response.strip())
+
+    return None
+
+def configure(
+    entrypoint: Optional[str] = None,
+    agent_name: Optional[str] = None,
+    container_runtime: Optional[str] = None,
+    requirements_file: Optional[str] = None,
+    region: Optional[str] = None,
+    protocol: Optional[str] = None,
+):
+    """Configure a AgentRun agent. The agent name defaults to your Python file name."""
+    if not entrypoint:
+        _handle_error("--entrypoint is required")
+
+    if protocol and protocol.upper() not in ["HTTP", "MCP"]:
+        _handle_error("Error: --protocol must be either HTTP or MCP")
+
+    console.print("[cyan]Configuring Bedrock AgentCore...[/cyan]")
+    try:
+        _, file_name = parse_entrypoint(entrypoint)
+        agent_name = agent_name or file_name
+
+        valid, error = validate_agent_name(agent_name)
+        if not valid:
+            _handle_error(error)
+
+        console.print(f"[dim]Agent name: {agent_name}[/dim]")
+    except ValueError as e:
+        _handle_error(f"Error: {e}", e)
+
+    final_requirements_file = _handle_requirements_file_display(requirements_file) 
+
+    try:
+        result = configure_agentrun(
+            agent_name=agent_name,
+            entrypoint_path=Path(entrypoint),
+            container_runtime=container_runtime,
+            requirements_file=final_requirements_file,
+            region=region,
+            protocol=protocol.upper() if protocol else None,
+        )
+        console.print(
+            Panel(
+                f"[green]Configuration Summary[/green]\n\n"
+                f"Name: {agent_name}\n"
+                f"Runtime: {result.runtime}\n"
+                f"Region: {result.region}\n"
+                f"Configuration saved to: {result.config_path}",
+                title="AgentRun Configured",
+                border_style="green",
+            )
+        )
+
+    except ValueError as e:
+        # Handle validation errors from core layer
+        _handle_error(str(e), e)
+    except Exception as e:
+        _handle_error(f"Configuration failed: {e}", e)
+
+def create(
+    entrypoint: Optional[str] = typer.Option(None, "--entrypoint", "-e", help="Python file with AgentRunApp"),
+    agent_name: Optional[str] = typer.Option(None, "--name", "-n"),
+    requirements_file: Optional[str] = typer.Option(
+        None, "--requirements-file", "-rf", help="Path to requirements file"
+    ),
+    container_runtime: Optional[str] = typer.Option(None, "--container-runtime", "-ctr"),
+    region: Optional[str] = typer.Option(None, "--region", "-r"),
+    protocol: Optional[str] = typer.Option(None, "--protocol", "-p", help="Server protocol (HTTP or MCP)"),
+
+    local: bool = typer.Option(
+        False, "--local", "-l", help="Build locally and run container locally - requires Docker/Finch/Podman"
+    ),
+    envs: List[str] = typer.Option(  # noqa: B008
+        None, "--env", "-env", help="Environment variables for agent (format: KEY=VALUE)"
+    ),
+):
+    """Launch AgentRun with three deployment modes.
+    --local: Local build + local runtime
+       - Build container locally and run locally
+       - requires Docker/Finch/Podman
+       - For local development and testing
+    """
+    configure(entrypoint, agent_name, container_runtime, requirements_file, region, protocol)
+
+    config_path = Path.cwd() / ".agentrun.yaml"
+
+    try:
+        # Show launch mode with enhanced migration guidance
+        if local:
+            mode = "local"
+            console.print(f"[cyan]🏠 Launching Bedrock AgentCore ({mode} mode)...[/cyan]")
+            console.print("[dim]   • Build and run container locally[/dim]")
+            console.print("[dim]   • Requires Docker/Finch/Podman to be installed[/dim]")
+            console.print("[dim]   • Perfect for development and testing[/dim]\n")
+
+        with console.status("[bold]Launching AgentRun...[/bold]"):
+            env_vars = None
+            if envs:
+                env_vars = {}
+                for env_var in envs:
+                    if "=" not in env_var:
+                        _handle_error(f"Invalid environment variable format: {env_var}. Use KEY=VALUE format.")
+                    key, value = env_var.split("=", 1)
+                    env_vars[key] = value
+
+            result = launch_agentrun(
+                config_path=config_path,
+                agent_name=agent_name,
+                local=local,
+                env_vars=env_vars,
+            )
+
+        if result.mode == "local":
+            _print_success(f"Docker image built: {result.tag}")
+            _print_success("Ready to run locally")
+            console.print("Starting server at http://localhost:8080")
+            console.print("[yellow]Press Ctrl+C to stop[/yellow]\n")
+
+            if result.runtime is None or result.port is None:
+                _handle_error("Unable to launch locally")
+
+            try:
+                result.runtime.run_local(result.tag, result.port, result.env_vars)
+            except KeyboardInterrupt:
+                console.print("\n[yellow]Stopped[/yellow]")
+
+    except FileNotFoundError:
+        _handle_error(".bedrock_agentcore.yaml not found. Run 'agentcore configure --entrypoint <file>' first")
+    except ValueError as e:
+        _handle_error(str(e), e)
+    except RuntimeError as e:
+        _handle_error(str(e), e)
+    except Exception as e:
+        if not isinstance(e, typer.Exit):
+            _handle_error(f"Launch failed: {e}", e)
+        raise
+
+def _handle_requirements_file_display(requirements_file: Optional[str]) -> Optional[str]:
+    """Handle requirements file with display logic for CLI."""
+    from ...utils.runtime.entrypoint import detect_dependencies
+
+    if requirements_file:
+        # User provided file - validate and show confirmation
+        return _validate_requirements_file(requirements_file)
+
+    # Auto-detection with interactive prompt
+    deps = detect_dependencies(Path.cwd())
+
+    if deps.found:
+        console.print(f"\n🔍 [cyan]Detected dependency file:[/cyan] [bold]{deps.file}[/bold]")
+        console.print("[dim]Press Enter to use this file, or type a different path (use Tab for autocomplete):[/dim]")
+
+        result = _prompt_for_requirements_file("Path or Press Enter to use detected dependency file: ", default="")
+
+        if result is None:
+            # Use detected file
+            _print_success(f"Using detected file: [dim]{deps.file}[/dim]")
+
+        return result
+    else:
+        console.print("\n[yellow]⚠️  No dependency file found (requirements.txt or pyproject.toml)[/yellow]")
+        console.print("[dim]Enter path to requirements file (use Tab for autocomplete), or press Enter to skip:[/dim]")
+
+        result = _prompt_for_requirements_file("Path: ")
+
+        if result is None:
+            _handle_error("No requirements file specified and none found automatically")
+
+        return result

agentrun_operation_sdk/client/client.py

@@ -0,0 +1,75 @@
+import json
+import logging
+from typing import Any, Dict, Iterator, Optional
+from pydantic import BaseModel, Field
+from ..services.runtime import generate_session_id, LocalAgentRunClient, AgentRunClient
+
+log = logging.getLogger(__name__)
+
+
+class InvokeResult(BaseModel):
+    """Result of invoke operation."""
+
+    response: Dict[str, Any] = Field(..., description="Response from Agentrun endpoint")
+    session_id: str = Field(..., description="Session ID used for invocation")
+
+
+class Session:
+    def __init__(self, session_id: str, 
+                 local_mode: Optional[bool] = False, 
+                 agent_id: Optional[str] = None,
+                 stream: Optional[bool] = False,
+                 region: Optional[str] = "cn-north-4"):
+        self.session_id = session_id
+        self.agent_id = agent_id
+        self.local_mode = local_mode
+        self.stream = stream
+        self.region = region
+
+    def invoke(
+            self,
+            payload: Any
+    ) -> InvokeResult:
+        """Invoke deployed Bedrock AgentCore endpoint."""
+        mode = "locally" if self.local_mode else "via cloud endpoint"
+        log.info("Invoking BedrockAgentCore agent '%s' %s", self.agent_id, mode)
+        if not self.session_id:
+            self.session_id = generate_session_id()
+
+        if isinstance(payload, dict):
+            payload_str = json.dumps(payload, ensure_ascii=False)
+        else:
+            payload_str = str(payload)
+
+        if self.local_mode:
+            client = LocalAgentRunClient("http://0.0.0.0:8080")
+            response = client.invoke_endpoint(self.session_id, payload_str, self.stream)
+        else:
+            client = AgentRunClient(self.region)
+            response = client.invoke_endpoint(
+                agent_id=self.agent_id,
+                payload=payload_str,
+                session_id=self.session_id,
+                stream=self.stream
+            )
+        return InvokeResult(
+            response=response,
+            session_id=self.session_id
+        )
+
+class Client:
+    def __init__(self, local_mode: Optional[bool] = True, 
+                 stream: Optional[bool] = True, 
+                 region: Optional[str] = "cn-north-4"):
+        self.session_id = generate_session_id()
+        self.local_mode = local_mode
+        self.stream = stream
+        self.region = region
+
+    def get_or_create_session(self, agent_id: str) -> Session:
+        session = Session(self.session_id, 
+                          self.local_mode, 
+                          agent_id,
+                          stream=self.stream,
+                          region=self.region)
+        return session

agentrun_operation_sdk/operations/runtime/__init__.py

@@ -0,0 +1,8 @@
+from .configure import validate_agent_name, configure_agentrun
+from .launch import launch_agentrun
+
+__all__ = [
+    "validate_agent_name",
+    "launch_agentrun",
+    "configure_agentrun"
+]

agentrun_operation_sdk/operations/runtime/configure.py

@@ -0,0 +1,101 @@
+import re
+import logging
+from pathlib import Path
+from typing import Optional, Tuple
+from .models import ConfigureResult
+from ...utils.runtime.config import merge_agent_config, save_config
+from ...utils.runtime.container import ContainerRuntime
+from ...utils.runtime.schema import (
+    AgentRunAgentSchema,
+)
+
+AGENT_NAME_REGEX = r"^[a-zA-Z][a-zA-Z0-9_]{0,47}$"
+AGENT_NAME_ERROR = (
+    "Invalid agent name. Must start with a letter, contain only letters/numbers/underscores, "
+    "and be 1-48 characters long."
+)
+
+log = logging.getLogger(__name__)
+
+def configure_agentrun(
+    agent_name: str,
+    entrypoint_path: Path,
+    container_runtime: Optional[str] = None,
+    requirements_file: Optional[str] = None,
+    region: Optional[str] = None,
+    protocol: Optional[str] = None,    
+) -> ConfigureResult:
+    """Configure AgentRun application with deployment settings.
+
+    Args:
+        agent_name: name of the agent,
+        entrypoint_path: Path to the entrypoint file
+        container_runtime: Container runtime to use
+        equirements_file: Path to requirements file
+        region: HW Cloud region for deployment
+        protocol: agent server protocol, must be either HTTP or MCP
+
+    Returns:
+        ConfigureResult model with configuration details
+    """
+    build_dir = Path.cwd()
+    region = region or "cn-north-4" 
+    runtime = ContainerRuntime(container_runtime)
+    agentrun_name = None
+    dockerfile_path = runtime.generate_dockerfile(
+        entrypoint_path,
+        build_dir,
+        agentrun_name or "agentrun",
+        region,
+        requirements_file,
+    )
+    dockerignore_path = build_dir / ".dockerignore"
+    log.info("Generated Dockerfile: %s", dockerfile_path)
+    if dockerignore_path.exists():
+        log.info("Generated .dockerignore: %s", dockerignore_path)
+
+    config_path = build_dir / ".agentrun.yaml"
+    entrypoint_path_str = entrypoint_path.as_posix()
+    if agentrun_name:
+        entrypoint = f"{entrypoint_path_str}:{agentrun_name}"
+    else:
+        entrypoint = entrypoint_path_str
+
+    config = AgentRunAgentSchema(
+        name=agent_name,
+        entrypoint=entrypoint,
+        platform=ContainerRuntime.DEFAULT_PLATFORM,
+        container_runtime=runtime.runtime,
+    )
+    
+    project_config = merge_agent_config(config_path, agent_name, config)
+    save_config(project_config, config_path)
+
+    return ConfigureResult(
+        config_path=config_path,
+        dockerfile_path=dockerfile_path,
+        dockerignore_path=dockerignore_path if dockerignore_path.exists() else None,
+        runtime=runtime.get_name(),
+        region=region,
+    )
+
+def validate_agent_name(name: str) -> Tuple[bool, str]:
+    """Check if name matches the pattern [a-zA-Z][a-zA-Z0-9_]{0,47}.
+
+    This pattern requires:
+    - First character: letter (a-z or A-Z)
+    - Remaining 0-47 characters: letters, digits, or underscores
+    - Total maximum length: 48 characters
+
+    Args:
+        name: The string to validate
+
+    Returns:
+        bool: True if the string matches the pattern, False otherwise
+    """
+    match = bool(re.match(AGENT_NAME_REGEX, name))
+
+    if match:
+        return match, ""
+    else:
+        return match, AGENT_NAME_ERROR

agentrun_operation_sdk/operations/runtime/launch.py

@@ -0,0 +1,82 @@
+import logging
+from typing import Optional
+from pathlib import Path
+from ...utils.runtime.container import ContainerRuntime
+from .models import LaunchResult
+from ...utils.runtime.config import load_config
+
+log = logging.getLogger(__name__)
+
+def launch_agentrun(
+    config_path: Path,
+    agent_name: Optional[str] = None,
+    local: bool = False,
+    env_vars: Optional[dict] = None,
+) -> LaunchResult:
+    """Launch Bedrock AgentCore locally or to cloud.
+
+    Args:
+        agent_name: Name of agent to launch (for project configurations)
+        local: Whether to run locally
+        env_vars: Environment variables to pass to local container (dict of key-value pairs)
+
+    Returns:
+        LaunchResult model with launch details
+    """
+    project_config = load_config(config_path)
+    agent_config = project_config.get_agent_config(agent_name)
+
+    mode = "locally" if local else "to cloud"
+    log.info("Launching Bedrock AgentCore agent '%s' %s", agent_config.name, mode)
+
+    # Validate configuration
+    errors = agent_config.validate(for_local=local)
+    if errors:
+        raise ValueError(f"Invalid configuration: {', '.join(errors)}")
+    
+    runtime = ContainerRuntime(agent_config.container_runtime)
+
+    if local and not runtime.has_local_runtime:
+        raise RuntimeError(
+            "Cannot run locally - no container runtime available\n"
+            "💡 Recommendation: Use CodeBuild for cloud deployment\n"
+            "💡 Run 'agentcore launch' (without --local) for CodeBuild deployment\n"
+            "💡 For local runs, please install Docker, Finch, or Podman"
+        )
+    
+    agentrun_name = agent_config.name
+
+    tag = f"agentrun-{agentrun_name}:latest"
+
+    build_dir = config_path.parent
+    success, output = runtime.build(build_dir, tag)
+
+    if not success:
+        error_lines = output[-10:] if len(output) > 10 else output
+        error_message = " ".join(error_lines)
+
+        # Check if this is a container runtime issue and suggest CodeBuild
+        if "No container runtime available" in error_message:
+            raise RuntimeError(
+                f"Build failed: {error_message}\n"
+                "💡 Recommendation: Use CodeBuild for building containers in the cloud\n"
+                "💡 Run 'agentcore launch' (default) for CodeBuild deployment"
+            )
+        else:
+            raise RuntimeError(f"Build failed: {error_message}")
+
+    log.info("Docker image built: %s", tag)
+
+    if local:
+        # Return info for local deployment
+        return LaunchResult(
+            mode="local",
+            tag=tag,
+            port=8080,
+            runtime=runtime,
+            env_vars=env_vars,
+        )
+    else:
+        raise RuntimeError(
+                "Build failed: only support local build\n"
+            )

agentrun_operation_sdk/operations/runtime/models.py

@@ -0,0 +1,31 @@
+from pathlib import Path
+from typing import Dict, List, Optional
+from pydantic import BaseModel, Field, ConfigDict
+from ...utils.runtime.container import ContainerRuntime
+
+# Launch operation models
+class LaunchResult(BaseModel):
+    """Result of launch operation."""
+
+    mode: str = Field(..., description="Launch mode: local, cloud, or codebuild")
+    tag: str = Field(..., description="Docker image tag")
+    env_vars: Optional[Dict[str, str]] = Field(default=None, description="Environment variables for local deployment")
+
+    # Local mode fields
+    port: Optional[int] = Field(default=None, description="Port for local deployment")
+    runtime: Optional[ContainerRuntime] = Field(default=None, description="Container runtime instance")
+
+    # Build output (optional)
+    build_output: Optional[List[str]] = Field(default=None, description="Docker build output")
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)  # For runtime field
+
+# Configure operation models
+class ConfigureResult(BaseModel):
+    """Result of configure operation."""
+
+    config_path: Path = Field(..., description="Path to configuration file")
+    dockerfile_path: Path = Field(..., description="Path to generated Dockerfile")
+    dockerignore_path: Optional[Path] = Field(None, description="Path to generated .dockerignore")
+    runtime: str = Field(..., description="Container runtime name")
+    region: str = Field(..., description="HW Cloud region")