Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Mempersiapkan agen Anda

Sebelum Anda dapat meluncurkan pekerjaan pelatihan, Anda perlu mengatur agen yang dapat berpartisipasi dalam lingkaran pelatihan. Bagian ini memandu Anda melalui cara mengonfigurasi dan menyebarkan agen Anda, apakah Anda menggunakan Amazon Bedrock AgentCore untuk hosting terkelola atau membawa infrastruktur Anda sendiri dengan agen khusus.

Ikhtisar integrasi kode agen

Selama pelatihan, SageMaker AI mengirimkan petunjuk dari kumpulan data pelatihan Anda ke agen Anda. Agen Anda memproses setiap prompt, memanggil model kebijakan untuk respons, dan mengambil tindakan di lingkungan Anda seperti alat panggilan. Model kebijakan adalah model yang dilatih. Ini dimulai saat model dasar Anda dan bobotnya diperbarui dari waktu ke waktu karena menerima umpan balik melalui loop pelatihan. Berdasarkan hasilnya, agen Anda melaporkan hadiah kembali ke SageMaker AI untuk menyelesaikan loop pelatihan. Ini berulang untuk semua permintaan dalam kumpulan data Anda, dan model kebijakan meningkat seiring waktu berdasarkan imbalan yang dikumpulkan.

SageMaker Layanan Runtime Pekerjaan AI

Selama pelatihan, agen Anda berkomunikasi dengan SageMaker AI Job Runtime Service untuk memanggil model kebijakan untuk inferensi dan melaporkan hasil kembali ke pelatih. Dekorator SDK menangani integrasi ini secara otomatis, tetapi jika agen Anda memiliki persyaratan khusus, Anda dapat memanggil Runtime API secara langsung.

Titik akhir

https://job-runtime.sagemaker.region.api.aws

API

Autentikasi

Agen Anda mengautentikasi dengan Layanan Runtime menggunakan token pembawa. Menghasilkan token menggunakan SDK:

from sagemaker.core.token_generator import generate_token

token = generate_token(region="us-west-2")

Berikan token ini sebagai kunci API saat memanggil Layanan Runtime.

Integrasi API langsung (lanjutan)

Jika kerangka kerja agen Anda tidak dapat menggunakan dekorator SDK, panggil API secara langsung:

import requests
import openai
from sagemaker.core.token_generator import generate_token
from sagemaker.train.rft.headers import make_inference_headers

token = generate_token(region="us-west-2")
endpoint = "https://job-runtime.sagemaker.us-west-2.api.aws"
headers = {
    "Authorization": f"Bearer {token}",
    "Content-Type": "application/json",
    **make_inference_headers(metadata),  # injects jobArn, rolloutId tracking
}

# Sample (inference call)

# Option 1: Create OpenAI-compatible client pointing to the Runtime Service (recommended)
client = openai.OpenAI(
    base_url=endpoint + "/v1",
    api_key=token,
    default_headers=headers,
)

# Option 2: direct request call
response = requests.post(
    f"{endpoint}/v1/chat/completions",
    headers=headers,
    json={
        "model": "default",
        "messages": [{"role": "user", "content": "..."}],
        "max_tokens": 256,
        "temperature": 1.0,
    }
)

# CompleteRollout + UpdateReward (after all turns complete)
# The decorator handles this; for direct calls, use the SDK's
# RolloutFeedbackClient or call the APIs per the Smithy model.

Opsi penyebaran agen

SageMaker AI mendukung dua opsi untuk menghubungkan agen Anda ke loop pelatihan:

Skenario 1: Agen di Bedrock AgentCore Runtime

Terapkan agen Anda ke Amazon Bedrock AgentCore untuk hosting yang dikelola sepenuhnya. SageMaker AI memanggil agen Anda selama pelatihan model.

Prasyarat

Sebelum Anda mulai, lengkapi prasyarat berikut.

Peran AgentCore eksekusi batuan dasar

Selama pelatihan, SageMaker AI mengasumsikan peran SageMaker eksekusi Anda untuk memanggil agen Anda. Agen Anda juga membutuhkan peran terpisahnya sendiri, yang disebut peran AgentCore eksekusi Bedrock, untuk memanggil RFT Runtime untuk inferensi model dan pelaporan hadiah. RFT Runtime adalah titik akhir layanan SageMaker AI yang berkomunikasi dengan agen Anda selama pelatihan. Ini menangani dua hal: melayani tanggapan dari model kebijakan selama inferensi, dan menerima hadiah yang dilaporkan agen Anda di akhir setiap peluncuran.

Buat peran AgentCore eksekusi Bedrock dengan kebijakan kepercayaan berikut. Kebijakan ini memberikan AgentCore izin kepada Bedrock untuk mengambil peran atas nama Anda selama pelatihan. Tanpa itu, Bedrock AgentCore tidak dapat mengakses gambar kontainer Anda atau memanggil RFT Runtime.

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Principal": {"Service": "bedrock-agentcore.amazonaws.com"},
        "Action": "sts:AssumeRole"
    }]
}

Kemudian lampirkan kebijakan yang AmazonSageMakerJobRuntimeAccessdikelola ke peran ini. Ini memberikan izin yang diperlukan agen Anda untuk memanggil model kebijakan untuk inferensi dan melaporkan hasil selama pelatihan.

Tulis atau perbarui kode agen Anda

Agen Anda harus menggunakan sagemaker-trainSDK dan menerapkan @sagemaker_rft_handler dekorator ke fungsi titik masuk agen Anda. Dekorator ini mengatur server HTTP yang AgentCore memanggil selama pelatihan, mendengarkan permintaan peluncuran masuk dan perintah perutean ke fungsi entrypoint Anda.

Instal SDK

Instal SDK di lingkungan agen Anda menggunakan salah satu metode berikut.

Opsi 1: Instal langsung

pip install sagemaker-train

Opsi 2: Bangun dan pasang roda satu per satu. Gunakan ini jika pemasangan langsung melebihi batasan ukuran lingkungan Anda.

# Clone the SDK repository
git clone https://github.com/aws/sagemaker-python-sdk.git

# Build the wheels
cd sagemaker-python-sdk/sagemaker-train
python -m build --wheel --outdir ./dist/

cd sagemaker-python-sdk/sagemaker-core
python -m build --wheel --outdir ./dist/

# Install
pip install ./sagemaker-train/dist/sagemaker_train-*.whl
pip install ./sagemaker-core/dist/sagemaker_core-*.whl

Autentikasi

Agen Anda mengautentikasi dengan SageMaker AI menggunakan token pembawa. Buat token menggunakan generate_token() metode SDK dan teruskan sebagai kunci API saat memanggil model kebijakan untuk inferensi.

Persyaratan agen

Agen Anda harus melakukan hal berikut untuk setiap peluncuran:

Contoh berikut menunjukkan template agen dasar menggunakan Strands SDK:

from sagemaker.train.rft import sagemaker_rft_handler, RolloutFeedbackClient
from sagemaker.train.rft.adapters.strands import wrap_model
from sagemaker.core.token_generator import generate_token
from strands import Agent, OpenAIModel
import os

@sagemaker_rft_handler
def handle_rollout(payload):
    metadata = payload.get("metadata", {})
    prompt = payload.get("prompt", "")
    endpoint = metadata.get("endpoint", os.environ.get("RFT_RUNTIME_ENDPOINT", ""))

    # Generate bearer token for authenticating with the RFT Runtime
    token = generate_token(region=os.environ.get("AWS_REGION", "us-west-2"))

    # Create client for model inference
    model = OpenAIModel(
        model_id="default",
        client_args={
            "api_key": token,
            "base_url": endpoint + "/v1",
        },
    )

    # Wrap model to auto-inject RFT tracking headers and inference parameters
    model = wrap_model(model)

    # Execute actions in your environment (tools, APIs, etc.)
    agent = Agent(model=model, tools=[..., ...])
    result = agent(prompt)

    # Return reward -   decorator handles CompleteRollout + UpdateReward
    return {"reward": compute_reward(result)}

Menyebarkan agen Anda ke Bedrock AgentCore

Terapkan agen Anda ke Amazon Bedrock AgentCore mengikuti panduan AgentCore pengembangan.

Setelah Anda menerapkan agen Anda menggunakan AgentCore CLI, perhatikan ARN Agent Runtime dari output. Anda membutuhkan ini saat membuat pekerjaan pelatihan Anda. Runtime ARN mengikuti format. arn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<agent-name>

Verifikasi agen Anda dikerahkan dan sehat:

aws bedrock-agentcore-control list-agent-runtimes --region us-west-2

Skenario 2: Agen Kustom dengan Lambda Forwarder

Selain Bedrock AgentCore, SageMaker AI mendukung agen khusus yang dihosting di lingkungan apa pun. Agen Anda terhubung ke loop pelatihan melalui forwarder Lambda, memberi Anda fleksibilitas untuk menggunakan kerangka kerja agen dan platform hosting pilihan Anda.

Agen Anda dapat dibangun menggunakan kerangka kerja atau platform apa pun, seperti Strands Agents SDK, atau implementasi kustom Anda sendiri. Ini dapat berjalan di lingkungan komputasi apa pun termasuk Amazon Bedrock, AgentCore Amazon EKS, Amazon EC2, Fargate AWS , atau infrastruktur Anda sendiri.

Fungsi Lambda menerima permintaan peluncuran dari SageMaker AI dan meneruskannya ke titik akhir HTTP agen Anda.

Bagian berikut memberikan informasi lebih lanjut tentang pengaturan agen kustom dengan forwarder Lambda, dengan contoh menggunakan agen kustom yang digunakan di Amazon EKS.

Prasyarat

Peran pelaksanaan Lambda

Selama pelatihan, SageMaker AI mengasumsikan peran SageMaker eksekusi Anda untuk memanggil forwarder Lambda Anda. Fungsi Lambda membutuhkan peran eksekusi sendiri sehingga AWS Lambda dapat menjalankannya. Peran ini memungkinkan Lambda menjalankan dan menulis log.

aws iam create-role \
  --role-name RFTLambdaForwarderRole \
  --assume-role-policy-document '{
    "Version": "2012-10-17",
    "Statement": [{
      "Effect": "Allow",
      "Principal": {"Service": "lambda.amazonaws.com"},
      "Action": "sts:AssumeRole"
    }]
  }'

aws iam attach-role-policy \
  --role-name RFTLambdaForwarderRole \
  --policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole

Tulis kode agen Anda

Agen Anda harus mengekspos titik akhir HTTP yang menerima permintaan peluncuran dan berinteraksi dengan layanan RFT Runtime, dengan memanggilnya untuk inferensi model dan melaporkan imbalan setelah tugas selesai.

Format permintaan peluncuran

Agen Anda menerima permintaan dalam format berikut dari forwarder Lambda:

{
    "prompt": "string",
    "metadata": {
        "jobArn": "string",
        "rolloutId": "string"
    },
    "inferenceParams": {
        "temperature": 1.0,
        "topP": 1.0,
        "maxTokens": 256
    }
}

Harapan agen

Agar Amazon SageMaker AI berhasil menyelesaikan peluncuran, agen Anda harus:

Contoh berikut menunjukkan agen kustom dengan titik akhir FastTapi:

"""
Custom Lambda Agent for SageMaker RFT.

This is a minimal example showing the required integration points.
You can use any framework (Strands, LangChain, raw OpenAI, etc.)
or any HTTP framework (FastAPI, Flask, Django, etc.) for your agent.
"""
import os
from fastapi import FastAPI
from fastapi.responses import JSONResponse
from pydantic import BaseModel
from typing import Any, Dict
from sagemaker.train.rft import sagemaker_rft_handler, set_rollout_context
from sagemaker.train.rft.headers import make_inference_headers
from sagemaker.core.token_generator import generate_token

app = FastAPI()

@app.post("/rollout")
def rollout_endpoint(payload: dict):
    handle_rollout(payload)
    return {"status": "accepted"}

@sagemaker_rft_handler
def handle_rollout(payload):
    """Handle a rollout request from RFT."""
    prompt = payload.get("prompt", "")
    metadata = payload.get("metadata", {})
    inference_params = payload.get("inferenceParams", {})
    endpoint = metadata.get("endpoint", os.environ.get("RFT_RUNTIME_ENDPOINT", ""))

    # 1. Set rollout context and capture inference headers
    set_rollout_context(metadata)
    headers = make_inference_headers(metadata)

    # 2. Get bearer token for RFT Runtime authentication
    token = generate_token(region=os.environ.get("AWS_REGION", "us-west-2"))

    # 3. Run your agent logic
    result = run_agent(prompt, token, endpoint, inference_params, headers)

    # 4. Compute reward based on your task's success criteria
    reward = compute_reward(result)

    # 5. Report completion with reward to RFT Runtime
    # decorator handles CompleteRollout + UpdateReward
    return {"reward": reward}

def run_agent(prompt: str, token: str, endpoint: str, inference_params: dict, headers: dict) -> str:
    """Your agent logic goes here."""
    import openai
    client = openai.OpenAI(
        base_url=(endpoint or os.environ.get("RFT_RUNTIME_ENDPOINT", "")) + "/v1",
        api_key=token,
        default_headers=headers,
    )

    response = client.chat.completions.create(
        model="default",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=inference_params.get("maxTokens", 256),
        temperature=inference_params.get("temperature", 1.0),
        top_p=inference_params.get("topP", 1.0),
    )

    return response.choices[0].message.content

def compute_reward(result: str) -> float:
    """Implement your task-specific reward function here."""

@app.get("/health")
def health():
    return {"status": "ok"}

Instal dependensi yang diperlukan di lingkungan agen Anda:

pip install sagemaker-train fastapi uvicorn openai

Menyebarkan agen Anda

Agen Anda dapat berjalan di lingkungan komputasi apa pun. Dibutuhkan akses jaringan keluar untuk mencapai SageMaker AI Runtime untuk inferensi dan pelaporan hadiah. Jika forwarder Lambda memanggil agen Anda secara langsung, agen Anda juga harus mengekspos titik akhir HTTP yang dapat dijangkau dari Lambda.

Langkah-langkah berikut menerapkan agen kustom ke Amazon EKS.

Buat kluster EKS

Untuk petunjuk penyiapan EKS lengkap, lihat panduan Memulai EKS. Berikut ini adalah pengaturan minimal untuk contoh ini:

eksctl create cluster \
  --name external-agent \
  --region us-west-2 \
  --nodegroup-name agent-nodes \
  --node-type t3.medium \
  --nodes 1 \
  --nodes-min 1 \
  --nodes-max 2 \
  --managed

Perbarui kubeconfig Anda untuk terhubung ke cluster:

aws eks update-kubeconfig --name external-agent --region us-west-2

Bangun dan dorong gambar kontainer Anda:

aws ecr create-repository --repository-name my-external-agent --region us-west-2

aws ecr get-login-password --region us-west-2 | \
  docker login --username AWS --password-stdin account-id.dkr.ecr.us-west-2.amazonaws.com

docker build -t my-external-agent .
docker tag my-external-agent:latest account-id.dkr.ecr.us-west-2.amazonaws.com/my-external-agent:latest
docker push account-id.dkr.ecr.us-west-2.amazonaws.com/my-external-agent:latest

Terapkan ke EKS:

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: external-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: external-agent
  template:
    metadata:
      labels:
        app: external-agent
    spec:
      containers:
      - name: agent
        image: <account-id>.dkr.ecr.us-west-2.amazonaws.com/external-agent:latest
        ports:
        - containerPort: 8080
        env:
        - name: AWS_REGION
          value: us-west-2
        - name: RFT_RUNTIME_ENDPOINT
          value: https://job-runtime.sagemaker.us-west-2.api.aws
---
apiVersion: v1
kind: Service
metadata:
  name: external-agent
spec:
  selector:
    app: external-agent
  ports:
  - port: 80
    targetPort: 8080
  type: LoadBalancer
EOF

Dapatkan titik akhir agen Anda:

AGENT_ENDPOINT=$(kubectl get svc external-agent -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')

echo "Agent endpoint: http://$AGENT_ENDPOINT"

Verifikasi penerapan:

curl -s "http://$AGENT_ENDPOINT/health"

# Expected: {"status": "ok"}

Buat forwarder Lambda Anda

Forwarder Lambda menerima permintaan peluncuran dari SageMaker AI dan meneruskannya ke agen Anda. Hal utama untuk menyesuaikan adalah _call_agent() fungsi, yang menerjemahkan permintaan peluncuran ke dalam format API agen Anda.

Jika agen Anda tidak memiliki titik akhir HTTP publik, Anda dapat mengganti panggilan HTTP _call_agent() dengan SQS send_message dan meminta agen Anda melakukan polling antrian sebagai gantinya.

"""
Lambda Template

Bridges SageMaker Job rollout requests to any agent platform with a public endpoint.
Implement _call_agent() with your platform-specific logic.

If your agent environment does not have a public endpoint, you can
replace the HTTP call with an SQS send_message to enqueue the request,
and have your agent poll the queue for work.

Env vars:
    AGENT_ENDPOINT  - target agent base URL
    AGENT_API_KEY   - API key for the target agent (prefer Secrets Manager)
"""

import json
import logging
import os
import re
import urllib.error
import urllib.request

logger = logging.getLogger()
logger.setLevel(os.environ.get("LOG_LEVEL", "INFO"))

AGENT_ENDPOINT = os.environ.get("AGENT_ENDPOINT", "")
AGENT_API_KEY = os.environ.get("AGENT_API_KEY", "")

_SAFE_ID = re.compile(r"^[\w\-.]+$")

# ---------------------------------------------------------------------------
# CUSTOMIZE THIS - translate rollout request to your platform's API
# ---------------------------------------------------------------------------
def _call_agent(prompt: str, metadata: dict, inference_params: dict):
    """
    Forward the prompt to your agent platform.
    Replace the body below with your platform's request format.
    """
    payload = json.dumps({
        "prompt": prompt,
        "metadata": metadata,
        "inferenceParams": inference_params,
    }).encode()

    req = urllib.request.Request(
        AGENT_ENDPOINT,
        data=payload,
        headers={
            "Content-Type": "application/json",
            "Authorization": f"Bearer {AGENT_API_KEY}",
        },
        method="POST",
    )

    urllib.request.urlopen(req, timeout=120)


# ---------------------------------------------------------------------------
# Validation - no changes needed below
# ---------------------------------------------------------------------------
def _validate(event: dict) -> dict:
    body = json.loads(event["body"]) if isinstance(event.get("body"), str) else event

    prompt = body.get("prompt")
    if not isinstance(prompt, str) or not prompt.strip():
        raise ValueError("'prompt' is required and must be a non-empty string")

    meta = body.get("metadata")
    if not isinstance(meta, dict):
        raise ValueError("'metadata' is required")
    for key in ("jobArn", "rolloutId"):
        val = meta.get(key)
        if not isinstance(val, str) or not val.strip():
            raise ValueError(f"metadata.{key} must match [a-zA-Z0-9_\\-.]")

    params = body.get("inferenceParams") or {}
    if not isinstance(params, dict):
        raise ValueError("'inferenceParams' must be an object")

    return {
        "prompt": prompt.strip(),
        "metadata": meta,
        "inferenceParams": params,
    }


# ---------------------------------------------------------------------------
# CUSTOMIZE THIS - handle errors thrown from your agent environment
# ---------------------------------------------------------------------------
def _handle_agent_error(exc: Exception) -> dict:
    """
    Called when _call_agent() raises an exception. Customize this to map
    platform-specific errors to appropriate error types and messages.

    The return payload must follow this structure:
        {"errorType": "<type>", "errorMessage": "<description>"}

    Supported errorType values:
        ValidationError, InternalServerError, AccessDenied

    Examples:
          return {"errorType": "AccessDenied","errorMessage": "Agent denied access"}
          return {"errorType": "ValidationError","errorMessage": "Missing required field"}
          return {"errorType":"InternalServerError", "errorMessage": str(exc)}
    """

def handler(event, context):
    try:
        body = _validate(event)
    except ValueError as exc:
        logger.warning("Validation error: %s", exc)
        return {"errorType": "ValidationError", "errorMessage": str(exc)}

    try:
        result = _call_agent(body["prompt"], body["metadata"], body["inferenceParams"])
        logger.info("Rollout %s completed", body["metadata"]["rolloutId"])
        return {}
    except Exception as exc:
        return _handle_agent_error(exc)

Menyebarkan fungsi Lambda:

Package fungsi Lambda:

zip lambda_forwarder.zip lambda_forwarder.py

Buat fungsi:

aws lambda create-function \
  --function-name rft-agent-forwarder \
  --runtime python3.12 \
  --handler lambda_forwarder.handler \
  --role arn:aws:iam::account-id:role/RFTLambdaForwarderRole \
  --zip-file fileb://lambda_forwarder.zip \
  --timeout 600 \
  --environment "Variables={AGENT_ENDPOINT=http://$AGENT_ENDPOINT}" \
  --region us-west-2

Uji Lambda:

aws lambda invoke \
  --function-name rft-agent-forwarder \
  --cli-binary-format raw-in-base64-out \
  --payload '{"prompt": "Plan a 3-day itinerary for a trip to Seattle", "metadata": {"jobArn": "arn:aws:sagemaker:us-west-2:123456789012:job/AgentRFT/test", "rolloutId": "roll-1"}}' \
  --region us-west-2 \
  /tmp/response.json && cat /tmp/response.json