agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/agent/import_/base_translator.py

@@ -0,0 +1,449 @@
+"""Base translator for converting Bedrock Agent configurations into Python code
+(port of operations/agent/import/base-translator.ts, itself a port of the starter toolkit's
+base_bedrock_translate.py).
+
+Generated code must stay byte-identical to upstream, so templates are built by plain string
+concatenation and numbers/JSON are formatted the way JavaScript does.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from agentcore.aws.partition import arn_prefix
+from agentcore.schema._zod import js_regex
+
+
+@dataclass
+class TranslatorOptions:
+    agent_config: Any
+    enable_memory: bool
+    memory_option: str
+    enable_observability: bool
+
+
+@dataclass
+class ImportedFeatures:
+    has_memory: bool = False
+    has_knowledge_bases: bool = False
+    has_action_groups: bool = False
+    has_code_interpreter: bool = False
+    has_multi_agent: bool = False
+    has_guardrails: bool = False
+    has_gateway: bool = False
+
+
+@dataclass
+class TranslationResult:
+    main_py_content: str
+    collaborator_files: dict[str, str] = field(default_factory=dict)
+    features: ImportedFeatures = field(default_factory=ImportedFeatures)
+
+
+@dataclass(frozen=True)
+class CollaboratorContext:
+    name: str
+    instruction: str
+    relay_history: str
+
+
+def nn(*values: Any) -> Any:
+    """JavaScript ``a ?? b ?? c``: the first value that is not None."""
+    for value in values:
+        if value is not None:
+            return value
+    return None
+
+
+def js_num(value: Any) -> str:
+    """Format a number like JavaScript template-literal interpolation."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, float):
+        if math.isnan(value):
+            return "NaN"
+        if math.isinf(value):
+            return "Infinity" if value > 0 else "-Infinity"
+        if value.is_integer() and abs(value) < 1e21:
+            return str(int(value))
+        return repr(value)
+    return str(value)
+
+
+def js_json(value: Any) -> str:
+    """``JSON.stringify(value)`` (compact)."""
+    return json.dumps(value, separators=(",", ":"), ensure_ascii=False)
+
+
+def arn_region(arn: str | None) -> str | None:
+    """``arn?.split(':')[3]``."""
+    if arn is None:
+        return None
+    parts = arn.split(":")
+    return parts[3] if len(parts) > 3 else None
+
+
+def js_replace_first(text: str, search: str, replacement: str) -> str:
+    """``String.prototype.replace(string, string)``: first occurrence, with ``$`` patterns expanded."""
+    idx = text.find(search)
+    if idx == -1:
+        return text
+    before, after = text[:idx], text[idx + len(search) :]
+    out: list[str] = []
+    i = 0
+    while i < len(replacement):
+        ch = replacement[i]
+        if ch == "$" and i + 1 < len(replacement):
+            nxt = replacement[i + 1]
+            if nxt == "$":
+                out.append("$")
+                i += 2
+                continue
+            if nxt == "&":
+                out.append(search)
+                i += 2
+                continue
+            if nxt == "`":
+                out.append(before)
+                i += 2
+                continue
+            if nxt == "'":
+                out.append(after)
+                i += 2
+                continue
+        out.append(ch)
+        i += 1
+    return before + "".join(out) + after
+
+
+_NON_IDENT = re.compile(r"[^a-zA-Z0-9_]")
+_LEADING_DIGIT = re.compile(r"^([0-9])")
+_JS_WHITESPACE = js_regex(r"\s")
+
+
+def sanitize_py_identifier(name: str) -> str:
+    """Sanitize a string to be a valid Python identifier."""
+    return _LEADING_DIGIT.sub(r"_\1", _NON_IDENT.sub("_", name))
+
+
+def escape_py_double_quote(s: str) -> str:
+    """Escape a string for use inside Python double-quoted strings."""
+    return s.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+
+
+def escape_py_single_quote(s: str) -> str:
+    """Escape a string for use inside Python single-quoted strings."""
+    return s.replace("\\", "\\\\").replace("'", "\\'").replace("\n", "\\n")
+
+
+def escape_py_triple_quote(s: str) -> str:
+    """Escape a string for use inside Python triple-quoted strings."""
+    return s.replace("\\", "\\\\").replace('"""', '\\"\\"\\"')
+
+
+class BaseBedrockTranslator(ABC):
+    """Shared translation logic between the Strands and LangChain translators."""
+
+    escape_py_double_quote = staticmethod(escape_py_double_quote)
+    escape_py_single_quote = staticmethod(escape_py_single_quote)
+    escape_py_triple_quote = staticmethod(escape_py_triple_quote)
+
+    def __init__(
+        self,
+        config: Any,
+        options: TranslatorOptions,
+        collaborator_context: CollaboratorContext | None = None,
+    ) -> None:
+        self.config = config
+        self.options = options
+        self.collaborator_context = collaborator_context
+
+        self.agent_info: dict[str, Any] = config.get("agent") or {}
+        self.action_groups: list[dict[str, Any]] = [
+            ag
+            for ag in (nn(config.get("action_groups"), []) or [])
+            if nn(ag.get("actionGroupState"), "ENABLED") == "ENABLED"
+        ]
+        self.custom_action_groups = [ag for ag in self.action_groups if not ag.get("parentActionSignature")]
+        self.knowledge_bases: list[dict[str, Any]] = nn(config.get("knowledge_bases"), [])
+        self.collaborators: list[dict[str, Any]] = nn(config.get("collaborators"), [])
+
+        info = self.agent_info
+        self.model_id: str = nn(info.get("foundationModel"), "")
+        self.agent_region: str = nn(arn_region(info.get("agentArn")), "us-east-1")
+        self.instruction: str = nn(info.get("instruction"), "")
+        self.prompt_configs: list[dict[str, Any]] = nn(
+            (info.get("promptOverrideConfiguration") or {}).get("promptConfigurations"), []
+        )
+        self.enabled_prompts: list[str] = []
+
+        # Memory
+        memory_config = info.get("memoryConfiguration") or {}
+        self.memory_enabled = bool(memory_config.get("enabledMemoryTypes"))
+        self.agentcore_memory_enabled = options.enable_memory and self.memory_enabled
+        self.has_long_term_strategies = options.memory_option == "longAndShortTerm"
+
+        # Features
+        self.code_interpreter_enabled = any(
+            ag.get("actionGroupName") == "codeinterpreteraction" and ag.get("actionGroupState") == "ENABLED"
+            for ag in self.action_groups
+        )
+        self.user_input_enabled = any(
+            ag.get("actionGroupName") == "userinputaction" and ag.get("actionGroupState") == "ENABLED"
+            for ag in self.action_groups
+        )
+        self.multi_agent_enabled = (
+            nn(info.get("agentCollaboration"), "DISABLED") != "DISABLED" and len(self.collaborators) > 0
+        )
+        self.supervision_type: str = nn(info.get("agentCollaboration"), "SUPERVISOR")
+        self.observability_enabled = options.enable_observability
+
+        # Guardrails
+        self.guardrail_config: dict[str, str] = {}
+        gc = info.get("guardrailConfiguration")
+        if gc:
+            g_id = nn(gc.get("guardrailId"), gc.get("guardrailIdentifier"), "")
+            g_version = nn(gc.get("version"), gc.get("guardrailVersion"), "")
+            if g_id:
+                self.guardrail_config = {"guardrailIdentifier": g_id, "guardrailVersion": g_version}
+
+        # Collaboration context
+        self.is_collaborator = collaborator_context is not None
+        self.is_accepting_relays = (
+            collaborator_context is not None and collaborator_context.relay_history == "TO_COLLABORATOR"
+        )
+        self.collaborator_descriptions = [
+            "{'agentName': '"
+            + escape_py_single_quote(nn((c.get("agent") or {}).get("agentName"), ""))
+            + "', 'collaboratorName': 'invoke_"
+            + sanitize_py_identifier(nn(c.get("collaboratorName"), ""))
+            + "', 'collaboratorInstruction': '"
+            + escape_py_triple_quote(nn(c.get("collaborationInstruction"), ""))
+            + "'}"
+            for c in self.collaborators
+        ]
+        self.collaborator_map = {nn(c.get("collaboratorName"), ""): c for c in self.collaborators}
+
+        agent_name = nn(info.get("agentName"), "agent")
+        self.cleaned_agent_name = _JS_WHITESPACE.sub("_", agent_name).replace("-", "_").lower()[:30]
+
+        self.tools: list[str] = []
+
+        # Base imports (common to both frameworks)
+        self.imports_code = """# ---------- NOTE: This file is auto-generated by AgentCore CLI (Import from Bedrock Agents). ----------
+# Use this agent definition as a starting point for your custom agent implementation.
+# Review the generated code, evaluate agent behavior, and make necessary changes before deploying.
+# -------------------------------------------------------------------------------------------------
+
+import json, sys, os, re, io, uuid, asyncio
+from typing import Annotated
+import boto3
+
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+"""
+        if not self.is_collaborator:
+            self.imports_code += "\napp = BedrockAgentCoreApp()\n"
+
+        self.prompts_code = ""
+
+    @abstractmethod
+    def translate(self) -> TranslationResult: ...
+
+    def generate_prompts(self) -> str:
+        """Prompt variable assignments for enabled prompt overrides."""
+        code = ""
+        for config in self.prompt_configs:
+            prompt_type = nn(config.get("promptType"), "")
+            template = (config.get("basePromptTemplate") or {}).get("system")
+            if not template:
+                continue
+            self.enabled_prompts.append(prompt_type)
+            processed = template
+            if prompt_type == "ORCHESTRATION":
+                processed = js_replace_first(processed, "$instruction$", self.instruction)
+            code += f'\n{prompt_type}_TEMPLATE = """{escape_py_triple_quote(processed)}"""\n'
+
+        if "ORCHESTRATION" not in self.enabled_prompts:
+            code += f'\nORCHESTRATION_TEMPLATE = """{escape_py_triple_quote(self.instruction)}"""\n'
+            self.enabled_prompts.append("ORCHESTRATION")
+        return code
+
+    def generate_function_action_group_tools(self) -> str:
+        """Function-schema action groups as @tool decorated functions."""
+        code = "\n# --- Action Group Tools ---\naction_group_tools = []\n"
+        for ag in self.custom_action_groups:
+            functions = (ag.get("functionSchema") or {}).get("functions")
+            if functions:
+                for fn in functions:
+                    code += self._generate_function_tool(fn, ag.get("actionGroupName", ""))
+        return code
+
+    def _generate_function_tool(self, fn: dict[str, Any], group_name: str) -> str:
+        fn_name = _NON_IDENT.sub("_", fn["name"])
+        params = nn(fn.get("parameters"), {}) or {}
+        py_types = {"string": "str", "integer": "int", "number": "float", "boolean": "bool"}
+        param_list = ", ".join(
+            f"{name}: {py_types.get((info or {}).get('type'), 'str')}" for name, info in params.items()
+        )
+        description = nn(fn.get("description"), f"Function from action group {group_name}")
+        escaped_desc = escape_py_triple_quote(description)
+        return (
+            "\n@tool\n"
+            f"def {fn_name}({param_list}) -> str:\n"
+            f'    """{escaped_desc}"""\n'
+            "    # TODO: Implement the logic for this action group function.\n"
+            f'    # This was imported from Bedrock Agent action group "{escape_py_double_quote(group_name)}".\n'
+            '    return json.dumps({"status": "not_implemented", "function": "' + fn_name + '"})\n'
+            "\n"
+            f"action_group_tools.append({fn_name})\n"
+        )
+
+    def generate_memory_code(self, memory_saver: str) -> str:
+        if not self.memory_enabled:
+            return ""
+        code = "\n# --- Memory Configuration ---\n"
+        if self.agentcore_memory_enabled:
+            code += """
+from bedrock_agentcore.memory import MemoryClient
+
+memory_client = MemoryClient()
+memory_id = os.environ.get("MEMORY_ID", "")
+"""
+        code += f"checkpointer_STM = {memory_saver}()\n"
+        return code
+
+    def generate_entrypoint_code(self, platform: Literal["strands", "langchain"]) -> str:
+        code = ""
+        if not self.is_collaborator:
+            code += "\n@app.entrypoint\n"
+
+        memory_event_code = (
+            """
+            event = memory_client.create_event(
+                memory_id=memory_id,
+                actor_id=user_id,
+                session_id=session_id,
+                messages=formatted_messages
+            )"""
+            if self.agentcore_memory_enabled
+            else ""
+        )
+
+        tools_used_update = (
+            "tools_used.update(list(agent_result.metrics.tool_metrics.keys()))"
+            if platform == "strands"
+            else "tools_used.update([msg.name for msg in agent_result if isinstance(msg, ToolMessage)])"
+        )
+        response_content = "str(agent_result)" if platform == "strands" else "agent_result[-1].content"
+
+        lines = ["async def invoke(payload, context):", "    try:"]
+        if self.agentcore_memory_enabled:
+            lines.append("        global user_id")
+            lines.append('        user_id = user_id or payload.get("userId", uuid.uuid4().hex[:8])')
+        lines.extend(
+            [
+                '        session_id = context.session_id or payload.get("sessionId", uuid.uuid4().hex[:8])',
+                "",
+                "        tools_used.clear()",
+                '        agent_query = payload.get("prompt", "")',
+                "        if not isinstance(agent_query, str):",
+                '            raise ValueError("prompt must be a string")',
+                "        if not agent_query:",
+                "            yield \"No query provided, please provide a 'prompt' field in the payload.\"",
+                "            return",
+                "",
+                "        agent_result = invoke_agent(agent_query)",
+                "",
+                "        " + tools_used_update,
+                "        response_content = " + response_content,
+            ]
+        )
+        if memory_event_code:
+            lines.extend(
+                [
+                    "",
+                    '        formatted_messages = [(agent_query, "USER"), (response_content if response_content else "No Response.", "ASSISTANT")]',
+                ]
+            )
+            lines.append(memory_event_code)
+        lines.extend(
+            [
+                "",
+                '        yield response_content if response_content else "No response."',
+                "    except Exception as e:",
+                '        yield f"Error: {e}"',
+            ]
+        )
+        code += "\n".join(lines)
+
+        if not self.is_collaborator:
+            code += '\n\n\nif __name__ == "__main__":\n    app.run()\n'
+        return code
+
+    def assemble_code(self, sections: list[str]) -> str:
+        return "\n".join(s for s in sections if s)
+
+    def generate_iam_permissions_comment(self) -> str:
+        """Comment block listing required IAM permissions and a CDK snippet granting them."""
+        kb_arns: list[str] = []
+        for kb in self.knowledge_bases:
+            if kb.get("knowledgeBaseArn"):
+                kb_arns.append(kb["knowledgeBaseArn"])
+            elif kb.get("knowledgeBaseId"):
+                kb_arns.append(
+                    f"{arn_prefix(self.agent_region)}:bedrock:{self.agent_region}:*:knowledge-base/{kb['knowledgeBaseId']}"
+                )
+        if not kb_arns:
+            return ""
+
+        arn_lines = "\n".join(f'#     "{arn}",' for arn in kb_arns)
+        cdk_lines = "\n".join(f"#         '{arn}'," for arn in kb_arns)
+        return (
+            """
+# -------------------------------------------------------------------------------------------------
+# IMPORTANT: Additional IAM permissions required for deployment.
+#
+# This agent uses Bedrock Knowledge Base retrieval, which requires the
+# "bedrock:Retrieve" permission on the following resources:
+"""
+            + arn_lines
+            + """
+#
+# The vended CDK stack does not automatically grant these permissions.
+# To add them, edit agentcore/cdk/lib/cdk-stack.ts:
+#
+#   import * as iam from 'aws-cdk-lib/aws-iam';
+#
+#   // After: this.application = new AgentCoreApplication(this, 'Application', { spec });
+#   // Use the agent name from agentcore/agentcore.json (the "name" field under "agents").
+#   const agentEnv = this.application.environments.get('<YOUR_AGENT_NAME>');
+#   if (agentEnv) {
+#     agentEnv.runtime.addToPolicy(new iam.PolicyStatement({
+#       actions: ['bedrock:Retrieve'],
+#       resources: [
+"""
+            + cdk_lines
+            + """
+#       ],
+#     }));
+#   }
+#
+# -------------------------------------------------------------------------------------------------
+"""
+        )
+
+    def get_features(self) -> ImportedFeatures:
+        return ImportedFeatures(
+            has_memory=self.memory_enabled,
+            has_knowledge_bases=len(self.knowledge_bases) > 0,
+            has_action_groups=len(self.custom_action_groups) > 0,
+            has_code_interpreter=self.code_interpreter_enabled,
+            has_multi_agent=self.multi_agent_enabled,
+            has_guardrails=len(self.guardrail_config) > 0,
+            has_gateway=False,
+        )

agentcore/operations/agent/import_/constants.py

@@ -0,0 +1,23 @@
+"""Constants for the Bedrock Agent import feature (port of operations/agent/import/constants.ts)."""
+
+from typing import Final
+
+from agentcore.operations.agent.generate.types import Option
+
+BEDROCK_REGIONS: Final = (
+    Option("us-east-1", "US East (N. Virginia)"),
+    Option("us-west-2", "US West (Oregon)"),
+    Option("eu-west-1", "Europe (Ireland)"),
+    Option("eu-central-1", "Europe (Frankfurt)"),
+    Option("ap-southeast-1", "Asia Pacific (Singapore)"),
+    Option("ap-northeast-1", "Asia Pacific (Tokyo)"),
+    Option("ap-south-1", "Asia Pacific (Mumbai)"),
+    Option("ca-central-1", "Canada (Central)"),
+    Option("sa-east-1", "South America (Sao Paulo)"),
+    Option("us-gov-west-1", "GovCloud (US West)"),
+)
+
+IMPORT_FRAMEWORK_OPTIONS: Final = (
+    Option("Strands", "Strands Agents SDK", "AWS native agent framework"),
+    Option("LangChain_LangGraph", "LangChain + LangGraph", "Popular open-source frameworks"),
+)

agentcore/operations/agent/import_/execute.py

@@ -0,0 +1,127 @@
+"""Bedrock Agent import entry point (port of operations/agent/import/index.ts executeImportAgent).
+
+Shared by the interactive `add agent` flow and the non-interactive CLI (AgentPrimitive / create).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.lib import APP_DIR, ConfigIO
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.operations.agent.import_.base_translator import TranslatorOptions
+from agentcore.operations.agent.import_.langgraph_translator import LangGraphTranslator
+from agentcore.operations.agent.import_.pyproject_generator import generate_pyproject_toml
+from agentcore.operations.agent.import_.strands_translator import StrandsTranslator
+from agentcore.primitives.auth_utils import JwtConfigOptions, create_managed_oauth_credential
+
+
+@dataclass
+class ExecuteImportAgentParams:
+    name: str
+    framework: str
+    memory: str
+    bedrock_region: str
+    bedrock_agent_id: str
+    bedrock_alias_id: str
+    config_base_dir: str
+    authorizer_type: str | None = None
+    jwt_config: JwtConfigOptions | None = None
+    idle_timeout: int | None = None
+    max_lifetime: int | None = None
+    session_storage_mount_path: str | None = None
+    efs_access_points: list[dict[str, Any]] | None = None
+    s3_access_points: list[dict[str, Any]] | None = None
+    # Attach the imported runtime to a capacity provider (camelCase dict: capacityProviderName/Arn).
+    capacity_provider_configuration: dict[str, Any] | None = None
+    # Capacity-provider volume mounts (camelCase dicts: volumeName, mountPath).
+    capacity_provider_volumes: list[dict[str, Any]] | None = None
+
+
+def _write(path: str, content: str) -> None:
+    with open(path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(content)
+
+
+def execute_import_agent(params: ExecuteImportAgentParams) -> Ok[dict[str, str]] | Err[BaseException]:
+    # Imported lazily: these modules import this package's siblings / are written concurrently.
+    from agentcore.aws.bedrock_import import get_bedrock_agent_config
+    from agentcore.operations.agent.generate import write_agent_to_project
+    from agentcore.operations.agent.generate.types import GenerateConfig
+    from agentcore.operations.python import setup_python_project
+
+    project_root = os.path.dirname(params.config_base_dir)
+    agent_path = os.path.join(project_root, APP_DIR, params.name)
+
+    try:
+        # 1. Fetch Bedrock Agent configuration
+        agent_config = get_bedrock_agent_config(params.bedrock_region, params.bedrock_agent_id, params.bedrock_alias_id)
+
+        # 2. Translate to framework-specific Python code
+        options = TranslatorOptions(
+            agent_config=agent_config,
+            enable_memory=params.memory != "none",
+            memory_option=params.memory,
+            enable_observability=True,
+        )
+        translator = (
+            StrandsTranslator(agent_config, options)
+            if params.framework == "Strands"
+            else LangGraphTranslator(agent_config, options)
+        )
+        result = translator.translate()
+
+        # 3. Write generated code to project
+        os.makedirs(agent_path, exist_ok=True)
+        _write(os.path.join(agent_path, "main.py"), result.main_py_content)
+        for file_name, content in result.collaborator_files.items():
+            _write(os.path.join(agent_path, file_name), content)
+
+        # 4. Generate pyproject.toml
+        _write(
+            os.path.join(agent_path, "pyproject.toml"),
+            generate_pyproject_toml(params.name, params.framework, result.features),
+        )
+
+        # 5. Write agent to project config
+        generate_config = GenerateConfig(
+            project_name=params.name,
+            build_type="CodeZip",
+            sdk=params.framework,
+            model_provider="Bedrock",
+            memory=params.memory,
+            language="Python",
+            protocol="HTTP",
+            authorizer_type=params.authorizer_type,
+            jwt_config=params.jwt_config,
+            idle_runtime_session_timeout=params.idle_timeout,
+            max_lifetime=params.max_lifetime,
+            session_storage_mount_path=params.session_storage_mount_path,
+            efs_access_points=params.efs_access_points,
+            s3_access_points=params.s3_access_points,
+            capacity_provider_configuration=params.capacity_provider_configuration,
+            capacity_provider_volumes=params.capacity_provider_volumes,
+        )
+        write_agent_to_project(generate_config, config_base_dir=params.config_base_dir)
+
+        # 5b. Auto-create OAuth credential for CUSTOM_JWT inbound auth
+        jwt = params.jwt_config
+        if params.authorizer_type == "CUSTOM_JWT" and jwt and jwt.client_id and jwt.client_secret:
+            config_io = ConfigIO(base_dir=params.config_base_dir)
+            create_managed_oauth_credential(
+                params.name,
+                jwt,
+                config_io.write_project_spec,
+                config_io.read_project_spec,
+                params.config_base_dir,
+            )
+
+        # 6. Set up Python environment
+        setup_python_project(agent_path)
+
+        return Ok({"agentName": params.name, "agentPath": agent_path})
+    except Exception as exc:  # noqa: BLE001 - surfaced as a Result, as upstream
+        return Err(to_error(exc))