strands-compose-agentcore 0.1.0__py3-none-any.whl

strands_compose_agentcore/__init__.py

@@ -0,0 +1,39 @@
+"""strands-compose-agentcore — toolkit for deploying strands-compose agents on AgentCore.
+
+Install this package and use :func:`create_app` to wrap a strands-compose
+YAML config as a ``BedrockAgentCoreApp``.  Assign the result to a
+module-level ``app`` in your entry script for ``agentcore deploy`` to
+discover, or call ``app.run()`` for local development.
+
+Example::
+
+    from pathlib import Path
+
+    from strands_compose_agentcore import create_app
+
+    app = create_app(Path(__file__).parent / "config.yaml")
+"""
+
+from __future__ import annotations
+
+from .app import create_app
+from .client import (
+    AccessDeniedError,
+    AgentCoreClient,
+    AgentCoreClientError,
+    ClientConnectionError,
+    LocalClient,
+    RetryConfig,
+    ThrottledError,
+)
+
+__all__ = [
+    "AccessDeniedError",
+    "AgentCoreClient",
+    "AgentCoreClientError",
+    "ClientConnectionError",
+    "LocalClient",
+    "RetryConfig",
+    "ThrottledError",
+    "create_app",
+]

strands_compose_agentcore/_utils.py

@@ -0,0 +1,39 @@
+"""Internal shared utilities — ANSI helpers and TTY detection.
+
+This module provides terminal colour helpers used by both the CLI and
+client subpackages.  It is private (underscore prefix) and should not
+be imported by external code.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TextIO
+
+
+def _stream_is_tty(stream: TextIO) -> bool:
+    """Check whether a stream is connected to a terminal.
+
+    Args:
+        stream: File-like object to check.
+
+    Returns:
+        True if the stream is a TTY.
+    """
+    return hasattr(stream, "isatty") and stream.isatty()
+
+
+def ansi(code: str, stream: TextIO = sys.stderr) -> str:
+    """Return an ANSI escape sequence if *stream* is a TTY, else empty string.
+
+    Evaluates TTY status at call time — safe to use in tests where
+    streams may be redirected after import.
+
+    Args:
+        code: ANSI escape code (e.g. ``"31"`` for red).
+        stream: Stream to check for TTY support.
+
+    Returns:
+        The escape sequence or an empty string.
+    """
+    return f"\033[{code}m" if _stream_is_tty(stream) else ""

strands_compose_agentcore/app.py

@@ -0,0 +1,263 @@
+"""BedrockAgentCore app factory for strands-compose agents.
+
+Provides :func:`create_app` — the main API for building a
+``BedrockAgentCoreApp`` from a strands-compose YAML config.
+Install this package and call the factory from your own entry script.
+
+The app uses two-phase resolution:
+
+- **Infrastructure** (models, MCP, session managers) is resolved once
+  at boot via ``resolve_infra()``.
+- **Session** (agents, orchestrations, entry point) is resolved once
+  per session via ``load_session(config, infra, session_id=...)``.
+  The session ID comes from the AgentCore runtime header
+  ``X-Amzn-Bedrock-AgentCore-Runtime-Session-Id``.
+- Follow-up prompts within the same session reuse the same agents and
+  ``EventQueue`` — only the queue is flushed between turns.
+
+Example::
+
+    from strands_compose_agentcore import create_app
+
+    app = create_app("config.yaml")
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from bedrock_agentcore import BedrockAgentCoreApp
+from bedrock_agentcore.runtime.context import BedrockAgentCoreContext
+from starlette.middleware.cors import CORSMiddleware
+from starlette.types import StatelessLifespan
+from strands_compose import (
+    AppConfig,
+    ResolvedInfra,
+    StreamEvent,
+    load_config,
+    resolve_infra,
+)
+from strands_compose.startup import validate_mcp
+
+from .session import SessionState, resolve_session, stream_invocation, validate_session_id
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Lifespan
+# ---------------------------------------------------------------------------
+
+
+def _make_lifespan(
+    app_config: AppConfig,
+    infra: ResolvedInfra,
+) -> StatelessLifespan[BedrockAgentCoreApp]:
+    """Return an ASGI lifespan that starts MCP infrastructure.
+
+    On startup the MCP lifecycle is entered (servers started, connectivity
+    probed).  Agents are **not** created here — they are created lazily on
+    the first invocation so the session ID from the AgentCore header can be
+    forwarded to ``load_session``.
+
+    On shutdown the MCP lifecycle context manager stops clients first, then
+    servers.
+
+    Args:
+        app_config: Validated AppConfig from YAML.
+        infra: Resolved infrastructure (models, MCP, session manager).
+
+    Returns:
+        An ASGI lifespan context manager.
+    """
+
+    @asynccontextmanager
+    async def _lifespan(app: BedrockAgentCoreApp) -> AsyncIterator[None]:
+        async with infra.mcp_lifecycle:
+            report = await validate_mcp(infra)
+            report.print_summary()
+
+            app.state.app_config = app_config
+            app.state.infra = infra
+            app.state.session = None  # lazily populated on first invoke
+            app.state.session_id = None  # bound on first invoke
+
+            logger.info("infrastructure ready, waiting for first invocation")
+            yield
+
+    return _lifespan
+
+
+# ---------------------------------------------------------------------------
+# App factory
+# ---------------------------------------------------------------------------
+
+
+def create_app(
+    config: str | Path | list[str | Path] | AppConfig,
+    infra: ResolvedInfra | None = None,
+    *,
+    cors_origins: list[str] | None = None,
+    suppress_runtime_logging: bool = False,
+    invocation_timeout: float | None = None,
+) -> BedrockAgentCoreApp:
+    """Create a BedrockAgentCoreApp with full event streaming.
+
+    This is the main API of strands-compose-agentcore.  Pass a YAML config
+    path (or list of paths) and the factory handles ``load_config`` and
+    ``resolve_infra`` internally.  For advanced use, pass a pre-built
+    ``AppConfig`` and optional ``ResolvedInfra``.
+
+    Infrastructure is resolved once at boot.  Session state (agents,
+    orchestrations) is resolved lazily on the first invocation using
+    the session ID from the ``X-Amzn-Bedrock-AgentCore-Runtime-Session-Id``
+    header.  Follow-up prompts reuse the same session state.
+
+    Args:
+        config: YAML file path, raw YAML string, list of either, or
+            a pre-built AppConfig.  Strings are auto-detected as file
+            paths if the file exists, otherwise parsed as inline YAML.
+        infra: Pre-resolved infrastructure.  When ``None`` (the default),
+            ``resolve_infra()`` is called automatically.
+        cors_origins: List of allowed CORS origins.
+        suppress_runtime_logging: Remove the JSON log handler that
+            ``BedrockAgentCoreApp`` installs on the
+            ``bedrock_agentcore.app`` logger.  Useful in local
+            development to avoid duplicate log lines.  In production
+            on AgentCore Runtime, leave this ``False`` so CloudWatch
+            receives structured JSON logs.
+        invocation_timeout: Maximum seconds to wait for the agent to
+            finish a single invocation.  ``None`` (the default) means
+            no timeout — the agent runs until completion or failure.
+
+    Returns:
+        Configured BedrockAgentCoreApp ready to run.
+    """
+    # Resolve config from path/string if needed.
+    if isinstance(config, (str, Path, list)):
+        app_config = load_config(config)
+    else:
+        app_config = config
+
+    # Validate that an entry point is defined.
+    if not getattr(app_config, "entry", None):
+        raise ValueError(
+            "config has no 'entry' defined — set 'entry: <agent_name>' in your YAML config"
+        )
+
+    # Resolve infrastructure if not provided.
+    if infra is None:
+        infra = resolve_infra(app_config)
+
+    _invocation_timeout = invocation_timeout  # capture for closure
+
+    app = BedrockAgentCoreApp(
+        lifespan=_make_lifespan(app_config, infra),
+    )
+
+    if suppress_runtime_logging:
+        logging.getLogger("bedrock_agentcore.app").handlers.clear()
+
+    if cors_origins:
+        app.add_middleware(
+            CORSMiddleware,  # type: ignore[arg-type]
+            allow_origins=cors_origins,
+            allow_methods=["*"],
+            allow_headers=["*"],
+        )
+
+    @app.entrypoint
+    async def invoke(payload: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
+        """Entrypoint for ``/invocations`` POST requests.
+
+        On the first call, resolves agents using the session ID from the
+        AgentCore runtime header and caches the result.  Subsequent calls
+        reuse the same agents — only the event queue is flushed.
+
+        Concurrent invocations within the same session are rejected with
+        an error event.  The ``/ping`` endpoint reports ``HEALTHY_BUSY``
+        while an invocation is in progress so AgentCore Runtime can
+        back off.
+
+        Args:
+            payload: Request payload.  Required key: ``prompt``.
+
+        Yields:
+            JSON-serializable dicts, one per StreamEvent.
+        """
+        prompt = payload.get("prompt")
+        if not prompt:
+            yield StreamEvent(
+                type="error",
+                agent_name="",
+                timestamp=datetime.now(tz=timezone.utc),
+                data={"message": "missing or empty required field: prompt"},
+            ).asdict()
+            return
+
+        session_id = BedrockAgentCoreContext.get_session_id()
+
+        try:
+            validate_session_id(session_id)
+        except ValueError as exc:
+            logger.warning("session_id=<%s> | %s", session_id, exc)
+            yield StreamEvent(
+                type="error",
+                agent_name="",
+                timestamp=datetime.now(tz=timezone.utc),
+                data={"message": str(exc)},
+            ).asdict()
+            return
+
+        # Resolve session first (sync — no await, no context switch).
+        session: SessionState | None = app.state.session
+        if session is None or app.state.session_id != session_id:
+            if app.state.session_id is not None:
+                logger.info(
+                    "session_id=<%s> | new session replaces previous session_id=<%s>",
+                    session_id,
+                    app.state.session_id,
+                )
+            session = resolve_session(
+                app.state.app_config,
+                app.state.infra,
+                session_id,
+            )
+            app.state.session = session
+            app.state.session_id = session_id
+
+        # SAFETY: asyncio is single-threaded.  No await exists between
+        # locked() and the async-with acquire below, so no other
+        # coroutine can acquire the lock in between.
+        if session.invocation_lock.locked():
+            logger.warning(
+                "session_id=<%s> | invocation rejected, agent already running",
+                session_id,
+            )
+            yield StreamEvent(
+                type="error",
+                agent_name="",
+                timestamp=datetime.now(tz=timezone.utc),
+                data={"message": "agent is already running, try again later"},
+            ).asdict()
+            return
+
+        task_id = app.add_async_task("invoke")
+        try:
+            async with session.invocation_lock:
+                async for event in stream_invocation(
+                    session.resolved,
+                    session.events,
+                    prompt,
+                    invocation_timeout=_invocation_timeout,
+                ):
+                    yield event.asdict()
+        finally:
+            app.complete_async_task(task_id)
+
+    return app

strands_compose_agentcore/cli/__init__.py

@@ -0,0 +1,141 @@
+"""CLI entry point for strands-compose-agentcore.
+
+Provides:
+- ``dev`` — server + REPL in one terminal
+- ``client local|remote`` — REPL for local or deployed agents
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import NoReturn
+
+from .client import cmd_client
+from .dev import cmd_dev
+from .utils import CLIError, red, reset
+
+
+class _ColorArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that prints errors in red with surrounding newlines."""
+
+    def error(self, message: str) -> NoReturn:
+        """Print a red error message and exit.
+
+        Args:
+            message: Error description from argparse.
+        """
+        print(
+            f"\n{red()}{self.prog}: error:\n {message}{reset()}\n",
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Build the argument parser with all subcommands.
+
+    Returns:
+        Configured ArgumentParser.
+    """
+    parser = _ColorArgumentParser(
+        prog="sca",
+        description="CLI toolkit for strands-compose agents on AgentCore.",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    # -- dev (own implementation) ------------------------------------------
+    dev_parser = subparsers.add_parser(
+        "dev",
+        help="Start server + REPL in one terminal.",
+    )
+    dev_parser.add_argument(
+        "--config",
+        default=None,
+        help="Path to strands-compose YAML config (default: ./config.yaml).",
+    )
+    dev_parser.add_argument(
+        "--port",
+        type=int,
+        default=8080,
+        help="Port for the HTTP server (default: 8080).",
+    )
+    dev_parser.add_argument(
+        "--session-id",
+        default=None,
+        help="Session ID for the REPL client",
+    )
+
+    # -- client (own implementation) ---------------------------------------
+    client_parser = subparsers.add_parser(
+        "client",
+        help="Interactive REPL client for local or remote agents.",
+    )
+    client_sub = client_parser.add_subparsers(dest="client_command")
+
+    local_parser = client_sub.add_parser(
+        "local",
+        help="Connect to a local server.",
+    )
+    local_parser.add_argument(
+        "--url",
+        default="http://localhost:8080/invocations",
+        help="URL of the /invocations endpoint.",
+    )
+    local_parser.add_argument(
+        "--session-id",
+        default=None,
+        help="Session ID for the AgentCore header.",
+    )
+    remote_parser = client_sub.add_parser(
+        "remote",
+        help="Connect to a deployed AgentCore Runtime agent.",
+    )
+    remote_parser.add_argument(
+        "--arn",
+        required=True,
+        help="Full ARN of the deployed agent runtime.",
+    )
+    remote_parser.add_argument(
+        "--region",
+        default=None,
+        help="AWS region override.",
+    )
+    remote_parser.add_argument(
+        "--session-id",
+        default=None,
+        help="AgentCore session ID.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Parse arguments and dispatch to the appropriate handler.
+
+    Args:
+        argv: Command-line arguments.  Defaults to ``sys.argv[1:]``.
+    """
+    if argv is None:
+        argv = sys.argv[1:]
+
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "dev":
+            cmd_dev(args)
+
+        elif args.command == "client":
+            cmd_client(args, parser)
+
+        else:
+            parser.print_help()
+            sys.exit(1)
+    except CLIError as exc:
+        print(f"\n{red()}{exc.message}{reset()}\n", file=sys.stderr)
+        sys.exit(exc.code)
+
+
+if __name__ == "__main__":
+    main()

strands_compose_agentcore/cli/client.py

@@ -0,0 +1,26 @@
+"""Client subcommands — local and remote REPL."""
+
+from __future__ import annotations
+
+import argparse
+
+from ..client import AgentCoreClient, LocalClient
+
+
+def cmd_client(args: argparse.Namespace, parser: argparse.ArgumentParser) -> None:
+    """Handle the ``client`` subcommand.
+
+    Args:
+        args: Parsed CLI arguments.
+        parser: Root parser (for --help fallback).
+    """
+    if args.client_command == "local":
+        client = LocalClient(url=args.url, session_id=args.session_id)
+        client.repl()
+
+    elif args.client_command == "remote":
+        client = AgentCoreClient(args.arn, region=args.region)
+        client.repl(session_id=args.session_id)
+
+    else:
+        parser.parse_args(["client", "--help"])

strands_compose_agentcore/cli/dev.py

@@ -0,0 +1,125 @@
+"""Dev command — server + REPL in one terminal."""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import socket
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+from .. import create_app
+from ..client.local import LocalClient
+from .utils import CLIError
+
+logger = logging.getLogger(__name__)
+
+_SERVER_STARTUP_TIMEOUT = 30.0
+_SERVER_POLL_INTERVAL = 0.5
+
+
+def cmd_dev(args: argparse.Namespace) -> None:
+    """Handle the ``dev`` subcommand.
+
+    Args:
+        args: Parsed CLI arguments (config, port, session_id).
+
+    Raises:
+        CLIError: Config file not found.
+    """
+    config_path = args.config or "config.yaml"
+    if not Path(config_path).is_file():
+        raise CLIError(f"Error: config not found: {config_path}")
+
+    run_dev(config_path, port=args.port, session_id=args.session_id)
+
+
+def run_dev(
+    config: str | Path,
+    *,
+    session_id: str | None = None,
+    port: int = 8080,
+) -> None:
+    """Start ASGI server in a daemon thread and run the REPL in main thread.
+
+    Uses ``app.run()`` which internally calls ``uvicorn.run(self, ...)``
+    with sensible defaults (host auto-detection, log levels, etc.).
+    The daemon thread auto-terminates when the process exits.
+
+    Args:
+        config: Path to strands-compose YAML config file.
+        port: Port for the HTTP server.
+        session_id: Session ID for the REPL client.  When ``None``
+            (the default), ``LocalClient`` uses ``DEFAULT_SESSION_ID``.
+
+    Raises:
+        CLIError: Port already in use or server startup timeout.
+    """
+    app = create_app(
+        config,
+        cors_origins=["*"],
+        suppress_runtime_logging=True,
+    )
+
+    if _port_in_use(port):
+        raise CLIError(
+            f"Error: port {port} is already in use.\n"
+            " Stop the other process or use --port <number>."
+        )
+
+    # Start the server in a daemon thread so it doesn't block the REPL
+    server_thread = threading.Thread(
+        target=app.run,
+        kwargs={"port": port},
+        daemon=True,
+        name="dev-server",
+    )
+    server_thread.start()
+
+    ping_url = f"http://localhost:{port}/ping"
+    if not _wait_for_server(ping_url, timeout=_SERVER_STARTUP_TIMEOUT):
+        raise CLIError(f"Error: server did not start within {_SERVER_STARTUP_TIMEOUT} seconds")
+
+    url = f"http://localhost:{port}/invocations"
+    client = LocalClient(url=url, session_id=session_id)
+    client.repl()
+
+
+def _wait_for_server(ping_url: str, timeout: float) -> bool:
+    """Poll the /ping endpoint until the server responds or timeout expires.
+
+    Args:
+        ping_url: URL of the server's health-check endpoint.
+        timeout: Maximum seconds to wait.
+
+    Returns:
+        True if server responded, False on timeout.
+    """
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        try:
+            # This urlopen call is safe - we just ping our local server
+            # Security alert is false positive
+            with urllib.request.urlopen(ping_url, timeout=2):  # nosec: B310
+                return True
+        except (OSError, urllib.error.URLError):
+            time.sleep(_SERVER_POLL_INTERVAL)
+    return False
+
+
+def _port_in_use(port: int, host: str = "127.0.0.1") -> bool:
+    """Check whether a TCP port is already bound.
+
+    Args:
+        port: Port number to check.
+        host: Address to probe.
+
+    Returns:
+        True if the port is in use.
+    """
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(1)
+        return sock.connect_ex((host, port)) == 0

strands_compose_agentcore/cli/utils.py

@@ -0,0 +1,44 @@
+"""Shared CLI utilities: ANSI colour helpers and exception types."""
+
+from __future__ import annotations
+
+import sys
+
+from .._utils import ansi  # noqa: F401 — re-exported for cli consumers
+
+# ---------------------------------------------------------------------------
+# Colours — call-time TTY detection via ansi()
+# ---------------------------------------------------------------------------
+
+
+def red() -> str:
+    """Return ANSI red escape for stderr."""
+    return ansi("31", sys.stderr)
+
+
+def reset() -> str:
+    """Return ANSI reset escape for stderr."""
+    return ansi("0", sys.stderr)
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class CLIError(Exception):
+    """Raised by CLI commands to signal a user-facing error.
+
+    ``main()`` catches this, prints the message to stderr, and calls
+    ``sys.exit(code)`` — keeping command handlers testable without
+    catching ``SystemExit``.
+
+    Args:
+        message: Human-readable error message.
+        code: Exit code (default ``1``).
+    """
+
+    def __init__(self, message: str, code: int = 1) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code