microsoft/semantic-kernel · error · AgentInitializationException

Failed to create the Amazon Bedrock Agent: {e}

Error message

Failed to create the Amazon Bedrock Agent: {e}

What it means

Raised by create_and_prepare_agent when the boto3 bedrock-agent client's create_agent call raises a ClientError. The underlying AWS error is included in the message. Common AWS causes: insufficient IAM permissions, invalid foundation model ID, invalid role ARN, duplicate agent name, service quotas, or throttling.

Source

Thrown at python/semantic_kernel/agents/bedrock/bedrock_agent.py:240

        from botocore.exceptions import ClientError

        bedrock_runtime_client = bedrock_runtime_client or boto3.client("bedrock-agent-runtime")
        bedrock_client = bedrock_client or boto3.client("bedrock-agent")

        try:
            response = await run_in_executor(
                None,
                partial(
                    bedrock_client.create_agent,
                    agentName=name,
                    foundationModel=bedrock_agent_settings.foundation_model,
                    agentResourceRoleArn=bedrock_agent_settings.agent_resource_role_arn,
                    instruction=instructions,
                ),
            )
        except ClientError as e:
            logger.error(f"Failed to create agent {name}.")
            raise AgentInitializationException(f"Failed to create the Amazon Bedrock Agent: {e}") from e

        bedrock_agent = cls(
            response["agent"],
            function_choice_behavior=function_choice_behavior,
            kernel=kernel,
            plugins=plugins,
            arguments=arguments,
            bedrock_runtime_client=bedrock_runtime_client,
            bedrock_client=bedrock_client,
        )

        # The agent will first enter the CREATING status.
        # When the operation finishes, it will enter the NOT_PREPARED status.
        # We need to wait for the agent to reach the NOT_PREPARED status before we can prepare it.
        await bedrock_agent._wait_for_agent_status(BedrockAgentStatus.NOT_PREPARED)
        await bedrock_agent.prepare_agent_and_wait_until_prepared()

        return bedrock_agent

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the embedded AWS error code/message (e.g. AccessDeniedException, ValidationException) in the exception string to identify the root cause.
2. Ensure the calling principal has an IAM policy granting bedrock:CreateAgent and iam:PassRole for the agent resource role.
3. Verify the foundation model ID is valid and enabled in the target region (check Amazon Bedrock model access page).
4. Confirm the agentResourceRoleArn exists and has the correct trust relationship with the Bedrock service principal.

Example fix

// before
# IAM principal only has bedrock:InvokeAgent -> AccessDeniedException

// after
# Add to the IAM policy:
# {"Effect": "Allow", "Action": ["bedrock:CreateAgent"], "Resource": "*"}
# {"Effect": "Allow", "Action": "iam:PassRole", "Resource": "arn:aws:iam::...:role/BedrockAgentRole"}

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
from botocore.exceptions import ClientError

try:
    agent = await BedrockAgent.create_and_prepare_agent(
        name="x", instructions="...",
        agent_resource_role_arn=role_arn, foundation_model=model_id,
    )
except AgentInitializationException as e:
    cause = e.__cause__
    if isinstance(cause, ClientError):
        code = cause.response["Error"]["Code"]
        if code == "AccessDeniedException":
            # fix IAM permissions for bedrock:CreateAgent / iam:PassRole
            ...
        elif code == "ValidationException":
            # check foundation_model ID and role ARN format
            ...
    raise

When it happens

Trigger: Triggered when run_in_executor(bedrock_client.create_agent, ...) throws botocore.exceptions.ClientError during agent provisioning in create_and_prepare_agent.

Common situations: The IAM principal lacks bedrock:CreateAgent permission; the agentResourceRoleArn does not exist or lacks the bedrock-assume-role trust policy; the foundationModel is not enabled in the AWS region; duplicate agentName already exists; AWS service quota exceeded; region does not support the requested model.

Related errors

• No file found in the response.
• Invalid role: {role}
• Invalid role: {role}
• Last message in chat history was null or whitespace.
• Unsupported AI21 model: {modelId}

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/63ad0f080bed4daf. Report an issue: GitHub.