# Tutorial: Get Started Using the Amazon A2I API
This tutorial explains the API operations you can use to get started using Amazon A2I.
To use a Jupyter Notebook to run these operations, select a Jupyter Notebook from [Use Cases and Examples Using Amazon A2I](a2i-task-types-general.md) and use [Use SageMaker Notebook Instance with Amazon A2I Jupyter Notebook](a2i-task-types-general.md#a2i-task-types-notebook-demo) to learn how to use it in a SageMaker AI notebook instance.
To learn more about the API operations you can use with Amazon A2I, see [Use APIs in Amazon Augmented AI](a2i-api-references.md).
## Create a Private Work Team
You can create a private work team and add yourself as a worker so that you can preview Amazon A2I.
If you are not familiar with Amazon Cognito, we recommend that you use the SageMaker AI console to create a private workforce and add yourself as a private worker. For instructions, see [Step 1: Create a Work Team](a2i-get-started-console.md#a2i-get-started-console-step-1).
If you are familiar with Amazon Cognito, you can use the following instructions to create a private work team using the SageMaker API. After you create a work team, note the work team ARN (`WorkteamArn`).
To learn more about the private workforce and other available configurations, see [Private workforce](sms-workforce-private.md).
**Create a private workforce**
If you have not created a private workforce, you can do so using an [Amazon Cognito user pool](https://docs.amazonaws.cn/cognito/latest/developerguide/cognito-user-identity-pools.html). Make sure that you have added yourself to this user pool. You can create a private work team using the Amazon SDK for Python (Boto3) `[create\_workforce](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_workforce)` function. For other language-specific SDKs, refer to the list in [CreateWorkforce](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateWorkforce.html#API_CreateWorkforce_SeeAlso).
```
response = client.create_workforce(
CognitoConfig={
"UserPool": "{{Pool_ID}}",
"ClientId": "{{app-client-id}}"
},
WorkforceName="{{workforce-name}}"
)
```
**Create a private work team**
After you have created a private workforce in the Amazon Region to configure and start your human loop, you can create a private work team using the Amazon SDK for Python (Boto3) `[create\_workteam](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_workteam)` function. For other language-specific SDKs, refer to the list in `[CreateWorkteam](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateWorkteam.html#API_CreateWorkteam_SeeAlso)`.
```
response = client.create_workteam(
WorkteamName="{{work-team-name}}",
WorkforceName= "{{workforce-name}}",
MemberDefinitions=[
{
"CognitoMemberDefinition": {
"UserPool": "{{_ID}}",
"UserGroup": "{{user-group}}",
"ClientId": "{{app-client-id}}"
},
}
]
)
```
Access your work team ARN as follows:
```
workteamArn = response["WorkteamArn"]
```
**List private work teams in your account**
If you have already created a private work team, you can list all work teams in a given Amazon Region in your account using the Amazon SDK for Python (Boto3) `[list\_workteams](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.list_workteams)` function. For other language-specific SDKs, refer to the list in `[ListWorkteams](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_ListWorkteams.html#API_ListWorkteams_SeeAlso)`.
```
response = client.list_workteams()
```
If you have numerous work teams in your account, you may want to use `MaxResults`, `SortBy`, and `NameContains` to filter your results.
## Create a Human Review Workflow
You can create a human review workflow using the Amazon A2I `[CreateFlowDefinition](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateFlowDefinition.html)` operation. Before you create your human review workflow, you need to create a human task UI. You can do this with the `[CreateHumanTaskUi](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateHumanTaskUi.html)` operation.
If you are using Amazon A2I with the Amazon Textract or Amazon Rekognition integrations, you can specify activation conditions using a JSON.
### Create a Human Task UI
If you are creating a human review workflow to be used with Amazon Textract or Amazon Rekognition integrations, you need to use and modify pre-made worker task template. For all custom integrations, you can use your own custom worker task template. Use the following table to learn how to create a human task UI using a worker task template for the two built-in integrations. Replace the template with your own to customize this request.
------
#### [ Amazon Textract – Key-value pair extraction ]
To learn more about this template, see [Custom Template Example for Amazon Textract](a2i-custom-templates.md#a2i-custom-templates-textract-sample).
------
#### [ Amazon Rekognition – Image moderation ]
To learn more about this template, see [Custom Template Example for Amazon Rekognition](a2i-custom-templates.md#a2i-custom-templates-rekognition-sample).
------
#### [ Custom Integration ]
The following is an example template that can be used in a custom integration. This template is used in this [notebook](https://github.com/aws-samples/amazon-a2i-sample-jupyter-notebooks/blob/master/Amazon%20Augmented%20AI%20(A2I)%20and%20Comprehend%20DetectSentiment.ipynb), demonstrating a custom integration with Amazon Comprehend.
------
Using the template specified above, you can create a template using the Amazon SDK for Python (Boto3) `[create\_human\_task\_ui](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_human_task_ui)` function. For other language-specific SDKs, refer to the list in `[CreateHumanTaskUi](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateHumanTaskUi.html#API_CreateHumanTaskUi_SeeAlso)`.
```
response = client.create_human_task_ui(
HumanTaskUiName="{{human-task-ui-name}}",
UiTemplate={
"Content": {{template}}
}
)
```
This response element contains the human task UI ARN. Save this as follows:
```
humanTaskUiArn = response["HumanTaskUiArn"]
```
### Create JSON to specify activation conditions
For Amazon Textract and Amazon Rekognition built-in integrations, you can save activation conditions in a JSON object and use this in your `CreateFlowDefinition` request.
Next, select a tab to see example activation conditions you can use for these built-in integrations. For additional information about activation condition options, see [JSON Schema for Human Loop Activation Conditions in Amazon Augmented AI](a2i-human-fallback-conditions-json-schema.md).
------
#### [ Amazon Textract – Key-value pair extraction ]
This example specifies conditions for specific keys (such as `Mail address`) in the document. If Amazon Textract's confidence falls outside of the thresholds set here, the document is sent to a human for review, with the specific keys that initiated the human loop prompted to the worker.
```
import json
humanLoopActivationConditions = json.dumps(
{
"Conditions": [
{
"Or": [
{
"ConditionType": "ImportantFormKeyConfidenceCheck",
"ConditionParameters": {
"ImportantFormKey": "Mail address",
"ImportantFormKeyAliases": ["Mail Address:","Mail address:", "Mailing Add:","Mailing Addresses"],
"KeyValueBlockConfidenceLessThan": 100,
"WordBlockConfidenceLessThan": 100
}
},
{
"ConditionType": "MissingImportantFormKey",
"ConditionParameters": {
"ImportantFormKey": "Mail address",
"ImportantFormKeyAliases": ["Mail Address:","Mail address:","Mailing Add:","Mailing Addresses"]
}
},
{
"ConditionType": "ImportantFormKeyConfidenceCheck",
"ConditionParameters": {
"ImportantFormKey": "Phone Number",
"ImportantFormKeyAliases": ["Phone number:", "Phone No.:", "Number:"],
"KeyValueBlockConfidenceLessThan": 100,
"WordBlockConfidenceLessThan": 100
}
},
{
"ConditionType": "ImportantFormKeyConfidenceCheck",
"ConditionParameters": {
"ImportantFormKey": "*",
"KeyValueBlockConfidenceLessThan": 100,
"WordBlockConfidenceLessThan": 100
}
},
{
"ConditionType": "ImportantFormKeyConfidenceCheck",
"ConditionParameters": {
"ImportantFormKey": "*",
"KeyValueBlockConfidenceGreaterThan": 0,
"WordBlockConfidenceGreaterThan": 0
}
}
]
}
]
}
)
```
------
#### [ Amazon Rekognition – Image moderation ]
The human loop activation conditions used here are tailored towards Amazon Rekognition content moderation; they are based on the confidence thresholds for the `Suggestive` and `Female Swimwear Or Underwear` moderation labels.
```
import json
humanLoopActivationConditions = json.dumps(
{
"Conditions": [
{
"Or": [
{
"ConditionType": "ModerationLabelConfidenceCheck",
"ConditionParameters": {
"ModerationLabelName": "Suggestive",
"ConfidenceLessThan": 98
}
},
{
"ConditionType": "ModerationLabelConfidenceCheck",
"ConditionParameters": {
"ModerationLabelName": "Female Swimwear Or Underwear",
"ConfidenceGreaterThan": 98
}
}
]
}
]
}
)
```
------
### Create a human review workflow
This section gives an example of the `CreateFlowDefinition` Amazon SDK for Python (Boto3) request using the resources created in the previous sections. For other language-specific SDKs, refer to the list in [CreateFlowDefinition](https://docs.amazonaws.cn/sagemaker/latest/APIReference/API_CreateFlowDefinition.html#API_CreateFlowDefinition_SeeAlso). Use the tabs in the following table to see the requests to create a human review workflow for Amazon Textract and Amazon Rekognition built-in integrations.
------
#### [ Amazon Textract – Key-value pair extraction ]
If you use the built-in integration with Amazon Textract, you must specify `"AWS/Textract/AnalyzeDocument/Forms/V1"` for `"AwsManagedHumanLoopRequestSource"` in `HumanLoopRequestSource`.
```
response = client.create_flow_definition(
FlowDefinitionName="{{human-review-workflow-name}}",
HumanLoopRequestSource={
"AwsManagedHumanLoopRequestSource": "AWS/Textract/AnalyzeDocument/Forms/V1"
},
HumanLoopActivationConfig={
"HumanLoopActivationConditionsConfig": {
"HumanLoopActivationConditions": {{humanLoopActivationConditions}}
}
},
HumanLoopConfig={
"WorkteamArn": {{workteamArn}},
"HumanTaskUiArn": {{humanTaskUiArn}},
"TaskTitle": "{{Document entry review}}",
"TaskDescription": "{{Review the document and instructions. Complete the task}}",
"TaskCount": {{1}},
"TaskAvailabilityLifetimeInSeconds": {{43200}},
"TaskTimeLimitInSeconds": {{3600}},
"TaskKeywords": [
"{{document review}}",
],
},
OutputConfig={
"S3OutputPath": "{{s3://amzn-s3-demo-bucket/prefix/}}",
},
RoleArn="{{arn:aws:iam:::role/}}",
Tags=[
{
"Key": "{{string}}",
"Value": "{{string}}"
},
]
)
```
------
#### [ Amazon Rekognition – Image moderation ]
If you use the built-in integration with Amazon Rekognition, you must specify `"AWS/Rekognition/DetectModerationLabels/Image/V3"` for `"AwsManagedHumanLoopRequestSource"` in `HumanLoopRequestSource`.
```
response = client.create_flow_definition(
FlowDefinitionName="{{human-review-workflow-name}}",
HumanLoopRequestSource={
"AwsManagedHumanLoopRequestSource": "AWS/Rekognition/DetectModerationLabels/Image/V3"
},
HumanLoopActivationConfig={
"HumanLoopActivationConditionsConfig": {
"HumanLoopActivationConditions": {{humanLoopActivationConditions}}
}
},
HumanLoopConfig={
"WorkteamArn": {{workteamArn}},
"HumanTaskUiArn": {{humanTaskUiArn}},
"TaskTitle": "{{Image content moderation}}",
"TaskDescription": "{{Review the image and instructions. Complete the task}}",
"TaskCount": {{1}},
"TaskAvailabilityLifetimeInSeconds": {{43200}},
"TaskTimeLimitInSeconds": {{3600}},
"TaskKeywords": [
"{{content moderation}}",
],
},
OutputConfig={
"S3OutputPath": "{{s3://amzn-s3-demo-bucket/prefix/}}",
},
RoleArn="{{arn:aws:iam:::role/}}",
Tags=[
{
"Key": "{{string}}",
"Value": "{{string}}"
},
]
)
```
------
#### [ Custom Integration ]
If you use a custom integration, exclude the following parameters: `HumanLoopRequestSource`, `HumanLoopActivationConfig`.
```
response = client.create_flow_definition(
FlowDefinitionName="{{human-review-workflow-name}}",
HumanLoopConfig={
"WorkteamArn": {{workteamArn}},
"HumanTaskUiArn": {{humanTaskUiArn}},
"TaskTitle": "{{Image content moderation}}",
"TaskDescription": "{{Review the image and instructions. Complete the task}}",
"TaskCount": {{1}},
"TaskAvailabilityLifetimeInSeconds": {{43200}},
"TaskTimeLimitInSeconds": {{3600}},
"TaskKeywords": [
"{{content moderation}}",
],
},
OutputConfig={
"S3OutputPath": "{{s3://amzn-s3-demo-bucket/prefix/}}",
},
RoleArn="{{arn:aws:iam:::role/}}",
Tags=[
{
"Key": "{{string}}",
"Value": "{{string}}"
},
]
)
```
------
After you create a human review workflow, you can retrieve the flow definition ARN from the response:
```
{{humanReviewWorkflowArn}} = response["FlowDefinitionArn"]
```
## Create a Human Loop
The API operation you use to start a human loop depends on the Amazon A2I integration you use.
+ If you use the Amazon Textract built-in integration, you use the [AnalyzeDocument](https://docs.amazonaws.cn/textract/latest/dg/API_AnalyzeDocument.html) operation.
+ If you use the Amazon Rekognition built-in integration, you use the [DetectModerationLabels](https://docs.amazonaws.cn/rekognition/latest/dg/API_DetectModerationLabels.html) operation.
+ If you use a custom integration, you use the [StartHumanLoop](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_StartHumanLoop.html) operation.
Select your task type in the following table to see example requests for Amazon Textract and Amazon Rekognition using the Amazon SDK for Python (Boto3).
------
#### [ Amazon Textract – Key-value pair extraction ]
The following example uses the Amazon SDK for Python (Boto3) to call `analyze_document` in us-west-2. Replace the italicized red text with your resources. Include the [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopDataAttributes.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopDataAttributes.html) parameter if you are using the Amazon Mechanical Turk workforce. For more information, see the [analyze\_document](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/textract.html#Textract.Client.analyze_document) documention in the *Amazon SDK for Python (Boto) API Reference*.
```
response = client.analyze_document(
Document={"S3Object": {"Bucket": "{{amzn-s3-demo-bucket}}", "Name": "{{document-name.pdf}}"},
HumanLoopConfig={
"FlowDefinitionArn":"{{arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name}}",
"HumanLoopName":"{{human-loop-name}}",
"DataAttributes" : {ContentClassifiers:[{{"FreeOfPersonallyIdentifiableInformation"}}|{{"FreeOfAdultContent"}}]}
}
FeatureTypes=["FORMS"]
)
```
Human loops are only created if Amazon Textract's confidence for document analysis task meets the activation conditions you specified in your human review workflow. You can check the `response` element to determine if a human loop has been created. To see everything included in this response, see [https://docs.amazonaws.cn/textract/latest/dg/API_HumanLoopActivationOutput.html](https://docs.amazonaws.cn/textract/latest/dg/API_HumanLoopActivationOutput.html).
```
if "HumanLoopArn" in analyzeDocumentResponse["HumanLoopActivationOutput"]:
# A human loop has been started!
print(f"A human loop has been started with ARN: {analyzeDocumentResponse["HumanLoopActivationOutput"]["HumanLoopArn"]}"
```
------
#### [ Amazon Rekognition – Image moderation ]
The following example uses the Amazon SDK for Python (Boto3) to call `detect_moderation_labels` in us-west-2. Replace the italicized red text with your resources. Include the [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopDataAttributes.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopDataAttributes.html) parameter if you are using the Amazon Mechanical Turk workforce. For more information, see the [detect\_moderation\_labels](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rekognition.html#Rekognition.Client.detect_moderation_labels) documention in the *Amazon SDK for Python (Boto) API Reference*.
```
response = client.detect_moderation_labels(
Image={"S3Object":{"Bucket": "{{amzn-s3-demo-bucket}}", "Name": "{{image-name.png}}"}},
HumanLoopConfig={
"FlowDefinitionArn":"{{arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name}}",
"HumanLoopName":"{{human-loop-name}}",
"DataAttributes":{ContentClassifiers:[{{"FreeOfPersonallyIdentifiableInformation"}}|{{"FreeOfAdultContent"}}]}
}
)
```
Human loops are only created if Amazon Rekognition's confidence for an image moderation task meets the activation conditions you specified in your human review workflow. You can check the `response` element to determine if a human loop has been created. To see everything included in this response, see [https://docs.amazonaws.cn/rekognition/latest/dg/API_HumanLoopActivationOutput.html](https://docs.amazonaws.cn/rekognition/latest/dg/API_HumanLoopActivationOutput.html).
```
if "HumanLoopArn" in response["HumanLoopActivationOutput"]:
# A human loop has been started!
print(f"A human loop has been started with ARN: {response["HumanLoopActivationOutput"]["HumanLoopArn"]}")
```
------
#### [ Custom Integration ]
The following example uses the Amazon SDK for Python (Boto3) to call `start_human_loop` in us-west-2. Replace the italicized red text with your resources. Include the [https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopDataAttributes.html](https://docs.amazonaws.cn/augmented-ai/2019-11-07/APIReference/API_HumanLoopDataAttributes.html) parameter if you are using the Amazon Mechanical Turk workforce. For more information, see the [start\_human\_loop](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-a2i-runtime.html#AugmentedAIRuntime.Client.start_human_loop) documention in the *Amazon SDK for Python (Boto) API Reference*.
```
response = client.start_human_loop(
HumanLoopName= "{{human-loop-name}}",
FlowDefinitionArn= "{{arn:aws:sagemaker:us-west-2:111122223333:flow-definition/flow-definition-name}}",
HumanLoopInput={"InputContent": {{inputContentJson}}},
DataAttributes={"ContentClassifiers":[{{"FreeOfPersonallyIdentifiableInformation"|"FreeOfAdultContent"}}]}
)
```
This example stores input content in the variable {{`inputContentJson`}}. Assume that the input content contains two elements: a text blurb and sentiment (such as `Positive`, `Negative`, or `Neutral`), and it is formatted as follows:
```
inputContent = {
"initialValue": sentiment,
"taskObject": blurb
}
```
The keys `initialValue` and `taskObject` must correspond to the keys used in the liquid elements of the worker task template. Refer to the custom template in [Create a Human Task UI](#a2i-get-started-api-worker-task-template) to see an example.
To create `{{inputContentJson}}`, do the following:
```
import json
inputContentJson = json.dumps(inputContent)
```
A human loop starts each time you call `start_human_loop`. To check the status of your human loop, use [describe\_human\_loop](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker-a2i-runtime.html#AugmentedAIRuntime.Client.describe_human_loop):
```
human_loop_info = a2i.describe_human_loop(HumanLoopName="{{human_loop_name}}")
print(f"HumanLoop Status: {resp["HumanLoopStatus"]}")
print(f"HumanLoop Output Destination: {resp["HumanLoopOutput"]}")
```
------