Sdk Getting Started

SDK Getting Started

Preflight checks to verify the user's environment can run SageMaker AI operations. The agent runs these checks directly (no code generation) and stores results in conversation context for downstream skills.

Principles

1. Don't ask for what you can look up. Resolve region and role programmatically before asking the user.

Workflow

Read and follow references/sagemaker-python-sdk-setup.md.

References

• references/sagemaker-python-sdk-setup.md - SageMaker Python SDK version, region, and execution role checks
• references/execution-role-setup.md — Execution role resolution and validation

Execution Role Setup

Resolve

Auto-detect the execution role by running:

python -c "from sagemaker.core.helper.session_helper import get_execution_role; print(get_execution_role())"

If it succeeds, store the printed ARN as ROLE_ARN and continue to Validate.

If it fails (user is not authenticated as a role, or credentials are missing), ask the user for their execution role ARN:

What IAM role should SageMaker use to run jobs? I need the full ARN (e.g., arn:aws:iam::123456789012:role/MySageMakerRole).

>

If you don't have one yet, see: https://github.com/awslabs/agent-plugins/tree/main/plugins/sagemaker-ai#authentication-and-authorization

Store the user-provided ARN as ROLE_ARN, continue to Validate.

Validate

Extract role name from ROLE_ARN and run:

aws iam get-role --role-name <ROLE_NAME>

• AccessDenied → warn: "⚠️ Cannot verify role (missing iam:GetRole). Proceeding with unverified role." Continue.
• Role found → check AssumeRolePolicyDocument for trust principals:
• sagemaker.amazonaws.com missing → STOP. Tell user their role needs sagemaker.amazonaws.com in the trust policy. Link to plugin README.
• bedrock.amazonaws.com missing → WARN: "Role missing bedrock trust. Bedrock steps may fail."
• lambda.amazonaws.com missing (and plan includes RLVR) → WARN: "Role missing lambda trust. RLVR reward functions will fail."

Required Permissions

For required IAM permissions and trust policy setup, see the plugin README — Authentication and Authorization.

S3 caveat: The AmazonSageMakerFullAccess managed policy only grants S3 access to buckets with "sagemaker" in the name. If your data is in other buckets, add a supplemental S3 policy.

Troubleshooting

"Access denied when attempting to assume role"

The role's trust policy is missing the required service principal. Add sagemaker.amazonaws.com to the trust policy.

SageMaker Python SDK Setup

Workflow for validating the SageMaker Python SDK environment.

Step 1: Install/Verify SDK

First, check if the SDK is already installed:

python -c "from importlib.metadata import version; print(version('sagemaker'))"

• If version ≥ 3.7.1 → report the version to the user. Offer to upgrade but do not force it.
• If missing or < 3.7.1 → install:

pip install --upgrade 'sagemaker>=3.7.1' boto3 -q

Then re-run the version check to confirm.

If install fails

STOP. Do NOT proceed with the plan. Tell the user:

pip install failed — this is likely a system-level issue, not something I can fix by trying different install commands.

Show the exact error, then:

Common causes: missing C build tools (gcc/python3-devel), incompatible Python version, or network/proxy issues.

Do NOT retry with --no-deps, alternative package names, or extras like [core] or [train]. These result in a broken partial install that fails later with import errors.

Step 2: Check Region

If REGION is already stored in conversation context, skip this step — do not re-prompt the user.

Otherwise, run:

python -c "import boto3; print(boto3.session.Session().region_name)"

• None → STOP. Tell user: "Set your region via export AWS_DEFAULT_REGION={region} or aws configure."
• Set → store REGION in context, continue.

Step 3: Resolve and Validate Execution Role

Read and follow execution-role-setup.md.

Step 4: Summary

Print:

Environment ready:
  SDK:    sagemaker X.Y.Z ✅
  Region: <region> ✅
  Role:   <arn> ✅
          sagemaker trust ✅ | bedrock trust ⚠️ | lambda trust ✅

Downstream skills use REGION and ROLE_ARN from conversation context. They MUST NOT re-resolve these values.