For the complete documentation index, see llms.txt.
Skip to main content
Version: 8.11 (unreleased)

Amazon SageMaker connector

Invoke a model deployed in Amazon SageMaker from your BPMN process and use the inference result in later steps.

About this connector​

The Amazon SageMaker connector is an outbound connector that sends inference requests to a SageMaker endpoint. Use it to score data with a machine learning model as part of a process, for example to classify a document or predict a value.

The connector supports two inference types:

  • Real-time: Calls the InvokeEndpoint action, waits for the model, and returns the inference result.
  • Asynchronous: Calls the InvokeEndpointAsync action, which reads the input from Amazon S3 and returns the locations where SageMaker writes the output.

Prerequisites​

To use the Amazon SageMaker connector, you need the following:

PrerequisiteDescription
Deployed SageMaker endpointA real-time or asynchronous endpoint that points to your operational model. Learn more about deploying models in the SageMaker documentation.
AWS IAM user and permissionsAn IAM access key and secret key pair with permission to run InvokeEndpoint (real-time) or InvokeEndpointAsync (asynchronous). Not required if you use the default credentials chain (hybrid/Self-Managed only) or a saved AWS credential.
note

Use secrets to store credentials and avoid exposing sensitive information directly from the process. Refer to managing secrets to learn more.

Use this connector​

New to using an outbound connector? Learn how to add and use this type of connector, apply element templates, use connector secrets, handle results and errors, and more.

Configuration​

Authentication​

Select an authentication method for the connector. Learn more about the available options in AWS authentication types.

PropertyTypeRequiredDescriptionExample
AWS credentialConfigurationNoSelect a saved AWS credential, which can include a default region. When you select a credential, the Authentication, Access key, and Secret key fields are hidden. Learn more about credentials.
AuthenticationDropdownYesThe AWS authentication strategy: Credentials, or Default Credentials Chain (Hybrid/Self-Managed only). Shown when no AWS credential is selected.Credentials
Access keyStringYesIAM access key of a user with permissions to the SageMaker InvokeEndpoint or InvokeEndpointAsync actions. Shown when Authentication is Credentials and no AWS credential is selected.{{secrets.MY_AWS_ACCESS_KEY}}
Secret keyStringYesIAM secret key of the user with the access key above. Shown when Authentication is Credentials and no AWS credential is selected.{{secrets.MY_AWS_SECRET_KEY}}

Region​

PropertyTypeRequiredDescriptionExample
RegionStringYesThe AWS region of the deployed endpoint. When you select an AWS credential, this field is optional: it overrides the credential's default region, and is required if the credential has no default region.us-east-1

Inference settings​

These properties apply to both inference types. Select the inference type first, because it determines which other properties appear.

PropertyTypeRequiredDescriptionExample
Inference typeDropdownYesThe type of inference: Real-time or Asynchronous.Real-time
Endpoint nameStringYesThe name of the deployed SageMaker endpoint to invoke.my-model-endpoint
Content typeStringYesThe MIME type of the input data. The default is application/json.application/json
AcceptStringYesThe desired MIME type of the inference response from the model container. The default is application/json.application/json
Custom attributesStringNoAdditional information about the inference request, passed to the model hosted at the endpoint.session=1234
Inference IDStringNoAn identifier for the inference request. If you provide a value, SageMaker adds it to the captured data when you enable data capture on the endpoint.order-1001

Job timeout​

PropertyTypeRequiredDescriptionExample
Job timeoutStringNoAn ISO-8601 duration after which Zeebe considers the job timed out if it is not completed yet. Leave empty to use the default timeout.PT5M

Operations​

Invoke a real-time endpoint​

Send data to a real-time endpoint and return the inference result. Select Real-time in Inference type. Ensure you deployed your model with a real-time endpoint.

The connector currently supports only JSON-like content types for real-time inference.

Input parameters​

In addition to the inference settings, configure the following properties.

PropertyTypeRequiredDescriptionExample
PayloadTextYesThe input data your deployed model requires. Use a FEEL expression to build it from process variables.= { "features": [1.2, 3.4] }
Target modelStringNoThe model to request for inference when you invoke a multi-model endpoint.model-a.tar.gz
Target variantStringNoThe production variant to send the inference request to.AllTraffic
Target invocation host nameStringNoThe host name of the container to invoke, if the endpoint hosts multiple containers and uses direct invocation.
Enable explanationsDropdownYesWhether SageMaker explains the request: Not set, True, or False.Not set
Inference component nameStringNoThe name of the inference component to invoke, if the endpoint hosts one or more inference components.

Learn more about these properties in the InvokeEndpoint documentation.

Output​

The connector returns an object with the following fields:

FieldDescription
bodyThe inference result. If the response content type is application/json, the connector parses it into an object. Otherwise, it is a string.
contentTypeThe content type of the response.
customAttributesThe custom attributes returned by the endpoint.
invokedProductionVariantThe production variant that processed the request.

The content of body depends on your deployed model. For example:

{
"body": {
"predictions": [{ "label": "approved", "score": 0.94 }]
},
"contentType": "application/json",
"customAttributes": "session=1234",
"invokedProductionVariant": "AllTraffic"
}

To map the response into process variables, use Result variable to store the whole response, or Result expression to map individual fields:

= {
"decision": response.body.predictions[1].label,
"score": response.body.predictions[1].score
}

Invoke an asynchronous endpoint​

Queue an inference request against an asynchronous endpoint and return the locations of the result. Select Asynchronous in Inference type. The request payload must already be stored in Amazon S3.

For asynchronous inference, the connector doesn't wait for the model result. It returns once SageMaker accepts the request. Read the output from the returned outputLocation after SageMaker finishes processing.

Input parameters​

In addition to the inference settings, configure the following properties.

PropertyTypeRequiredDescriptionExample
Input locationStringYesThe Amazon S3 URI where the inference request payload is stored.s3://my-bucket/input/data.json
Request time-to-leave in secondsStringNoThe maximum age in seconds a request can be in the queue before it is marked as expired. The default is 21,600 seconds.21600
Invocation timeout in secondsStringNoThe maximum time in seconds a request can be processed before it is marked as expired. The default is 900 seconds.900

For asynchronous inference, the connector supports any content type. Learn more about these properties in the InvokeEndpointAsync documentation.

Output​

The connector returns an object with the following fields:

FieldDescription
outputLocationThe Amazon S3 location where SageMaker stores the inference output.
failureLocationThe Amazon S3 location where SageMaker stores the output if it fails.
inferenceIdThe identifier of the inference request.

For example:

{
"outputLocation": "s3://my-bucket/async-output/4d7c1f.out",
"failureLocation": "s3://my-bucket/async-failure/4d7c1f-error.out",
"inferenceId": "order-1001"
}

To store the output location in a process variable, use Result expression:

= {
"inferenceOutput": response.outputLocation
}

AWS authentication types​

You can authenticate the connector with AWS in the following ways:

  • Credentials: Use this option if your AWS account administrator provided a pair of access and secret keys. It applies to SaaS and Self-Managed.
  • Default Credentials Chain (Hybrid/Self-Managed only): Use this option if your system relies on an implicit authentication mechanism, such as role-based authentication, credentials supplied through environment variables, or files on the target host. It applies only to Self-Managed or hybrid distributions, and uses the Default Credential Provider Chain to resolve credentials.
  • AWS credential: Select a saved credential instead of entering authentication details on the task.

Troubleshooting​

To learn about general error handling in Camunda, see BPMN errors and failing jobs.

Further resources​