fix(import-agent): create gateway Lambda before targets and handle string apiSchema (#515)

* fix(import-agent): create gateway Lambda before targets and handle string apiSchema

Gateway control plane validates that the Lambda ARN exists when creating
targets. The previous code called create_gateway_lambda_target inside the
action group loop before create_lambda was invoked, causing rejections.
Restructured into collect-then-create phases.

Also added isinstance guards for apiSchema which can be returned as a raw
string by the Bedrock API, causing AttributeError on .get() calls.

Constraint: Bedrock API returns apiSchema as either dict or raw string
Rejected: Parsing string schema inline in base_bedrock_translate | only dict payloads expected there, safer to skip
Confidence: high
Scope-risk: narrow

* style: fix ruff lint errors (unused imports)

* chore: remove .omc state files and add to gitignore

* fix: remove pointless sleep from data-collection loop

The sleep was there to throttle Gateway API calls, but after
restructuring, this loop only collects data locally. The sleep
remains in the deferred targets loop where API calls actually happen.

Author: jesseturner21

.gitignore

@@ -32,3 +32,4 @@ mise.toml
 !tests/create/fixtures/scenarios/
 !tests/create/fixtures/scenarios/**
 .kiro/
+.omc/

src/bedrock_agentcore_starter_toolkit/cli/create/import_agent/agent_info.py

@@ -139,6 +139,10 @@ def get_agent_info(agent_id: str, agent_alias_id: str, bedrock_client, bedrock_a
         action_group["actionGroupName"] = clean_variable_name(action_group["actionGroupName"])
 
         if action_group.get("apiSchema", False):
+            api_schema = action_group["apiSchema"]
+            if isinstance(api_schema, str):
+                yaml = YAML(typ="safe")
+                action_group["apiSchema"] = {"payload": yaml.load(api_schema)}
             open_api_schema = action_group["apiSchema"].get("payload", False)
             if open_api_schema:
                 yaml = YAML(typ="safe")

src/bedrock_agentcore_starter_toolkit/services/import_agent/scripts/base_bedrock_translate.py

@@ -478,7 +478,8 @@ def generate_openapi_ag_code(self, ag: Dict, platform: str) -> Tuple[list, str]:
             lambda_arn = ag.get("actionGroupExecutor", {}).get("lambda", "")
             lambda_region = lambda_arn.split(":")[3] if lambda_arn else "us-west-2"
 
-        openapi_schema = ag.get("apiSchema", {}).get("payload", {})
+        api_schema = ag.get("apiSchema", {})
+        openapi_schema = api_schema.get("payload", {}) if isinstance(api_schema, dict) else {}
 
         for func_name, func_spec in openapi_schema.get("paths", {}).items():
             # Function metadata
@@ -1172,10 +1173,9 @@ def create_gateway_proxy_and_targets(self):
 
         # Aggregate info from the action_groups
         tool_mappings = {}
+        deferred_targets = []
 
         for ag in action_groups:
-            time.sleep(10)  # Sleep to avoid throttling issues with the Gateway API
-
             if "lambda" not in ag.get("actionGroupExecutor", {}):
                 continue
 
@@ -1186,7 +1186,8 @@ def create_gateway_proxy_and_targets(self):
             tools = []
 
             if ag.get("apiSchema", False):
-                openapi_schema = ag.get("apiSchema", {}).get("payload", {})
+                api_schema = ag.get("apiSchema", {})
+                openapi_schema = api_schema.get("payload", {}) if isinstance(api_schema, dict) else {}
 
                 for func_name, func_spec in openapi_schema.get("paths", {}).items():
                     clean_func_name = clean_variable_name(func_name)
@@ -1358,7 +1359,7 @@ def create_gateway_proxy_and_targets(self):
                     )
 
             if tools:
-                self.create_gateway_lambda_target(tools, lambda_arn, clean_action_group_name)
+                deferred_targets.append((tools, clean_action_group_name))
 
         agent_metadata = {
             "name": self.agent_info.get("agentName", ""),
@@ -1472,6 +1473,10 @@ def lambda_handler(event, context):
 
         self.create_lambda(lambda_code, function_name)
 
+        for tools, clean_action_group_name in deferred_targets:
+            time.sleep(10)  # Sleep to avoid throttling issues with the Gateway API
+            self.create_gateway_lambda_target(tools, lambda_arn, clean_action_group_name)
+
     def _update_gateway_role_with_lambda_permission(self, function_name):
         """Update the gateway role with lambda invoke permission."""
         if not self.created_gateway or not self.created_gateway.get("roleArn"):

tests/services/import_agent/test_import_agent_bugs.py

@@ -0,0 +1,164 @@
+"""Tests for import-agent bug fixes (V2200635700)."""
+
+from unittest.mock import MagicMock, patch
+
+
+class TestLambdaCreatedBeforeGatewayTargets:
+    """Bug #1: Gateway Lambda must be created before targets reference it."""
+
+    @patch("boto3.client")
+    def test_create_lambda_called_before_gateway_targets(self, mock_boto_client):
+        """Verify create_lambda is called before any create_gateway_lambda_target."""
+        from bedrock_agentcore_starter_toolkit.services.import_agent.scripts.base_bedrock_translate import (
+            BaseBedrockTranslator,
+        )
+
+        mock_sts = MagicMock()
+        mock_sts.get_caller_identity.return_value = {"Account": "123456789012"}
+        mock_boto_client.return_value = mock_sts
+
+        translator = BaseBedrockTranslator.__new__(BaseBedrockTranslator)
+        translator.agent_region = "us-west-2"
+        translator.cleaned_agent_name = "test_agent"
+        translator.created_gateway = {"gatewayId": "gw-123", "roleArn": "arn:aws:iam::123456789012:role/test"}
+        translator.gateway_client = MagicMock()
+        translator.agent_info = {"agentName": "test", "agentId": "id", "alias": "a", "version": "1"}
+
+        translator.custom_ags = [
+            {
+                "actionGroupExecutor": {"lambda": "arn:aws:lambda:us-west-2:123456789012:function:orig"},
+                "actionGroupName": "TestGroup",
+                "description": "test",
+                "apiSchema": {
+                    "payload": {
+                        "paths": {
+                            "/test": {
+                                "get": {
+                                    "summary": "Test endpoint",
+                                    "parameters": [],
+                                }
+                            }
+                        }
+                    }
+                },
+            }
+        ]
+
+        call_order = []
+        translator.create_lambda = MagicMock(side_effect=lambda *a, **kw: call_order.append("create_lambda"))
+        translator.create_gateway_lambda_target = MagicMock(
+            side_effect=lambda *a, **kw: call_order.append("create_gateway_lambda_target")
+        )
+
+        with patch("time.sleep"):
+            translator.create_gateway_proxy_and_targets()
+
+        assert call_order[0] == "create_lambda", "create_lambda must be called before create_gateway_lambda_target"
+        assert "create_gateway_lambda_target" in call_order
+
+
+class TestApiSchemaAsString:
+    """Bug #2: apiSchema can be a raw string instead of a dict."""
+
+    def test_agent_info_handles_string_api_schema(self):
+        """agent_info.py string apiSchema guard converts it to a dict with parsed payload."""
+        from ruamel.yaml import YAML
+
+        # Simulate what agent_info.py does with string apiSchema
+        action_group = {
+            "apiSchema": "openapi: '3.0.0'\npaths: {}",
+            "actionGroupName": "TestGroup",
+        }
+
+        api_schema = action_group["apiSchema"]
+        if isinstance(api_schema, str):
+            yaml = YAML(typ="safe")
+            action_group["apiSchema"] = {"payload": yaml.load(api_schema)}
+
+        # Verify it was converted to a dict with parsed YAML
+        assert isinstance(action_group["apiSchema"], dict)
+        assert action_group["apiSchema"]["payload"] == {"openapi": "3.0.0", "paths": {}}
+        # .get() should now work
+        assert action_group["apiSchema"].get("payload", False) is not False
+
+    @patch("boto3.client")
+    def test_base_translate_handles_string_api_schema(self, mock_boto_client):
+        """base_bedrock_translate.py should skip string apiSchema gracefully."""
+        from bedrock_agentcore_starter_toolkit.services.import_agent.scripts.base_bedrock_translate import (
+            BaseBedrockTranslator,
+        )
+
+        mock_sts = MagicMock()
+        mock_sts.get_caller_identity.return_value = {"Account": "123456789012"}
+        mock_boto_client.return_value = mock_sts
+
+        translator = BaseBedrockTranslator.__new__(BaseBedrockTranslator)
+        translator.agent_region = "us-west-2"
+        translator.cleaned_agent_name = "test_agent"
+        translator.created_gateway = {"gatewayId": "gw-123", "roleArn": "arn:aws:iam::123456789012:role/test"}
+        translator.gateway_client = MagicMock()
+        translator.agent_info = {"agentName": "test", "agentId": "id", "alias": "a", "version": "1"}
+
+        translator.custom_ags = [
+            {
+                "actionGroupExecutor": {"lambda": "arn:aws:lambda:us-west-2:123456789012:function:orig"},
+                "actionGroupName": "TestGroup",
+                "description": "test",
+                "apiSchema": "openapi: '3.0.0'\npaths: {}",
+            }
+        ]
+
+        translator.create_lambda = MagicMock()
+        translator.create_gateway_lambda_target = MagicMock()
+
+        with patch("time.sleep"):
+            translator.create_gateway_proxy_and_targets()
+
+        # Should not crash; no targets created since string schema yields no tools
+        translator.create_gateway_lambda_target.assert_not_called()
+
+    @patch("boto3.client")
+    def test_dict_api_schema_still_works(self, mock_boto_client):
+        """Regression: dict apiSchema with payload should still extract tools."""
+        from bedrock_agentcore_starter_toolkit.services.import_agent.scripts.base_bedrock_translate import (
+            BaseBedrockTranslator,
+        )
+
+        mock_sts = MagicMock()
+        mock_sts.get_caller_identity.return_value = {"Account": "123456789012"}
+        mock_boto_client.return_value = mock_sts
+
+        translator = BaseBedrockTranslator.__new__(BaseBedrockTranslator)
+        translator.agent_region = "us-west-2"
+        translator.cleaned_agent_name = "test_agent"
+        translator.created_gateway = {"gatewayId": "gw-123", "roleArn": "arn:aws:iam::123456789012:role/test"}
+        translator.gateway_client = MagicMock()
+        translator.agent_info = {"agentName": "test", "agentId": "id", "alias": "a", "version": "1"}
+
+        translator.custom_ags = [
+            {
+                "actionGroupExecutor": {"lambda": "arn:aws:lambda:us-west-2:123456789012:function:orig"},
+                "actionGroupName": "TestGroup",
+                "description": "test",
+                "apiSchema": {
+                    "payload": {
+                        "paths": {
+                            "/test": {
+                                "get": {
+                                    "summary": "Test endpoint",
+                                    "parameters": [],
+                                }
+                            }
+                        }
+                    }
+                },
+            }
+        ]
+
+        translator.create_lambda = MagicMock()
+        translator.create_gateway_lambda_target = MagicMock()
+
+        with patch("time.sleep"):
+            translator.create_gateway_proxy_and_targets()
+
+        translator.create_gateway_lambda_target.assert_called_once()