agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/knowledge_base/hydrate_data_sources.py

@@ -0,0 +1,59 @@
+"""Hydrate KB data-source ids after deploy (port of ``operations/knowledge-base/hydrate-data-sources.ts``)."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from agentcore.aws import bedrock_agent
+
+_DS_SUFFIX = re.compile(r"_ds_([0-9a-f]+)$")
+
+
+def uri_hash_prefix(uri: str) -> str:
+    """First 8 hex chars of SHA-256(uri) — must stay byte-equivalent to the L3's DS naming."""
+    return hashlib.sha256(uri.encode("utf-8")).hexdigest()[:8]
+
+
+def _get(obj: Any, camel: str, snake: str) -> Any:
+    return obj.get(camel) if isinstance(obj, Mapping) else getattr(obj, snake, None)
+
+
+def hydrate_knowledge_base_data_sources(
+    *, knowledge_bases: Mapping[str, dict[str, Any]], knowledge_base_specs: Sequence[Any], region: str
+) -> None:
+    """Fill ``dataSources`` (in place) for KB records whose CFN outputs carried none.
+
+    Falls back to ``ListDataSources`` and pairs each deployed DS with its local spec by the URI-hash
+    suffix the L3 puts in every data source name.
+    """
+    specs_by_name = {_get(s, "name", "name"): s for s in knowledge_base_specs}
+    for name, deployed in knowledge_bases.items():
+        if deployed.get("dataSources"):
+            continue
+        spec = specs_by_name.get(name)
+        if spec is None:
+            continue
+        summaries = bedrock_agent.list_data_sources(region=region, knowledge_base_id=deployed["knowledgeBaseId"])
+        id_by_hash: dict[str, str] = {}
+        for summary in summaries:
+            ds_id, ds_name = summary.get("dataSourceId"), summary.get("name")
+            if not ds_id or not ds_name:
+                continue
+            match = _DS_SUFFIX.search(ds_name)
+            if match:
+                id_by_hash[match.group(1)] = ds_id
+        hydrated = []
+        for local_ds in _get(spec, "dataSources", "data_sources") or []:
+            if _get(local_ds, "type", "type") != "S3":
+                continue
+            uri = _get(local_ds, "uri", "uri")
+            ds_id = id_by_hash.get(uri_hash_prefix(uri))
+            if ds_id:
+                hydrated.append({"dataSourceId": ds_id, "uri": uri})
+        deployed["dataSources"] = hydrated
+
+
+__all__ = ["hydrate_knowledge_base_data_sources", "uri_hash_prefix"]

agentcore/operations/mcp/__init__.py

@@ -0,0 +1,4 @@
+"""MCP operations (port of operations/mcp). Upstream removed the facades: use the primitives directly.
+
+``agentcore.primitives.gateway`` and ``agentcore.primitives.gateway_target`` own gateway / target creation.
+"""

agentcore/operations/memory/__init__.py

@@ -0,0 +1,13 @@
+"""Memory record operations (port of src/cli/operations/memory)."""
+
+from agentcore.operations.memory._records import MemoryRecordEntry
+from agentcore.operations.memory.list_memory_records import ListMemoryRecordsResult, list_memory_records
+from agentcore.operations.memory.retrieve_memory_records import RetrieveMemoryRecordsResult, retrieve_memory_records
+
+__all__ = [
+    "ListMemoryRecordsResult",
+    "MemoryRecordEntry",
+    "RetrieveMemoryRecordsResult",
+    "list_memory_records",
+    "retrieve_memory_records",
+]

agentcore/operations/memory/_records.py

@@ -0,0 +1,72 @@
+"""Shared helpers for the memory record operations."""
+
+from datetime import UTC, datetime
+from typing import Any, TypedDict
+
+from agentcore.aws._aws_errors import aws_error_name
+from agentcore.aws.agentcore import _create_agentcore_client
+from agentcore.lib.errors.types import ResourceNotFoundError, ValidationError, to_error
+from agentcore.lib.result import Err
+
+
+class MemoryRecordEntry(TypedDict):
+    memoryRecordId: str
+    content: str | None
+    memoryStrategyId: str
+    namespaces: list[str]
+    createdAt: str
+    score: float | None
+    metadata: dict[str, str]
+
+
+def create_client(region: str) -> Any:
+    return _create_agentcore_client(region)
+
+
+def check_namespace(namespace: str | None, namespace_path: str | None) -> Err[Exception] | None:
+    """Exactly one of namespace / namespace_path; empty strings count as not provided."""
+    if namespace and namespace_path:
+        return Err(ValidationError("'namespace' and 'namespacePath' are mutually exclusive."))
+    if not namespace and not namespace_path:
+        return Err(ValidationError("Either 'namespace' or 'namespacePath' must be provided."))
+    return None
+
+
+def namespace_params(namespace: str | None, namespace_path: str | None) -> dict[str, str]:
+    return {"namespace": namespace} if namespace else {"namespacePath": namespace_path or ""}
+
+
+def _iso(value: Any) -> str:
+    """Like JS Date.toISOString(): UTC with millisecond precision and a Z suffix."""
+    if value is None:
+        return "unknown"
+    if isinstance(value, datetime):
+        if value.tzinfo is not None:
+            value = value.astimezone(UTC)
+        return value.strftime("%Y-%m-%dT%H:%M:%S.") + f"{value.microsecond // 1000:03d}Z"
+    return str(value)
+
+
+def to_entries(summaries: list[dict[str, Any]] | None) -> list[MemoryRecordEntry]:
+    return [
+        {
+            "memoryRecordId": r.get("memoryRecordId") or "unknown",
+            "content": (r.get("content") or {}).get("text"),
+            "memoryStrategyId": r.get("memoryStrategyId") or "unknown",
+            "namespaces": list(r.get("namespaces") or []),
+            "createdAt": _iso(r.get("createdAt")),
+            "score": r.get("score"),
+            "metadata": {k: (v or {}).get("stringValue") or "" for k, v in (r.get("metadata") or {}).items()},
+        }
+        for r in summaries or []
+    ]
+
+
+def map_error(exc: BaseException, memory_id: str) -> Err[Exception]:
+    if aws_error_name(exc) == "ResourceNotFoundException":
+        return Err(ResourceNotFoundError(f"Memory '{memory_id}' not found. It may not have been deployed yet."))
+    return Err(to_error(exc))  # type: ignore[arg-type]
+
+
+def drop_none(params: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in params.items() if v is not None}

agentcore/operations/memory/list_memory_records.py

@@ -0,0 +1,45 @@
+"""List memory records of a deployed memory (port of list-memory-records.ts)."""
+
+from typing import Any
+
+from agentcore.lib.result import Err, Ok
+from agentcore.operations.memory import _records
+from agentcore.operations.memory._records import MemoryRecordEntry
+
+ListMemoryRecordsResult = Ok[dict[str, Any]] | Err[Exception]
+
+
+def list_memory_records(
+    *,
+    region: str,
+    memory_id: str,
+    namespace: str | None = None,
+    namespace_path: str | None = None,
+    memory_strategy_id: str | None = None,
+    max_results: int = 50,
+    next_token: str | None = None,
+) -> ListMemoryRecordsResult:
+    """Exactly one of ``namespace`` (exact) or ``namespace_path`` (path prefix) must be given.
+
+    Returns ``Ok({"records": [...], "nextToken": ...})``.
+    """
+    invalid = _records.check_namespace(namespace, namespace_path)
+    if invalid is not None:
+        return invalid
+    client = _records.create_client(region)
+    try:
+        response = client.list_memory_records(
+            **_records.drop_none(
+                {
+                    "memoryId": memory_id,
+                    **_records.namespace_params(namespace, namespace_path),
+                    "memoryStrategyId": memory_strategy_id,
+                    "maxResults": max_results,
+                    "nextToken": next_token,
+                }
+            )
+        )
+        records: list[MemoryRecordEntry] = _records.to_entries(response.get("memoryRecordSummaries"))
+        return Ok({"records": records, "nextToken": response.get("nextToken")})
+    except Exception as exc:  # noqa: BLE001
+        return _records.map_error(exc, memory_id)

agentcore/operations/memory/retrieve_memory_records.py

@@ -0,0 +1,52 @@
+"""Semantic search over memory records (port of retrieve-memory-records.ts)."""
+
+from typing import Any
+
+from agentcore.lib.result import Err, Ok
+from agentcore.operations.memory import _records
+
+RetrieveMemoryRecordsResult = Ok[dict[str, Any]] | Err[Exception]
+
+
+def retrieve_memory_records(
+    *,
+    region: str,
+    memory_id: str,
+    search_query: str,
+    namespace: str | None = None,
+    namespace_path: str | None = None,
+    memory_strategy_id: str | None = None,
+    top_k: int | None = None,
+    max_results: int | None = None,
+    next_token: str | None = None,
+) -> RetrieveMemoryRecordsResult:
+    """Exactly one of ``namespace`` or ``namespace_path`` must be given.
+
+    Returns ``Ok({"records": [...], "nextToken": ...})``.
+    """
+    invalid = _records.check_namespace(namespace, namespace_path)
+    if invalid is not None:
+        return invalid
+    client = _records.create_client(region)
+    try:
+        response = client.retrieve_memory_records(
+            **_records.drop_none(
+                {
+                    "memoryId": memory_id,
+                    **_records.namespace_params(namespace, namespace_path),
+                    "searchCriteria": _records.drop_none(
+                        {"searchQuery": search_query, "memoryStrategyId": memory_strategy_id, "topK": top_k}
+                    ),
+                    "maxResults": max_results,
+                    "nextToken": next_token,
+                }
+            )
+        )
+        return Ok(
+            {
+                "records": _records.to_entries(response.get("memoryRecordSummaries")),
+                "nextToken": response.get("nextToken"),
+            }
+        )
+    except Exception as exc:  # noqa: BLE001
+        return _records.map_error(exc, memory_id)

agentcore/operations/node/__init__.py

@@ -0,0 +1,15 @@
+from agentcore.operations.node.setup import (
+    NodeSetupResult,
+    NodeSetupStatus,
+    check_npm_available,
+    install_node_dependencies,
+    setup_node_project,
+)
+
+__all__ = [
+    "NodeSetupResult",
+    "NodeSetupStatus",
+    "check_npm_available",
+    "install_node_dependencies",
+    "setup_node_project",
+]

agentcore/operations/node/setup.py

@@ -0,0 +1,36 @@
+"""Node project setup (port of src/cli/operations/node/setup.ts)."""
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from agentcore.lib import check_subprocess, run_subprocess_capture
+
+NodeSetupStatus = Literal["success", "npm_not_found", "install_failed"]
+
+
+@dataclass
+class NodeSetupResult:
+    status: NodeSetupStatus
+    error: str | None = None
+
+
+def check_npm_available() -> bool:
+    return check_subprocess("npm", ["--version"])
+
+
+def install_node_dependencies(project_dir: str) -> NodeSetupResult:
+    """`npm install` (not `npm ci`): fresh scaffolds don't ship a lockfile."""
+    result = run_subprocess_capture("npm", ["install"], cwd=project_dir)
+    if result.code == 0:
+        return NodeSetupResult("success")
+    return NodeSetupResult("install_failed", result.stderr or result.stdout)
+
+
+def setup_node_project(project_dir: str) -> NodeSetupResult:
+    """Run `npm install`. A no-op when AGENTCORE_SKIP_INSTALL is set."""
+    if os.environ.get("AGENTCORE_SKIP_INSTALL"):
+        return NodeSetupResult("success")
+    if not check_npm_available():
+        return NodeSetupResult("npm_not_found", "'npm' not found. Install Node.js from https://nodejs.org/")
+    return install_node_dependencies(project_dir)

agentcore/operations/python/__init__.py

@@ -0,0 +1,17 @@
+from agentcore.operations.python.setup import (
+    PythonSetupResult,
+    PythonSetupStatus,
+    check_uv_available,
+    create_venv,
+    install_dependencies,
+    setup_python_project,
+)
+
+__all__ = [
+    "PythonSetupResult",
+    "PythonSetupStatus",
+    "check_uv_available",
+    "create_venv",
+    "install_dependencies",
+    "setup_python_project",
+]

agentcore/operations/python/setup.py

@@ -0,0 +1,47 @@
+"""Python project setup with uv (port of src/cli/operations/python/setup.ts)."""
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from agentcore.lib import check_subprocess, run_subprocess_capture
+
+PythonSetupStatus = Literal["success", "uv_not_found", "venv_failed", "install_failed"]
+
+
+@dataclass
+class PythonSetupResult:
+    status: PythonSetupStatus
+    error: str | None = None
+
+
+def check_uv_available() -> bool:
+    return check_subprocess("uv", ["--version"])
+
+
+def create_venv(project_dir: str, venv_name: str = ".venv") -> PythonSetupResult:
+    result = run_subprocess_capture("uv", ["venv", venv_name], cwd=project_dir)
+    if result.code == 0:
+        return PythonSetupResult("success")
+    return PythonSetupResult("venv_failed", result.stderr or result.stdout)
+
+
+def install_dependencies(project_dir: str) -> PythonSetupResult:
+    result = run_subprocess_capture("uv", ["sync"], cwd=project_dir)
+    if result.code == 0:
+        return PythonSetupResult("success")
+    return PythonSetupResult("install_failed", result.stderr or result.stdout)
+
+
+def setup_python_project(project_dir: str, venv_name: str = ".venv") -> PythonSetupResult:
+    """Create a venv and install dependencies. A no-op when AGENTCORE_SKIP_INSTALL is set."""
+    if os.environ.get("AGENTCORE_SKIP_INSTALL"):
+        return PythonSetupResult("success")
+    if not check_uv_available():
+        return PythonSetupResult(
+            "uv_not_found", "uv command not found. Install it with: curl -LsSf https://astral.sh/uv/install.sh | sh"
+        )
+    venv = create_venv(project_dir, venv_name)
+    if venv.status != "success":
+        return venv
+    return install_dependencies(project_dir)

agentcore/operations/resolve_agent.py

@@ -0,0 +1,159 @@
+"""Port of src/cli/operations/resolve-agent.ts: pick the deployed runtime/harness a command targets."""
+
+import re
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.aws.agentcore_harness import get_harness
+from agentcore.lib.schemas.io.config_io import ConfigIO
+
+
+@dataclass
+class DeployedProjectConfig:
+    project: Any
+    deployed_state: Any
+    aws_targets: list[Any]
+
+
+@dataclass
+class ResolvedAgent:
+    agent_name: str
+    target_name: str
+    region: str
+    account_id: str
+    runtime_id: str
+
+
+@dataclass
+class ResolveResult:
+    """``{success: true, agent}`` / ``{success: false, error}``."""
+
+    success: bool
+    agent: ResolvedAgent | None = None
+    error: str | None = None
+
+
+def load_deployed_project_config(config_io: ConfigIO | None = None) -> DeployedProjectConfig:
+    config_io = config_io or ConfigIO()
+    return DeployedProjectConfig(
+        project=config_io.read_project_spec(),
+        deployed_state=config_io.read_deployed_state(),
+        aws_targets=config_io.read_aws_deployment_targets(),
+    )
+
+
+def _first_target(context: DeployedProjectConfig) -> tuple[str, Any, Any] | ResolveResult:
+    targets = context.deployed_state.targets or {}
+    if not targets:
+        return ResolveResult(False, error="No deployed targets found. Run `agentcore deploy` first.")
+    name = next(iter(targets))
+    config = next((t for t in context.aws_targets if t.name == name), None)
+    if config is None:
+        return ResolveResult(False, error=f"Target config '{name}' not found in aws-targets")
+    return name, targets[name], config
+
+
+def resolve_agent(context: DeployedProjectConfig, runtime: str | None = None) -> ResolveResult:
+    project = context.project
+    runtimes = project.runtimes or []
+    if not runtimes:
+        return ResolveResult(False, error="No runtimes defined in agentcore.json")
+    names = [r.name for r in runtimes]
+    if not runtime and len(runtimes) > 1:
+        return ResolveResult(False, error=f"Multiple runtimes found. Use --runtime to specify one: {', '.join(names)}")
+    spec = next((r for r in runtimes if r.name == runtime), None) if runtime else runtimes[0]
+    if runtime and spec is None:
+        return ResolveResult(False, error=f"Runtime '{runtime}' not found. Available: {', '.join(names)}")
+    if spec is None:
+        return ResolveResult(False, error="No runtimes defined in agentcore.json")
+
+    first = _first_target(context)
+    if isinstance(first, ResolveResult):
+        return first
+    target_name, target_state, target_config = first
+    resources = target_state.resources if target_state else None
+    agent_state = ((resources.runtimes if resources else None) or {}).get(spec.name)
+    if not agent_state:
+        return ResolveResult(
+            False,
+            error=f"Runtime '{spec.name}' is not deployed to target '{target_name}'. Run 'agentcore deploy' first.",
+        )
+    return ResolveResult(
+        True,
+        agent=ResolvedAgent(
+            agent_name=spec.name,
+            target_name=target_name,
+            region=target_config.region,
+            account_id=target_config.account,
+            runtime_id=agent_state.runtime_id,
+        ),
+    )
+
+
+def resolve_harness(context: DeployedProjectConfig, harness_name: str) -> ResolveResult:
+    harnesses = context.project.harnesses or []
+    spec = next((h for h in harnesses if h.name == harness_name), None)
+    if spec is None:
+        available = [h.name for h in harnesses]
+        return ResolveResult(
+            False,
+            error=f"Harness '{harness_name}' not found. Available: {', '.join(available)}"
+            if available
+            else "No harnesses defined in agentcore.json",
+        )
+    first = _first_target(context)
+    if isinstance(first, ResolveResult):
+        return first
+    target_name, target_state, target_config = first
+    resources = target_state.resources if target_state else None
+    harness_state = ((resources.harnesses if resources else None) or {}).get(harness_name)
+    if not harness_state:
+        return ResolveResult(
+            False,
+            error=f"Harness '{harness_name}' is not deployed to target '{target_name}'. Run 'agentcore deploy' first.",
+        )
+
+    runtime_id: str | None = None
+    if harness_state.agent_runtime_arn:
+        match = re.search(r"runtime/([^/]+)", harness_state.agent_runtime_arn)
+        if match:
+            runtime_id = match.group(1)
+    if not runtime_id:
+        try:
+            get_harness(region=target_config.region, harness_id=harness_state.harness_id)
+            runtime_id = harness_state.harness_id
+        except Exception as exc:  # noqa: BLE001 - reported as a resolution error, as upstream
+            return ResolveResult(False, error=f"Failed to resolve runtime for harness '{harness_name}': {exc}")
+    if not runtime_id:
+        return ResolveResult(
+            False,
+            error=f"Could not resolve runtime ID for harness '{harness_name}'. Re-deploy to populate agentRuntimeArn.",
+        )
+    return ResolveResult(
+        True,
+        agent=ResolvedAgent(
+            agent_name=harness_name,
+            target_name=target_name,
+            region=target_config.region,
+            account_id=target_config.account,
+            runtime_id=runtime_id,
+        ),
+    )
+
+
+def resolve_agent_or_harness(
+    context: DeployedProjectConfig, runtime: str | None = None, harness: str | None = None
+) -> ResolveResult:
+    if harness and runtime:
+        return ResolveResult(False, error="Cannot specify both --harness and --runtime")
+    if harness:
+        return resolve_harness(context, harness)
+    if runtime or (context.project.runtimes or []):
+        return resolve_agent(context, runtime)
+    harnesses = context.project.harnesses or []
+    if not harnesses:
+        return ResolveResult(False, error="No runtimes or harnesses defined in agentcore.json")
+    if len(harnesses) > 1:
+        names = ", ".join(h.name for h in harnesses)
+        return ResolveResult(False, error=f"Multiple harnesses found. Use --harness to specify one: {names}")
+    return resolve_harness(context, harnesses[0].name)

agentcore/operations/session/__init__.py

@@ -0,0 +1,86 @@
+"""Session ID helpers (port of src/cli/operations/session/index.ts)."""
+
+import uuid
+from dataclasses import dataclass
+
+from agentcore.lib.schemas.io.config_io import ConfigIO
+
+
+def generate_session_id() -> str:
+    """New UUID v4 session ID."""
+    return str(uuid.uuid4())
+
+
+@dataclass
+class SessionInfo:
+    session_id: str | None
+    agent_name: str
+    runtime_arn: str
+    target_name: str
+
+
+def _select_target(deployed_state, target_name: str | None) -> str | None:
+    names = list(deployed_state.targets or {})
+    if not names:
+        return None
+    return target_name if target_name is not None else names[0]
+
+
+def get_session_id(
+    agent_name: str, target_name: str | None = None, config_io: ConfigIO | None = None
+) -> SessionInfo | None:
+    config_io = config_io or ConfigIO()
+    deployed_state = config_io.read_deployed_state()
+    aws_targets = config_io.read_aws_deployment_targets()
+    selected = _select_target(deployed_state, target_name)
+    if selected is None:
+        return None
+    target_state = deployed_state.targets.get(selected)
+    target_config = next((t for t in aws_targets if t.name == selected), None)
+    runtimes = target_state.resources.runtimes if target_state and target_state.resources else None
+    if not target_config or not runtimes:
+        return None
+    agent_state = runtimes.get(agent_name)
+    if not agent_state:
+        return None
+    return SessionInfo(agent_state.session_id, agent_name, agent_state.runtime_arn, selected)
+
+
+def save_session_id(
+    agent_name: str, session_id: str, target_name: str | None = None, config_io: ConfigIO | None = None
+) -> None:
+    config_io = config_io or ConfigIO()
+    deployed_state = config_io.read_deployed_state()
+    selected = _select_target(deployed_state, target_name)
+    if selected is None:
+        raise RuntimeError("No deployed targets found")
+    target_state = deployed_state.targets.get(selected)
+    runtimes = target_state.resources.runtimes if target_state and target_state.resources else None
+    if not runtimes or agent_name not in runtimes:
+        raise RuntimeError(f"Agent '{agent_name}' not found in deployed state")
+    runtimes[agent_name].session_id = session_id
+    config_io.write_deployed_state(deployed_state)
+
+
+def clear_session_id(agent_name: str, target_name: str | None = None, config_io: ConfigIO | None = None) -> None:
+    config_io = config_io or ConfigIO()
+    deployed_state = config_io.read_deployed_state()
+    selected = _select_target(deployed_state, target_name)
+    if selected is None:
+        return
+    target_state = deployed_state.targets.get(selected)
+    runtimes = target_state.resources.runtimes if target_state and target_state.resources else None
+    if not runtimes or agent_name not in runtimes:
+        return
+    runtimes[agent_name].session_id = None
+    config_io.write_deployed_state(deployed_state)
+
+
+def get_or_create_session_id(agent_name: str, target_name: str | None = None, config_io: ConfigIO | None = None) -> str:
+    config_io = config_io or ConfigIO()
+    info = get_session_id(agent_name, target_name, config_io)
+    if info and info.session_id:
+        return info.session_id
+    new_id = generate_session_id()
+    save_session_id(agent_name, new_id, target_name, config_io)
+    return new_id

agentcore/operations/traces/__init__.py

@@ -0,0 +1,29 @@
+"""Trace listing/download via CloudWatch Logs Insights (port of src/cli/operations/traces)."""
+
+from agentcore.operations.traces.get_trace import fetch_trace_records, get_trace
+from agentcore.operations.traces.insights_query import InsightsQueryResult, run_insights_query
+from agentcore.operations.traces.list_traces import list_traces
+from agentcore.operations.traces.trace_url import build_trace_console_url
+from agentcore.operations.traces.types import (
+    CloudWatchSpanRecord,
+    CloudWatchTraceRecord,
+    FetchTraceRecordsValue,
+    GetTraceValue,
+    ListTracesValue,
+    TraceEntry,
+)
+
+__all__ = [
+    "CloudWatchSpanRecord",
+    "CloudWatchTraceRecord",
+    "FetchTraceRecordsValue",
+    "GetTraceValue",
+    "InsightsQueryResult",
+    "ListTracesValue",
+    "TraceEntry",
+    "build_trace_console_url",
+    "fetch_trace_records",
+    "get_trace",
+    "list_traces",
+    "run_insights_query",
+]