本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 設定 Lambda 函式以傳送 Amazon Bedrock 代理人從使用者取得的資訊
您可以定義 Lambda 函式來編寫動作群組的商業邏輯。Amazon Bedrock 代理人決定在動作群組中調用所需的 API 操作後，會將 API 結構描述中的資訊與相關中繼資料一起傳送至 Lambda 函式。若要撰寫函數，您必須了解 Lambda 函式的下列元件：
+ **輸入事件** – 包含來自 API 操作請求內文或代理程式判斷必須呼叫之動作的函數參數的相關中繼資料和填入欄位。
+ **回應** – 包含 API 操作或函數傳回之回應內文的相關中繼資料和已填入欄位。
您可以撰寫 Lambda 函式來定義如何處理動作群組，以及自訂傳回 API 回應的方式。您可以使用輸入事件中的變數來定義函數，並將回應傳回給代理。
**注意**
動作群組最多可包含 11 個 API 操作，但您只能撰寫一個 Lambda 函式。由於 Lambda 函式一次只能接收一個輸入事件並傳回一個 API 操作的回應，因此在編寫函數時，應考慮可能調用不同的 API 操作。
若要讓代理程式使用 Lambda 函式，您必須將資源型政策連接至函數，以提供代理程式的許可。如需更多資訊，請依照[資源型政策，允許 Amazon Bedrock 調用動作群組 Lambda 函數](agents-permissions.md#agents-permissions-lambda)中的步驟進行。如需 Lambda 中資源型政策的詳細資訊，請參閱《 AWS Lambda 開發人員指南》中的[為 Lambda 使用資源型政策](https://docs.aws.amazon.com/lambda/latest/dg/access-control-resource-based.html)。
若要了解如何在建立動作群組時定義函數，請參閱[在 Amazon Bedrock 中將動作群組新增至您的代理程式](agents-action-add.md)。
**Topics**
+ [來自 Amazon Bedrock 的 Lambda 輸入事件](#agents-lambda-input)
+ [Amazon Bedrock 的 Lambda 回應事件](#agents-lambda-response)
+ [動作群組 Lambda 函式範例](#agents-lambda-example)
## 來自 Amazon Bedrock 的 Lambda 輸入事件
調用使用 Lambda 函式的動作群組時，Amazon Bedrock 會傳送下列一般格式的 Lambda 輸入事件。您可以將 Lambda 函式定義為使用任何輸入事件欄位來操作函數內的商務邏輯，以順利執行動作。如需 Lambda 函數的詳細資訊，請參閱《 AWS Lambda 開發人員指南》中的[事件驅動叫用](https://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html#event-driven-invocation)。
輸入事件格式取決於您是否使用 API 結構描述或函數詳細資訊來定義動作群組：
+ 如果您使用 API 結構描述定義動作群組，則輸入事件格式如下：
```
{
"messageVersion": "1.0",
"agent": {
"name": "string",
"id": "string",
"alias": "string",
"version": "string"
},
"inputText": "string",
"sessionId": "string",
"actionGroup": "string",
"apiPath": "string",
"httpMethod": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"requestBody": {
"content": {
"": {
"properties": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
]
}
}
},
"sessionAttributes": {
"string": "string",
},
"promptSessionAttributes": {
"string": "string"
}
}
```
+ 如果您使用函數詳細資訊來定義動作群組，則輸入事件格式如下：
```
{
"messageVersion": "1.0",
"agent": {
"name": "string",
"id": "string",
"alias": "string",
"version": "string"
},
"inputText": "string",
"sessionId": "string",
"actionGroup": "string",
"function": "string",
"parameters": [
{
"name": "string",
"type": "string",
"value": "string"
},
...
],
"sessionAttributes": {
"string": "string",
},
"promptSessionAttributes": {
"string": "string"
}
}
```
下列清單說明輸入事件欄位；
+ `messageVersion` – 訊息版本，用於識別進入 Lambda 函式的事件資料的格式，以及來自 Lambda 函式的回應的預期格式。Amazon Bedrock 僅支援 1.0 版。
+ `agent`— 包含動作群組所屬代理程式的名稱、ID、別名和版本的相關資訊。
+ `inputText`— 用於對話回合的使用者輸入。
+ `sessionId` – 代理程式工作階段的唯一識別碼。
+ `actionGroup`— 動作群組的名稱。
+ `parameters`— 包含物件清單。每個物件都包含 API 操作 (如 OpenAPI 結構描述中所定義) 或函數中參數的名稱、類型和值。
+ 如果您使用 API 結構描述來定義動作群組，則輸入事件會包含下列欄位：
+ `apiPath` – API 操作的路徑，如 OpenAPI 結構描述中所定義。
+ `httpMethod` – API 操作的方法，如 OpenAPI 結構描述中所定義。
+ `requestBody` – 包含請求內文及其屬性，如動作群組的 OpenAPI 結構描述中所定義。
+ 如果您使用函數詳細資訊來定義動作群組，則輸入事件會包含下列欄位：
+ `function` – 函數的名稱，如動作群組的函數詳細資訊中所定義。
+ `sessionAttributes` – 包含[工作階段屬性](agents-session-state.md)及其值。這些屬性會在[工作階段](advanced-prompts.md#advanced-prompts-terminology)期間存放，並提供代理程式的內容。
+ `promptSessionAttributes` – 包含[提示工作階段屬性](agents-session-state.md)及其值。這些屬性會在一個[回合](advanced-prompts.md#advanced-prompts-terminology)內儲存，並提供代理程式的內容。
## Amazon Bedrock 的 Lambda 回應事件
Amazon Bedrock 預期 Lambda 函式符合以下列格式的回應。回應由 API 操作傳回的參數組成。代理可以使用 Lambda 函式的回應進行進一步協同運作，或協助將回應傳回給客戶。
**注意**
承載回應大小上限符合 Lambda 函式同步回應的大小上限。如需詳細資訊，請參閱《 AWS Lambda 開發人員指南》中的*調用承載*資源[配額](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html#function-configuration-deployment-and-execution)。
輸入事件格式取決於您是否使用 API 結構描述或函數詳細資訊來定義動作群組：
+ 如果您使用 API 結構描述來定義動作群組，回應格式如下：
```
{
"messageVersion": "1.0",
"response": {
"actionGroup": "string",
"apiPath": "string",
"httpMethod": "string",
"httpStatusCode": number,
"responseBody": {
"": {
"body": "JSON-formatted string"
}
}
},
"sessionAttributes": {
"string": "string",
...
},
"promptSessionAttributes": {
"string": "string",
...
},
"knowledgeBasesConfiguration": [
{
"knowledgeBaseId": "string",
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"numberOfResults": int,
"overrideSearchType": "HYBRID | SEMANTIC",
"filter": [RetrievalFilter](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html) object
}
}
},
...
]
}
```
+ 如果您使用函數詳細資訊來定義動作群組，則回應格式如下：
```
{
"messageVersion": "1.0",
"response": {
"actionGroup": "string",
"function": "string",
"functionResponse": {
"responseState": "FAILURE | REPROMPT",
"responseBody": {
"": {
"body": "JSON-formatted string"
}
}
}
},
"sessionAttributes": {
"string": "string",
},
"promptSessionAttributes": {
"string": "string"
},
"knowledgeBasesConfiguration": [
{
"knowledgeBaseId": "string",
"retrievalConfiguration": {
"vectorSearchConfiguration": {
"numberOfResults": int,
"filter": {
[RetrievalFilter](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrievalFilter.html) object
}
}
}
},
...
]
}
```
下列清單說明回應欄位：
+ `messageVersion` – 訊息版本，用於識別進入 Lambda 函式的事件資料的格式，以及來自 Lambda 函式的回應的預期格式。Amazon Bedrock 僅支援 1.0 版。
+ `response`— 包含 API 回應的下列資訊。
+ `actionGroup`— 動作群組的名稱。
+ 如果您使用 API 結構描述來定義動作群組，回應中可以有下列欄位：
+ `apiPath` – API 操作的路徑，如 OpenAPI 結構描述中所定義。
+ `httpMethod` – API 操作的方法，如 OpenAPI 結構描述中所定義。
+ `httpStatusCode` – 從 API 操作傳回的 HTTP 狀態碼。
+ `responseBody` – 包含回應內文，如 OpenAPI 結構描述中所定義。
+ 如果您使用函數詳細資訊來定義動作群組，則回應中可以有下列欄位：
+ `responseState` (選用) – 設定為下列其中一種狀態，以在處理動作後定義代理程式的行為：
+ 失敗 – 代理程式會擲回目前工作階段的 `DependencyFailedException`。當函數執行因相依性失敗而失敗時適用。
+ REPROMPT – 代理程式會將回應字串傳遞給模型以將其取代。當函數執行因輸入無效而失敗時適用。
+ `responseBody` – 包含定義函數執行之回應的物件。金鑰是內容類型 (目前僅支援 `TEXT`)，而值是包含回應 `body` 的物件。
+ (選用) `sessionAttributes` — 包含階段作業屬性及其值。如需詳細資訊，請參閱[工作階段和提示工作階段屬性](agents-session-state.md#session-state-attributes)。
+ (選用) `promptSessionAttributes` — 包含提示屬性及其值。如需詳細資訊，請參閱[工作階段和提示工作階段屬性](agents-session-state.md#session-state-attributes)。
+ (選用) `knowledgeBasesConfiguration` – 包含連接至代理程式之知識庫的查詢組態清單。如需詳細資訊，請參閱[知識庫擷取組態](agents-session-state.md#session-state-kb)。
## 動作群組 Lambda 函式範例
以下是如何在 中定義 Lambda 函數的最小範例Python。選取對應於您是否使用 OpenAPI 結構描述或函數詳細資訊定義動作群組的索引標籤：
------
#### [ OpenAPI schema ]
```
def lambda_handler(event, context):
agent = event['agent']
actionGroup = event['actionGroup']
api_path = event['apiPath']
# get parameters
get_parameters = event.get('parameters', [])
# post parameters
post_parameters = event['requestBody']['content']['application/json']['properties']
response_body = {
'application/json': {
'body': "sample response"
}
}
action_response = {
'actionGroup': event['actionGroup'],
'apiPath': event['apiPath'],
'httpMethod': event['httpMethod'],
'httpStatusCode': 200,
'responseBody': response_body
}
session_attributes = event['sessionAttributes']
prompt_session_attributes = event['promptSessionAttributes']
api_response = {
'messageVersion': '1.0',
'response': action_response,
'sessionAttributes': session_attributes,
'promptSessionAttributes': prompt_session_attributes
}
return api_response
```
------
#### [ Function details ]
```
def lambda_handler(event, context):
agent = event['agent']
actionGroup = event['actionGroup']
function = event['function']
parameters = event.get('parameters', [])
response_body = {
'TEXT': {
'body': "sample response"
}
}
function_response = {
'actionGroup': event['actionGroup'],
'function': event['function'],
'functionResponse': {
'responseBody': response_body
}
}
session_attributes = event['sessionAttributes']
prompt_session_attributes = event['promptSessionAttributes']
action_response = {
'messageVersion': '1.0',
'response': function_response,
'sessionAttributes': session_attributes,
'promptSessionAttributes': prompt_session_attributes
}
return action_response
```
------