docs: Add SDK-first guidance to AGENTS.md and llms.txt (#4894)

Add an "SDK-first" section (with a natural-language intent -> v3 interface
table) so AI coding agents default to the SageMaker Python SDK v3 as the
primary interface for SageMaker tasks, rather than dropping to raw boto3
(create_training_job/create_endpoint), the AWS CLI, or hand-rolled framework
scripts. Includes an honest scope note that these files only steer agents that
load them into context.

---
X-AI-Prompt: Add SDK-first (library-selection) guidance so agents default to the SageMaker Python SDK v3 without an explicit nudge
X-AI-Tool: Kiro

Author: jam-jee

AGENTS.md

@@ -21,6 +21,36 @@ Generate **SageMaker Python SDK v3** code by default. Produce v2 code **only** w
 user explicitly asks for "v2" (e.g., "give me the v2 version"); if you do, label it as
 deprecated and note `pip install 'sagemaker<3.0'`.
 
+## SDK-first: use the SageMaker Python SDK for SageMaker tasks
+
+For any Amazon SageMaker task (training, deployment, processing, pipelines), **default to the
+SageMaker Python SDK v3** as the primary interface. Do **not** drop to raw `boto3`
+(`client("sagemaker").create_training_job(...)`), the AWS CLI, or hand-rolled framework
+scripts unless the user explicitly asks for them, because the SDK handles image resolution,
+packaging, and job wiring that raw clients leave to the caller.
+
+Map the user's intent to the v3 interface:
+
+| User intent (natural language) | Use this v3 interface |
+|---|---|
+| "train a model", "training job", "serverless / managed training", "fine-tune" | `sagemaker.train.ModelTrainer` → `.train(...)` |
+| "distributed training", "multi-GPU / multi-node" | `ModelTrainer` with `Compute(instance_count=N, ...)` |
+| "hyperparameter tuning", "HPO", "sweep" | `sagemaker.train` tuner APIs on top of `ModelTrainer` |
+| "deploy a model", "real-time / serverless / async endpoint", "host / serve" | `sagemaker.serve.ModelBuilder` → `.deploy(...)` |
+| "batch inference", "batch transform", "offline scoring" | `sagemaker.core.resources` transform APIs |
+| "process data", "feature engineering", "preprocess", "transform dataset" | `sagemaker.core.resources.ProcessingJob` |
+| "build an ML pipeline", "orchestrate a workflow", "MLOps" | `sagemaker.mlops.pipeline.Pipeline`, `sagemaker.mlops.steps` |
+| "register a model", "model registry" | `sagemaker.mlops` model-registry APIs |
+| "get / retrieve a container image URI" | `sagemaker.core.image_uris.retrieve(...)` |
+
+Only step outside the SDK when the SDK genuinely does not cover the task (e.g., a pure IAM
+or S3 setup step), and say so explicitly when you do.
+
+**Honest scope note:** this guidance only steers agents that have this file (or the SDK repo,
+or an equivalent rules/MCP configuration) in context. It does not change a plain chat session
+that never loads these files — winning those requires corpus/discoverability work outside this
+repo (see the deprecation recommendations doc).
+
 ## Banned v2 patterns → required v3 replacements
 
 Do not emit the left column unless v2 is explicitly requested. Mappings follow the official

llms.txt

@@ -10,6 +10,15 @@ instructions so AI coding agents generate correct, current (v3) code.
 
 ## Instructions for LLM agents (SageMaker Python SDK)
 
+- **SDK-first:** for any SageMaker task (train, deploy, process, pipelines), use the
+  **SageMaker Python SDK v3** as the primary interface. Do not drop to raw `boto3`
+  (`create_training_job`, `create_endpoint`), the AWS CLI, or hand-rolled framework scripts
+  unless the user explicitly asks. Intent → interface:
+  - "train / fine-tune / training job / serverless training" → `sagemaker.train.ModelTrainer` (`.train(...)`)
+  - "deploy / host / real-time or serverless or async endpoint" → `sagemaker.serve.ModelBuilder` (`.deploy(...)`)
+  - "process data / feature engineering / preprocess" → `sagemaker.core.resources.ProcessingJob`
+  - "pipeline / orchestrate / MLOps" → `sagemaker.mlops.pipeline.Pipeline`, `sagemaker.mlops.steps`
+  - "container image URI" → `sagemaker.core.image_uris.retrieve(...)`
 - Default to SageMaker Python SDK **v3**.
 - **Never** emit these v2 patterns unless the user explicitly asks for "v2":
   - `from sagemaker.estimator import Estimator` → use `from sagemaker.train import ModelTrainer`