Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

Bereite deinen Agenten vor

Bevor Sie einen Schulungsjob starten können, müssen Sie einen Agenten einrichten, der an der Schulungsschleife teilnehmen kann. In diesem Abschnitt erfahren Sie, wie Sie Ihren Agenten konfigurieren und bereitstellen, unabhängig davon, ob Sie Amazon Bedrock AgentCore für verwaltetes Hosting verwenden oder Ihre eigene Infrastruktur mit einem benutzerdefinierten Agenten verwenden.

Überblick über die Integration des Agentencodes

Während des Trainings sendet SageMaker KI Eingabeaufforderungen aus Ihrem Trainingsdatensatz an Ihren Agenten. Ihr Agent verarbeitet jede Aufforderung, ruft das Richtlinienmodell auf, um eine Antwort zu erhalten, und ergreift Maßnahmen in Ihrer Umgebung, z. B. das Aufrufen von Tools. Das Richtlinienmodell ist das Modell, das trainiert wird. Es beginnt mit Ihrem Basismodell und seine Gewichtungen werden im Laufe der Zeit aktualisiert, wenn es Feedback aus der Trainingsschleife erhält. Auf der Grundlage des Ergebnisses meldet Ihr Agent eine Belohnung an die SageMaker KI zurück, um die Trainingsschleife abzuschließen. Dies wiederholt sich für alle Eingabeaufforderungen in Ihrem Datensatz, und das Richtlinienmodell verbessert sich im Laufe der Zeit auf der Grundlage der gesammelten Prämien.

SageMaker AI Job Runtime Service

Während der Schulung kommuniziert Ihr Agent mit dem SageMaker AI Job Runtime Service, um das Richtlinienmodell zur Inferenz aufzurufen und die Ergebnisse an den Trainer zurückzumelden. Der SDK-Decorator verarbeitet diese Integration automatisch. Wenn Ihr Agent jedoch benutzerdefinierte Anforderungen hat, können Sie die Runtime-APIs direkt aufrufen.

Endpunkt

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

APIs

Authentifizierung

Ihr Agent authentifiziert sich beim Runtime Service mithilfe von Bearer-Token. Generieren Sie mithilfe des SDK ein Token:

from sagemaker.core.token_generator import generate_token

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

Übergeben Sie dieses Token als API-Schlüssel, wenn Sie den Runtime Service aufrufen.

Direkte API-Integration (fortgeschritten)

Wenn Ihr Agenten-Framework den SDK-Decorator nicht verwenden kann, rufen Sie die APIs direkt auf:

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.

Bereitstellungsoptionen für Agenten

SageMaker KI unterstützt zwei Optionen, um Ihren Agenten mit der Trainingsschleife zu verbinden:

Szenario 1: Agenten auf Bedrock Runtime AgentCore

Stellen Sie Ihren Agenten AgentCore für vollständig verwaltetes Hosting auf Amazon Bedrock bereit. SageMaker KI ruft Ihren Agenten während des Modelltrainings auf.

Voraussetzungen

Bevor Sie beginnen, müssen Sie die folgenden Voraussetzungen erfüllen.

Rolle bei der AgentCore Ausführung von Bedrock

Während des Trainings übernimmt SageMaker KI Ihre SageMaker Ausführungsrolle, um Ihren Agenten aufzurufen. Ihr Agent benötigt außerdem eine eigene Rolle, die sogenannte AgentCore Bedrock-Ausführungsrolle, um die RFT-Runtime für Modellinferenzen und Prämienberichte aufzurufen. Die RFT-Runtime ist der SageMaker KI-Dienstendpunkt, mit dem Ihr Agent während des Trainings kommuniziert. Sie kümmert sich um zwei Dinge: die Bereitstellung von Antworten aus dem Policy-Modell während der Inferenz und den Empfang der Belohnung, die Ihr Agent am Ende jedes Rollouts meldet.

Erstellen Sie die AgentCore Bedrock-Ausführungsrolle mit der folgenden Vertrauensrichtlinie. Diese Richtlinie erteilt Bedrock die AgentCore Erlaubnis, die Rolle während der Schulung in Ihrem Namen zu übernehmen. Ohne sie kann Bedrock AgentCore nicht auf Ihr Container-Image zugreifen oder die RFT-Runtime aufrufen.

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

Fügen Sie dann die AmazonSageMakerJobRuntimeAccessverwaltete Richtlinie dieser Rolle hinzu. Dadurch werden Ihrem Agenten die Berechtigungen erteilt, die er benötigt, um das Policy-Modell während der Schulung aufzurufen und Ergebnisse zu melden.

Schreiben oder aktualisieren Sie Ihren Agentencode

Ihr Agent muss das sagemaker-trainSDK verwenden und den @sagemaker_rft_handler Decorator auf die Einstiegsfunktion Ihres Agenten anwenden. Dieser Decorator richtet den HTTP-Server ein, der während des Trainings AgentCore aufgerufen wird. Er wartet auf eingehende Rollout-Anfragen und leitet Eingabeaufforderungen an Ihre Entrypoint-Funktion weiter.

Installieren des SDK

Installieren Sie das SDK mithilfe einer der folgenden Methoden in der Umgebung Ihres Agenten.

Option 1: Direkte Installation

pip install sagemaker-train

Option 2: Räder einzeln bauen und montieren. Verwenden Sie diese Option, wenn die direkte Installation die Größenbeschränkungen Ihrer Umgebung überschreitet.

# 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

Authentifizierung

Ihr Agent authentifiziert sich mithilfe von Bearer-Token bei SageMaker KI. Generieren Sie mithilfe der generate_token() SDK-Methode ein Token und übergeben Sie es als API-Schlüssel, wenn Sie das Richtlinienmodell zur Inferenz aufrufen.

Anforderungen an den Agenten

Ihr Agent muss bei jedem Rollout Folgendes tun:

Das folgende Beispiel zeigt eine grundlegende Agentenvorlage, die das Strands SDK verwendet:

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)}

Stellen Sie Ihren Agenten auf Bedrock bereit AgentCore

Stellen Sie Ihren Agenten gemäß dem AgentCore Entwicklungsleitfaden auf Amazon Bedrock AgentCore bereit.

Nachdem Sie Ihren Agenten mithilfe der AgentCore CLI bereitgestellt haben, notieren Sie sich den Agent-Runtime-ARN aus der Ausgabe. Sie benötigen dies, wenn Sie Ihren Trainingsjob erstellen. Der Runtime-ARN folgt dem Format vonarn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<agent-name>.

Stellen Sie sicher, dass Ihr Agent bereitgestellt und fehlerfrei ist:

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

Szenario 2: Benutzerdefinierter Agent mit Lambda Forwarder

Zusätzlich zu Bedrock unterstützt SageMaker KI benutzerdefinierte Agenten AgentCore, die in jeder Umgebung gehostet werden. Ihr Agent stellt über einen Lambda-Forwarder eine Verbindung zur Trainingsschleife her, sodass Sie die Flexibilität haben, jedes Agenten-Framework und jede Hosting-Plattform Ihrer Wahl zu verwenden.

Ihr Agent kann mit jedem Framework oder jeder Plattform wie dem Strands Agents SDK oder Ihrer eigenen benutzerdefinierten Implementierung erstellt werden. Es kann in jeder Computerumgebung ausgeführt werden, einschließlich Amazon Bedrock AgentCore, Amazon EKS, Amazon EC2, AWS Fargate oder Ihrer eigenen Infrastruktur.

Die Lambda-Funktion empfängt Rollout-Anfragen von SageMaker KI und leitet sie an den HTTP-Endpunkt Ihres Agenten weiter.

Die folgenden Abschnitte enthalten weitere Informationen zum Einrichten eines benutzerdefinierten Agenten mit einem Lambda-Forwarder, mit Beispielen für die Verwendung eines benutzerdefinierten Agenten, der auf Amazon EKS bereitgestellt wird.

Voraussetzungen

Lambda-Ausführungsrolle

Während des Trainings übernimmt SageMaker KI Ihre SageMaker Ausführungsrolle, um Ihren Lambda-Forwarder aufzurufen. Die Lambda-Funktion benötigt eine eigene Ausführungsrolle, damit AWS Lambda sie ausführen kann. Diese Rolle ermöglicht es Lambda, Protokolle auszuführen und zu schreiben.

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

Schreiben Sie Ihren Agentencode

Ihr Agent muss einen HTTP-Endpunkt bereitstellen, der Rollout-Anfragen akzeptiert und mit dem RFT-Runtime-Dienst interagiert, indem er ihn zur Modellinferenz aufruft und die Belohnungen meldet, sobald die Aufgabe abgeschlossen ist.

Format der Rollout-Anfrage

Ihr Agent erhält Anfragen im folgenden Format vom Lambda-Forwarder:

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

Erwartungen des Agenten

Damit Amazon SageMaker AI Rollouts erfolgreich abschließen kann, muss Ihr Agent:

Das folgende Beispiel zeigt einen benutzerdefinierten Agenten mit einem FastAPI-Endpunkt:

"""
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"}

Installieren Sie die erforderlichen Abhängigkeiten in Ihrer Agentenumgebung:

pip install sagemaker-train fastapi uvicorn openai

Stellen Sie Ihren Agenten bereit

Ihr Agent kann in jeder Computerumgebung ausgeführt werden. Er benötigt ausgehenden Netzwerkzugriff, um die SageMaker AI Runtime für Inferenz- und Prämienberichte zu erreichen. Wenn der Lambda-Forwarder Ihren Agenten direkt anruft, muss Ihr Agent auch einen HTTP-Endpunkt verfügbar machen, der von Lambda aus erreichbar ist.

Mit den folgenden Schritten wird ein benutzerdefinierter Agent für Amazon EKS bereitgestellt.

Erstellen Sie einen EKS-Cluster

Vollständige Anweisungen zur Einrichtung von EKS finden Sie im Handbuch Erste Schritte mit EKS. Im Folgenden finden Sie eine Minimalkonfiguration für dieses Beispiel:

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

Aktualisieren Sie Ihre kubeconfig, um eine Verbindung zum Cluster herzustellen:

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

Erstellen Sie Ihr Container-Image und übertragen Sie es:

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

Auf EKS bereitstellen:

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

Holen Sie sich Ihren Agenten-Endpunkt:

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

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

Überprüfen Sie die Bereitstellung:

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

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

Erstellen Sie Ihren Lambda-Forwarder

Der Lambda-Forwarder empfängt Rollout-Anfragen von SageMaker KI und leitet sie an Ihren Agenten weiter. Das Wichtigste, was angepasst werden muss, ist die _call_agent() Funktion, die die Rollout-Anfrage in das API-Format Ihres Agenten übersetzt.

Wenn Ihr Agent keinen öffentlichen HTTP-Endpunkt hat, können Sie den HTTP-Aufruf durch einen SQS ersetzen send_message und stattdessen Ihren Agenten die Warteschlange abfragen lassen. _call_agent()

"""
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)

Stellen Sie die Lambda-Funktion bereit:

Package Sie die Lambda-Funktion:

zip lambda_forwarder.zip lambda_forwarder.py

Erstellen Sie die Funktion:

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

Testen Sie das 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