Lab 2 - Create Agents with API Schema

标题: “实验 2 - 使用 API 架构创建代理” 权重: 20

在这个实验中， 我们提供了一个使用 Agents for Amazon Bedrock 集成和 Lambda 函数的 API 架构的代理示例。

在创建代理的操作组时， 我们可以通过提供函数详细信息或传递 API 架构来定义操作。当提供 API 架构时， 我们可以更明确地定义操作并将它们映射到系统中的 API 操作。这个选项要求我们的 API 架构文件采用 OpenAPI 格式。我们可以通过以下方式之一将 API 架构添加到操作组:

  • 将我们创建的架构上传到 Amazon Simple Storage Service (Amazon S3) 存储桶。
  • 在向代理添加操作组时， 在 AWS Management Console 中的内联 OpenAPI 架构编辑器中编写架构。这个选项只有在代理所属的操作组已经创建好之后才可用。

该示例代理实现了一个保险理赔处理程序， 可以:

  • 获取未结理赔
  • 获取某个理赔的详细信息
  • 获取现有理赔的缺失文件
  • 发送提醒， 识别任何缺失的文档

创建的代理的架构如下:

使用 OpenAPI 架构格式描述了代理的功能。

下面的代码显示了获取未结理赔功能的请求格式:

{
  "paths": {
    "/open-items": {
      "get": {
        "summary": "获取所有未结保险理赔的列表"，
        "description": "获取所有未结保险理赔的列表。返回所有未结的 claimId。"，
        "operationId": "getAllOpenClaims"，
        "responses": {
          "200": {
            "description": "获取保单持有人的所有未结保险理赔列表"，
            "content": {
              "application/json": {
                "schema": {
                  "type": "array"，
                  "items": {
                    "type": "object"，
                    "properties": {
                      "claimId": {
                        "type": "string"，
                        "description": "理赔的唯一 ID。"
                      }，
                      "policyHolderId": {
                        "type": "string"，
                        "description": "提出理赔的保单持有人的唯一 ID。"
                      }，
                      "claimStatus": {
                        "type": "string"，
                        "description": "理赔的状态。理赔可以处于未结或已结状态。"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }，
    "/open-items/{claimId}/outstanding-paperwork": {
      ...
    }，
    ...
  }
}

这段代码展示了如何为 Bedrock Agents 集成定义 OpenAPI 架构中的 API 路由。它有一个父路由 “/open-items” 和一个提供不同信息的子路由 “/open-items/{claimId}/outstanding-paperwork”。定义这些 API 允许我们的代理知道如何以及何时使用我们的 API 来收集信息。

在创建代理的操作组时， 通过包含 API 架构文件 S3 位置的 apiSchema 参数将架构定义传递给操作组:

agent_action_group_response = bedrock_agent_client.create_agent_action_group(
    agentId=agent_id，
    agentVersion='DRAFT'，
    actionGroupExecutor={
        'lambda': lambda_function['FunctionArn']
    }，
    actionGroupName='ClaimManagementActionGroup'，
    apiSchema={
        's3': {
            's3BucketName': bucket_name，
            's3ObjectKey': bucket_key
        }
    }，
    description='Actions for listing claims， identifying missing paperwork， sending reminders'
)

代理的操作是作为 AWS Lambda 函数的一部分实现的， 该函数通过事件接收来自代理的输入。

事件具有以下结构， 其中 apiPath 提供了用户所需操作的所需路径:

{
    "messageVersion": "1.0"，
    "response": {
        "actionGroup": "string"，
        "apiPath": "string"，
        "httpMethod": "string"，
        "httpStatusCode": number，
        "responseBody": {
            "<contentType>": {
                "body": "JSON-formatted string" 
            }
        }
    }，
    "sessionAttributes": {
        "string": "string"，
    }，
    "promptSessionAttributes": {
        "string": "string"
    }
}

要处理代理请求的操作， 以下代码将添加到 Lambda 函数中:

def get_named_parameter(event， name):
    return next(item for item in event['parameters'] if item['name'] == name)['value']


def get_named_property(event， name):
    return next(
        item for item in
        event['requestBody']['content']['application/json']['properties']
        if item['name'] == name)['value']

def lambda_handler(event， context):
    # 从事件中获取信息
    action_group = event['actionGroup']
    api_path = event['apiPath']
    http_method = event['httpMethod']
    
    # 根据 HTTP 方法获取参数
    if http_method == "get":
        claim_id = get_named_parameter(event， "claim_id")
    elif http_method == "post":
        claim_id = get_named_property(event， "claim_id")
    
    # 设置预期的响应主体
    response_body = {
        'application/json': {
            'body': "sample response"
        }
    }
    
    # 处理请求的逻辑在这里
    ...

    # 最后， 将响应返回给代理
    
    action_response = {
        'actionGroup': event['actionGroup']，
        'apiPath': event['apiPath']，
        'httpMethod': event['httpMethod']，
        'httpStatusCode': 200，
        'responseBody': response_body
    }
    
    api_response = {
        'messageVersion': '1.0'， 
        'response': action_response
    }
        
    return api_response

这段代码收集代理的请求， 处理请求， 然后制定一个响应返回给代理。返回的响应可以用来回答最终用户对代理的提问。

试一试

在 AWS 活动中

如果我们是通过 workshop studio 参加研讨会， 现在请转到 SageMaker Studio 中的 JupyterLab。

在 JupyterLab UI 中导航到 bedrock-agents-workshop/02-create-agent-with-api-schema/02-create-agent-with-api-schema.ipynb

自主学习

这里有一个笔记本， 让我们可以尝试上述内容: 使用 OpenAPI 架构创建代理 。