Creación de un proveedor de modelos personalizado para agentes de Strands con LLM alojados en puntos finales de IA de SageMaker

Las organizaciones implementan cada vez más modelos de habla egregio (LLM) personalizados en puntos finales de IA en tiempo actual de Amazon SageMaker utilizando sus marcos de servicio preferidos, como SGLang, vLLM o TorchServe, para ayudar a obtener un longevo control sobre sus implementaciones, optimizar costos y alinearse con los requisitos de cumplimiento. Sin bloqueo, esta flexibilidad introduce un desafío técnico crítico: incompatibilidad de formato de respuesta con agentes de Strands. Si aceptablemente estos marcos de servicio personalizados generalmente devuelven respuestas en formatos compatibles con OpenAI para simplificar un amplio soporte del entorno, Agentes de hebras Espere respuestas maniquí alineadas con el formato API de Bedrock Messages.

El desafío es particularmente importante porque la compatibilidad con la API de mensajes no está garantizada para los modelos alojados en SageMaker IA puntos finales en tiempo actual. Mientras Motor de inferencia distribuida Amazon Bedrock Mantle ha admitido los formatos de transporte OpenAI desde diciembre de 2025, la flexibilidad de SageMaker AI permite a los clientes penetrar varios modelos básicos, algunos de los cuales requieren formatos esotéricos de mensajes y respuestas que no se ajustan a las API habitual. Esto crea una brecha entre la estructura de salida del ámbito de servicio y lo que Strands dilación, lo que impide una integración perfecta a pesar de que los dos sistemas son técnicamente funcionales. La decisión está en implementar analizadores de modelos personalizados que se extienden SageMakerAIModelo y traducir el formato de respuesta del servidor maniquí a lo que Strands dilación, permitiendo a las organizaciones beneficiarse sus marcos de servicio preferidos sin inmolar la compatibilidad con el SDK de Strands Agents.

Esta publicación demuestra cómo crear analizadores de modelos personalizados para agentes de Strands cuando se trabaja con LLM alojados en SageMaker que no admiten de forma nativa el formato API de Bedrock Messages. Revisaremos la implementación de Lumbre 3.1 con SGLang en SageMaker usando awslabs/ml-contenedor-creadory luego implementar un analizador personalizado para integrarlo con los agentes de Strands.

Analizadores personalizados de Strands

Los agentes de Strands esperan respuestas maniquí en un formato específico seguidor con la API de Bedrock Messages. Cuando implementa modelos utilizando marcos de servicio personalizados como SGLang, vLLM o TorchServe, normalmente devuelven respuestas en sus propios formatos, a menudo compatibles con OpenAI para un amplio soporte del entorno. Sin un analizador personalizado, encontrará errores como:

TypeError: 'NoneType' object is not subscriptable

Esto sucede porque los agentes de Strands incumplen SageMakerAIModel La clase intenta analizar las respuestas asumiendo una estructura específica que su punto final personalizado no proporciona. En esta publicación y en la pulvínulo del código complementario, ilustramos cómo extender el SageMakerAIModel clase con razonamiento de exploración personalizada que traduce el formato de respuesta de su servidor maniquí a lo que Strands dilación.

Descripción universal de la implementación

Nuestra implementación consta de tres capas:

Capa de implementación del maniquí: Lumbre 3.1 servido por SGLang en SageMaker, que devuelve respuestas compatibles con OpenAI
Capa de analizador: Costumbre LlamaModelProvider clase que se extiende SageMakerAIModel para manejar el formato de respuesta de Lumbre 3.1
Capa de agente: Agente de Strands que utiliza el proveedor personalizado para la IA conversacional, analizando adecuadamente la respuesta del maniquí.

Empezamos usando awslabs/ml-contenedor-creadorun creador Yeoman de código franco de AWS Labs que automatiza la creación de proyectos de implementación BYOC (Bring Your Own Container) de SageMaker. Genera los artefactos necesarios para crear contenedores de servicio LLM, incluidos Dockerfiles, configuraciones de CodeBuild y scripts de implementación.

Instalar ml-contenedor-creador

El primer paso que debemos dar es construir el recipiente para servir para nuestro maniquí. Usamos un esquema de código franco para construir el contenedor y crear scripts de implementación para ese contenedor. Los siguientes comandos ilustran cómo instalar awslabs/ml-contenedor-creador y sus dependencias, que incluyen mpn y Rico. Para obtener más información, revise el esquema LÉAME y wiki para emprender.

# Install Yeoman globally
npm install -g yo

# Clone and install ml-container-creator
git clone https://github.com/awslabs/ml-container-creator
cd ml-container-creator
npm install && npm link

# Verify installation
yo --generators # Should show ml-container-creator

Crear esquema de implementación

Una vez instalado y vinculado, el comando yo le permite ejecutar los generadores instalados, yo ml-container-creator le permite ejecutar el creador que necesitamos para este adiestramiento.

# Run the generator
yo ml-container-creator

# Configuration options:
# - Framework: transformers
# - Model Server: sglang
# - Model: meta-llama/Lumbre-3.1-8B-Instruct
# - Deploy Target: codebuild
# - Instance Type: ml.g6.12xlarge (GPU)
# - Region: us-east-1

El creador crea una estructura de esquema completa:

/
├── Dockerfile # Container with SGLang and dependencies
├── buildspec.yml # CodeBuild configuration
├── code/
│ └── serve # SGLang server startup script
├── deploy/
│ ├── submit_build.sh # Triggers CodeBuild
│ └── deploy.sh # Deploys to SageMaker
└── test/
└── test_endpoint.sh # Endpoint testing script

Construir e implementar

Proyectos construidos por awslabs/ml-contenedor-creador Incluye scripts de compilación e implementación con plantillas. El ./deploy/submit_build.sh and ./deploy/deploy.sh Los scripts se utilizan para crear la imagen, enviarla a Amazon Elastic Container Registry (ECR) e implementarla en un punto final de IA en tiempo actual de Amazon SageMaker.

cd llama-31-deployment

# Build container with CodeBuild (no restringido Docker required)
./deploy/submit_build.sh

# Deploy to SageMaker
./deploy/deploy.sh arn:aws:iam::ACCOUNT:role/SageMakerExecutionRole

El proceso de implementación:

CodeBuild crea la imagen de Docker con SGLang y Lumbre 3.1
La imagen se envía a Amazon ECR
SageMaker crea un punto final en tiempo actual
SGLang descarga el maniquí de HuggingFace y lo carga en la memoria de la GPU
El terminal alcanza el estado InService (aproximadamente entre 10 y 15 minutos)

Podemos probar el punto final usando ./test/test_endpoint.sho con una invocación directa:

import boto3
import json

runtime_client = boto3.client('sagemaker-runtime', region_name="us-east-1")

payload = {
"messages": (
    {"user", "content": "Hello, how are you?"}
  ),
  "max_tokens": 100,
  "temperature": 0.7
}

response = runtime_client.invoke_endpoint(
  EndpointName="llama-31-deployment-endpoint",
  ContentType="application/json",
  Body=json.dumps(payload)
)

result = json.loads(response('Body').read().decode('utf-8'))
print(result('choices')(0)('message')('content'))

Comprender el formato de respuesta

Lumbre 3.1 devuelve respuestas compatibles con OpenAI. Strands dilación que las respuestas del maniquí se adhieran al formato API de Bedrock Messages. Hasta finales del año pasado, esto era una discrepancia de compatibilidad habitual. Desde diciembre de 2025, el El motor de inferencia distribuida de Amazon Bedrock Mantle admite formatos de transporte OpenAI:

{
  "id": "cmpl-abc123",
  "object": "chat.completion",
  "created": 1704067200,
  "model": "meta-llama/Lumbre-3.1-8B-Instruct",
  "choices": ({
    "index": 0,
    "message": {"role": "assistant", "content": "I'm doing well, thank you for asking!"},
    "finish_reason": "stop"
  }),
  "usage": {
    "prompt_tokens": 23,
    "completion_tokens": 12,
    "total_tokens": 35
  }
}

Sin bloqueo, la compatibilidad con la API de mensajes no está garantizada para los modelos alojados en puntos finales en tiempo actual de SageMaker AI. SageMaker AI permite a los clientes penetrar muchos tipos de modelos básicos en una infraestructura administrada acelerada por GPU, algunos de los cuales pueden requerir formatos esotéricos de aviso/respuesta. Por ejemplo, el valencia predeterminado SageMakerAIModel utiliza el formato API de Bedrock Messages heredado e intenta conseguir a campos que no existen en el formato habitual de OpenAI Messages, lo que provoca TypeError Fallos de estilo.

Implementación de un analizador de modelos personalizado

Los analizadores de modelos personalizados son una característica del SDK de agentes de Strands que proporciona una gran compatibilidad y flexibilidad para los clientes que crean agentes impulsados por LLM alojados en SageMaker AI. Aquí describimos cómo crear un proveedor personalizado que extienda SageMakerAIModel:

def stream(self, messages: List(Dict(str, Any)), tool_specs: list, system_prompt: Optional(str), **kwargs):
  # Build payload messages
  payload_messages = ()
  if system_prompt:
    payload_messages.append({"role": "system", "content": system_prompt})
    # Extract message content from Strands format
    for msg in messages:
      payload_messages.append({"role": "user", "content": msg('content')(0)('text')})
      
      # Build complete payload with streaming enabled
      payload = {
        "messages": payload_messages,
        "max_tokens": kwargs.get('max_tokens', self.max_tokens),
        "temperature": kwargs.get('temperature', self.temperature),
        "top_p": kwargs.get('top_p', self.top_p),
        "stream": True
      }

      try:
        # Invoke SageMaker endpoint with streaming
        response = self.runtime_client.invoke_endpoint_with_response_stream(
          EndpointName=self.endpoint_name,
          ContentType="application/json",
          Accept="application/json",
          Body=json.dumps(payload)
        )

        # Process streaming response
        accumulated_content = ""
          for event in response('Body'):
            chunk = event('PayloadPart')('Bytes').decode('utf-8')
            if not chunk.strip():
              continue
    
            # Parse SSE format: "data: {json}n"
            for line in chunk.split('n'):
              if line.startswith('data: '):
                try:
                  json_str = line.replace('data: ', '').strip()
                  if not json_str:
                    continue
                  
                  chunk_data = json.loads(json_str)
                  if 'choices' in chunk_data and chunk_data('choices'):
                    delta = chunk_data('choices')(0).get('delta', {})

                    # Yield content delta in Strands format
                    if 'content' in delta:
                      content_chunk = delta('content')
                      accumulated_content += content_chunk
                      yield {
                        "type": "contentBlockDelta",
                        "delta": {"text": content_chunk},
                        "contentBlockIndex": 0
                      }

                    # Check for completion
                    finish_reason = chunk_data('choices')(0).get('finish_reason')
                    if finish_reason:
                      yield {
                        "type": "messageStop",
                        "stopReason": finish_reason
                      }

                    # Yield usage metadata
                    if 'usage' in chunk_data:
                      yield {
                        "type": "metadata",
                        "usage": chunk_data('usage')
                      }

                except json.JSONDecodeError:
                  continue

      except Exception as e:
        yield {
          "type": "error",
          "error": {
            "message": f"Endpoint invocation failed: {str(e)}",
            "type": "EndpointInvocationError"
          }
      }

El método de flujo anula el comportamiento del SageMakerAIModel y permite al agente analizar respuestas basadas en los requisitos del maniquí subyacente. Si aceptablemente la gran mayoría de los modelos son compatibles con el protocolo Message API de OpenAI, esta capacidad permite a los usuarios avanzados beneficiarse LLM enormemente específicos en SageMaker AI para impulsar cargas de trabajo de agentes utilizando Strands Agents SDK. Una vez creada la razonamiento de respuesta del maniquí personalizado, Strands Agents SDK simplifica la inicialización de agentes con proveedores de modelos personalizados:

from strands.agent import Agent

# Initialize custom provider
provider = LlamaModelProvider(
  endpoint_name="llama-31-deployment-endpoint",
  region_name="us-east-1",
  max_tokens=1000,
  temperature=0.7
)

# Create agent with custom provider
agent = Agent(
  name="llama-assistant",
  model=provider,
  system_prompt=(
    "You are a helpful AI assistant powered by Lumbre 3.1, "
    "deployed on Amazon SageMaker. You provide clear, accurate, "
    "and friendly responses to user questions."
  )
)

# Test the agent
response = agent("What are the key benefits of deploying LLMs on SageMaker?")
print(response.content)

La implementación completa de este analizador personalizado, incluido el cuaderno Jupyter con explicaciones detalladas y el esquema de implementación ml-container-creator, está habitable en el complemento repositorio de GitHub.

Conclusión

La creación de analizadores de modelos personalizados para agentes de Strands ayuda a los usuarios a beneficiarse diferentes implementaciones de LLM en SageMaker, independientemente de su formato de respuesta. Al extender SageMakerAIModel e implementar el stream() método, puede integrar modelos alojados personalizados mientras mantiene la interfaz de agente limpia de Strands.

Conclusiones esencia:

awslabs/ml-contenedor-creador simplifica las implementaciones BYOC de SageMaker con código de infraestructura vivo para producción
Los analizadores personalizados cierran la brecha entre los formatos de respuesta del servidor maniquí y las expectativas de Strands
El método stream() es el punto de integración crítico para los proveedores personalizados.

Sobre los autores

Daniel Ferguson es arquitecto senior de soluciones en AWS, con sede en Nueva York, EE. UU. Como versado en servicios de formación automotriz, Dan trabaja para ayudar a los clientes en su camino en torno a la integración de flujos de trabajo de formación automotriz de guisa apto, efectiva y sostenible.

Etiquetado agentes, alojados, con, creación, finales, LLM, modelos, para, personalizado, proveedor, puntos, SageMaker, Strands