本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 教學課程：建置簡單的 Amazon Bedrock 代理程式 本教學課程將引導您使用 AWS 管理主控台建立和設定簡單的 Amazon Bedrock 代理程式。您將了解如何建立代理程式，透過調用 Lambda 函數來回應使用者有關目前日期和時間的查詢。 在此教學課程中，您將會： 1. 建立 Lambda 函數 — 建置 Python 函數，在代理程式調用時傳回目前的日期和時間。 1. 建立 Amazon Bedrock 代理程式 — 在 Amazon Bedrock 主控台中設定代理程式，並使用處理日期和時間查詢的指示進行設定。 1. 測試代理程式 — 使用內建測試介面，確認您的代理程式可以正確回應日期和時間請求。 1. 使用別名部署代理程式 — 建立代理程式的版本，並使用別名部署它以使其可供使用。 1. 從 Python 程式碼呼叫代理程式 — 了解如何使用 適用於 Python (Boto) 的 AWS SDK，以程式設計方式與您的代理程式互動。 1. 清除資源 — 移除在本教學課程中建立的 AWS 資源，以避免產生不必要的費用。 在本教學課程結束時，您將有一個運作中的 Amazon Bedrock 代理程式，可以了解日期和時間資訊的自然語言請求，並使用來自 Lambda 函數的準確資料來回應。 本教學課程是以 AWS 文件 [GitHub 儲存庫](https://github.com/awsdocs/aws-doc-sdk-examples/blob/main/python/example_code/bedrock-agent/scenario_get_started_with_agents.py)中的代理程式程式碼範例為基礎。 **Topics** + [必要條件](agent-tutorial-prereq.md) + [步驟 1：建立 Lambda 函數](agent-tutorial-step1.md) + [步驟 2：建立 Amazon Bedrock 代理程式](agent-tutorial-step2.md) + [步驟 3：測試代理程式](agent-tutorial-step3.md) + [步驟 4：使用別名部署代理程式](agent-tutorial-step4.md) + [步驟 5：從 Python 程式碼呼叫代理程式](agent-tutorial-step5.md) + [步驟 6：清除資源](agent-tutorial-step6.md) + [其他資源](agent-tutorial-resources.md) # 必要條件 開始本教學課程之前，請確定您已準備好下列項目： + 具有下列受管政策的 AWS 帳戶： + [AmazonBedrockFullAccess](https://docs.aws.amazon.com/bedrock/latest/userguide/security-iam-awsmanpol.html#security-iam-awsmanpol-AmazonBedrockFullAccess) + [AWSLambda\$1FullAccess](https://docs.aws.amazon.com/lambda/latest/dg/security-iam-awsmanpol.html#lambda-security-iam-awsmanpol-AWSLambda_FullAccess) + [IAMFullAccess](aws-managed-policy/latest/reference/IAMFullAccess.html) **重要** 這些許可允許您執行本教學課程以及其他不相關的任務。在生產環境中，請務必只指派使用者執行應用程式所需的許可。 + 對 IAM 角色和許可的基本了解 ([IAM 使用者指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html)) + 熟悉 AWS Lambda 函數 ([Lambda 開發人員指南](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html)) # 步驟 1：建立 Lambda 函數 首先，建立 Lambda 函數，您的代理程式將調用它來執行動作。在此程序中，您將建立 Python Lambda 函數，在調用時傳回目前的日期和時間。您將設定具有基本許可的函數、新增必要的程式碼來處理來自 Amazon Bedrock 代理程式的請求，以及部署函數，以便隨時連接到您的代理程式。 如需詳細資訊，請參閱《AWS Lambda 開發人員指南》**中的[建立您的第一個 Lambda 函數](https://docs.aws.amazon.com/lambda/latest/dg/getting-started.html)。 **建立 Lambda 函數** 1. 登入 AWS 管理主控台，並開啟位於 [https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 的 Lambda 主控台。 1. 選擇**建立函數** 。 1. 選取**從頭開始撰寫**。 1. 在 **Basic information (基本資訊)** 區段中： + 在**函數名稱**中，輸入函數名稱 (例如 `DateTimeFunction`)。請注意函數的名稱，您需要在[步驟 2：建立 Amazon Bedrock 代理程式](agent-tutorial-step2.md) 的步驟 15 中使用它。 + 針對**執行時期**，選取 **Python 3.9** (或您偏好的版本)。 + 對於**架構**，請保持不變。 + 在**許可**中，選取**變更預設執行角色**，然後選取**使用基本 Lambda 許可建立新角色**。 1. 選擇**建立函數** 。 1. 在**函數概觀**的**函數 ARN** 下，記下函數的 Amazon Resource Name (ARN)。您需要它才能執行[步驟 2：建立 Amazon Bedrock 代理程式](agent-tutorial-step2.md) 的步驟 24。 1. 在**程式碼**標籤中，將現有程式碼取代為以下程式碼： ``` # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. # SPDX-License-Identifier: Apache-2.0 import datetime import json def lambda_handler(event, context): now = datetime.datetime.now() response = {"date": now.strftime("%Y-%m-%d"), "time": now.strftime("%H:%M:%S")} response_body = {"application/json": {"body": json.dumps(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"] return { "messageVersion": "1.0", "response": action_response, "sessionAttributes": session_attributes, "promptSessionAttributes": prompt_session_attributes, } ``` 1. 選擇**部署**以部署您的函數。 1. 選擇 **Configuration** (組態) 索引標籤。 1. 選擇**許可**。 1. 在**資源型政策陳述式**底下，選擇**新增許可**。 1. 在**編輯政策陳述式**中，執行以下操作： 1. 選擇 **AWS 服務**。 1. 在**服務**中選取**其他**。 1. 針對**陳述式 ID**，輸入唯一識別符 (例如 `AllowBedrockInvocation`)。 1. 針對**主體**輸入 `bedrock.amazonaws.com`。 1. 針對**來源 ARN**，輸入 `arn:aws:bedrock:region:AWS account ID:agent/*`。 將 `region` 取代為您正在使用的 AWS 區域，例如 `us-east-1`。將 `AWS account ID` 取代為您的 AWS 帳戶 ID。 1. 針對**動作**，選取 `lambda:InvokeFunction`。 1. 選擇**儲存**。 # 步驟 2：建立 Amazon Bedrock 代理程式 接著，您將建立 Amazon Bedrock 代理程式。在此程序中，您將在 Amazon Bedrock 主控台中設定代理程式、使用基礎模型設定代理程式，並提供指示，將其行為定義為傳回日期和時間資訊的友善聊天機器人。您也將建立具有 OpenAPI 結構描述的動作群組，其定義代理程式可以呼叫的 API 端點，特別是取得目前日期和時間的端點。此外，您也將新增內嵌政策到代理程式的 IAM 角色，以允許它調用您的 Lambda 函數。代理程式將做為使用者和 Lambda 函數之間的介面，解譯自然語言請求並將其轉換為結構化函數呼叫，以擷取日期和時間資訊。 如需詳細資訊，請參閱[手動建立和設定代理程式](agents-create.md)。 **建立 Amazon Bedrock 代理程式** 1. AWS 管理主控台使用具有使用 Amazon Bedrock 主控台之許可的 IAM 身分登入 。接著，開啟位於 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock) 的 Amazon Bedrock 主控台。 1. 請確定您位於支援 Amazon Bedrock [代理程式](agents-supported.md)的 AWS[區域](https://docs.aws.amazon.com/awsconsolehelpdocs/latest/gsg/select-region.html)。 1. 在導覽窗格中的**建置器工具**下，選擇**代理程式**。 1. 選擇**建立代理程式**。 1. 針對**名稱**，輸入您代理程式的名稱 (例如 `MyBedrockAgent`)。 1. 在**描述**，請輸入描述。 1. 選擇**建立**。**代理程式建置器**窗格隨即開啟。 1. 在**代理程式詳細資訊**區段中： + 針對**代理程式資源角色**，選取**建立並使用新的服務角色**。 + 針對**選取模型**，選取一個模型，例如 Claude 3 Haiku。 + 在**代理程式的指示**區段中，輸入下列指示。 ``` You are a friendly chat bot. You have access to a function called that returns information about the current date and time. When responding with date or time, please make sure to add the timezone UTC. ``` 1. 選擇**儲存**。 1. 選擇**動作群組**索引標籤。 1. 在**動作群組**中，選擇**新增**。 1. 對於**輸入動作群組名稱**，輸入動作群組的名稱 (例如，`TimeActions`)。 1. (選用) 對於**描述**，輸入動作群組的描述。 1. 在**動作群組類型**中，選取**使用 API 結構描述定義**。 1. 在**動作群組調用**中，選擇**選取現有的 Lambda 函數**。 1. 在**選取 Lambda 函數**中，選取您在[步驟 1：建立 Lambda 函數](agent-tutorial-step1.md)中建立的 Lambda 函數名稱。 1. 在**動作群組結構描述**中，選取**透過內嵌結構描述編輯器定義**。 1. 在**內嵌 OpenAPI 結構描述**文字方塊中，將現有的結構描述取代為下列 OpenAPI YAML 結構描述： ``` openapi: 3.0.0 info: title: Time API version: 1.0.0 description: API to get the current date and time. paths: /get-current-date-and-time: get: summary: Gets the current date and time. description: Gets the current date and time. operationId: getDateAndTime responses: '200': description: Gets the current date and time. content: 'application/json': schema: type: object properties: date: type: string description: The current date time: type: string description: The current time ``` 1. 請檢閱您的動作群組組態，然後選擇**建立**。 1. 選擇**儲存**，以儲存變更。 1. 選擇**準備**以準備代理程式。 1. 選擇**儲存並結束**，以儲存變更並結束代理程式建置器。 1. 在**代理程式概觀**區段的**許可**下，選擇 IAM 服務角色。這會在 IAM 主控台中開啟該角色。 1. 在 IAM 主控台中，選擇**許可**索引標籤。 1. 選擇**新增許可**，然後選取**建立內嵌政策**。 1. 選擇 **JSON**，並將下列政策貼上。請確定 `Resource` 是 Lambda 函數的 Amazon Resource Name (ARN)。您在[步驟 1：建立 Lambda 函數](agent-tutorial-step1.md) 的步驟 6 中記下 ARN。 1. 選擇**下一步**。 1. 輸入政策的名稱 (例如 `BedrockAgentLambdaInvoke`)。 1. 選擇**建立政策**。 # 步驟 3：測試代理程式 在此程序中，您將使用 Amazon Bedrock 主控台中的內建測試介面來測試代理程式的工作草稿。您將傳送詢問目前日期和時間的自然語言查詢，並觀察代理程式如何處理這些請求、調用 Lambda 函數，以及傳回格式化的回應。此測試步驟可讓您驗證代理程式是否正確了解使用者意圖、正確呼叫 Lambda 函數，並以方便使用者的方式呈現資訊。 如需詳細資訊，請參閱 [測試代理程式行為並進行疑難排解](agents-test.md)。 **測試代理程式** 1. 在 Amazon Bedrock 主控台中，開啟您在[步驟 2：建立 Amazon Bedrock 代理程式](agent-tutorial-step2.md)中建立的代理程式 1. 選擇**測試**以開啟**測試**面板。 1. 在**別名**下拉式清單中，選取別名 **TestAlias：工作草稿**。 1. 在聊天介面中，輸入會觸發代理程式其中一個動作的提示，例如： + **What time is it?** + **Can you tell me today's date?** 1. 代理程式會處理您的提示、在必要時調用 Lambda 函數，並傳回回應。 1. (選用) 選擇**顯示追蹤**以查看您傳送至模型之提示的[追蹤](trace-events.md)步驟。在追蹤中，您應該會看到模型用來判斷何時呼叫 Lambda 函數以取得日期和時間的推理。 # 步驟 4：使用別名部署代理程式 設定代理程式之後，您需要使用別名來部署代理程式，以使其可供使用。在此程序中，您將建立代理程式的別名和版本，以準備您的代理程式進行部署。別名指向版本，可讓您透過穩定的端點調用代理程式，同時維持更新基礎實作的能力。 如需詳細資訊，請參閱 [在應用程式中部署和使用 Amazon Bedrock 代理程式](agents-deploy.md)。 **使用別名部署代理程式** 1. 在 Amazon Bedrock 主控台中，開啟您在[步驟 2：建立 Amazon Bedrock 代理程式](agent-tutorial-step2.md)中建立的代理程式 1. 選擇**建立別名**。 1. 對於**別名名稱**，輸入別名的名稱。例如 **DateTimeAliasAgentAlias**。 1. (選用) 在**描述**，請輸入描述。 1. 對於**與版本建立關聯**，請選取**建立新版本並將其與此別名建立關聯**。 1. 選擇**建立別名**。 1. 遵循[步驟 3：測試代理程式](agent-tutorial-step3.md)中的指示來測試別名。在步驟 6 中，選擇您剛剛建立的別名。 # 步驟 5：從 Python 程式碼呼叫代理程式 在此步驟中，您將了解如何使用 適用於 Python (Boto) 的 AWS SDK以程式設計方式與代理程式互動。此範例程式碼示範如何使用 [InvokeAgent](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_InvokeAgent.html) 操作，這需要 AGENT ID 和 ALIAS ID 作為參數才能呼叫您的代理程式。此程式碼說明如何傳送提示給您的代理程式、處理回應，以及處理串流和非串流回應模式。這可讓您將 Bedrock 代理程式整合到您自己的 Python 應用程式。 如需詳細資訊，請參閱[從您的應用程式調用代理程式](agents-invoke-agent.md)。 **從 Python 程式碼呼叫代理程式** 1. 取得代理程式的 ID。如需詳細資訊，請參閱[檢視代理程式的資訊](agents-view.md)。 1. 取得代理程式別名的 ID。如需詳細資訊，請參閱[檢視 Amazon Bedrock 中代理程式別名的相關資訊](agents-alias-view.md)。 1. 執行下列程式碼。更新下列項目： + **AGENT\$1ID** – 代理程式的 ID。 + **ALIAS\$1ID** – 代理程式的別名 ID。 + **REGION** – 您建立代理程式 AWS 的區域，例如 `us-east-1`。 若要從代理程式串流回應，請將 `streamFinalResponse` 的值變更為 `True`。 ``` import boto3 import logging from botocore.exceptions import ClientError logging.basicConfig(level=logging.INFO) logger = logging.getLogger(__name__) def invoke_agent(client, agent_id, alias_id, prompt, session_id): response = client.invoke_agent( agentId=agent_id, agentAliasId=alias_id, enableTrace=True, sessionId = session_id, inputText=prompt, streamingConfigurations = { "applyGuardrailInterval" : 20, "streamFinalResponse" : False } ) completion = "" for event in response.get("completion"): #Collect agent output. if 'chunk' in event: chunk = event["chunk"] completion += chunk["bytes"].decode() # Log trace output. if 'trace' in event: trace_event = event.get("trace") trace = trace_event['trace'] for key, value in trace.items(): logging.info("%s: %s",key,value) print(f"Agent response: {completion}") if __name__ == "__main__": client=boto3.client( service_name="bedrock-agent-runtime", region_name="REGION") agent_id = "AGENT_ID" alias_id = "ALIAS_ID" session_id = "123456" prompt = "What's the current time?" try: invoke_agent(client, agent_id, alias_id, prompt, session_id) except ClientError as e: print(f"Client error: {str(e)}") logger.error("Client error: %s", {str(e)}) ``` # 步驟 6：清除資源 使用 Amazon Bedrock 代理人完成後，您應該清除資源，以避免產生不必要的費用。在此最終程序中，您將有系統地刪除在本教學課程中建立的所有 AWS 資源，包括 Bedrock 代理程式、Lambda 函數和相關聯的 \$1IAM 角色。此清除程序對於成本管理很重要，因為它可防止您不再使用的資源持續產生費用。程序分為三個部分：刪除代理程式、移除 Lambda 函式，以及清除為支援這些服務而建立的 IAM 角色。 **Topics** + [刪除代理程式](#agent-tutorial-step6-console-agent) + [刪除 Lambda 函式](#agent-tutorial-step6-console-lambda) + [刪除 IAM 角色](#agent-tutorial-step6-console-iam) ## 刪除代理程式 **刪除代理程式** 1. 在 Amazon Bedrock 主控台中，開啟您在[步驟 2：建立 Amazon Bedrock 代理程式](agent-tutorial-step2.md)中建立的代理程式 1. 選取您建立的代理程式。 1. 選擇 **Delete** (刪除)。 1. 確認刪除。 ## 刪除 Lambda 函式 **刪除 Lambda 函式** 1. 在 https：//[https://console.aws.amazon.com/lambda/](https://console.aws.amazon.com/lambda/) 開啟 AWS Lambda 主控台。 1. 選取您建立的 Lambda 函式。 1. 依序選擇**動作**和**刪除**。 1. 確認刪除。 ## 刪除 IAM 角色 **刪除 IAM 角色** 1. 在以下網址開啟 IAM 主控台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。 1. 在導覽窗格中，選擇**角色**。 1. 選取您建立的代理程式服務角色。 1. 選擇 **Delete** (刪除)。 1. 確認刪除。 1. 針對 Lambda 執行角色重複此步驟。 # 其他資源 + [Amazon Bedrock 使用者指南](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html) + [Amazon Bedrock API 參考](https://docs.aws.amazon.com/bedrock/latest/APIReference/welcome.html) + [AWS Lambda 開發人員指南](https://docs.aws.amazon.com/lambda/latest/dg/welcome.html) + [IAM 使用者指南](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) + [Amazon Bedrock 代理程式文件](https://docs.aws.amazon.com/bedrock/latest/userguide/agents.html) + [OpenAPI 規格](https://swagger.io/specification/)