本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# 手動建立和設定代理程式
<a name="agents-create"></a>

若要使用 Amazon Bedrock 建立代理程式，您需設定下列元件：
+ 代理程式的組態，定義了代理程式的用途，並指示用來產生提示和回應的基礎模型 (FM)。
+ 至少下列其中一個項目：
  + 動作群組，定義代理程式要執行哪些動作。
  + 資料來源的知識庫，透過允許搜尋和查詢來增強代理程式的生成能力。

您可以建立一個僅包含名稱的代理程式。若要**準備**代理程式以便[測試](agents-test.md)或[部署](agents-deploy.md)代理程式，您必須至少設定下列元件：


****  

| 組態 | 說明 | 
| --- | --- | 
| 代理程式資源角色 | [具有在代理程式上呼叫 API 操作之許可的服務角色](agents-permissions.md)的 ARN | 
| 基礎模型 (FM) | 代理程式要調用以執行協同運作的 FM | 
| 指示 | 描述代理程式應該做什麼以及如何與使用者互動的自然語言 | 

您也應該為代理程式設定至少一個動作群組或知識庫。如果您準備的代理程式沒有動作群組或知識庫，那麼它只會根據 FM 和指示和[基本提示範本](advanced-prompts.md)傳回回應。

若要了解如何建立代理程式，請選擇您偏好方法的索引標籤，然後遵循下列步驟：

------
#### [ Console ]

**建立代理程式**

1. 使用具有 Amazon Bedrock 主控台使用許可的 IAM 身分登入AWS 管理主控台。接著，開啟位於 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock) 的 Amazon Bedrock 主控台。

1. 從左側導覽窗格選取**代理程式**。

1. 在**代理程式**區段中選擇**建立代理程式**。

1. (選用) 變更自動產生的代理程式**名稱**，並提供選用的**描述**。

1. 選擇**建立**。您的代理程式已建立，系統會將您導向至新建立代理程式的**代理程式建置器**，您可以在其中設定代理程式。

1. 您可以繼續執行下列程序來設定您的代理程式，或稍後再返回代理程式建置器。

**設定您的代理程式**

1. 如果您尚未進入代理程式建置器，請執行下列動作：

   1. 使用具有 Amazon Bedrock 主控台使用許可的 IAM 身分登入AWS 管理主控台。接著，開啟位於 [https://console.aws.amazon.com/bedrock](https://console.aws.amazon.com/bedrock) 的 Amazon Bedrock 主控台。

   1. 從左側導覽窗格選取**代理程式**。接著，在**代理程式**區段中選擇代理程式。

   1. 選擇**在代理程式建置器中編輯**。

1. 在**代理程式詳細資訊**區段中，您可以設定下列組態：

   1. 編輯**代理程式名稱**或**代理程式描述**。

   1. 針對**代理程式資源角色**，選取下列其中一個選項：
      + **建立並使用新的服務角色** – 讓 Amazon Bedrock 代表您建立服務角色並設定必要的許可。
      + **使用現有的服務角色** – 使用您先前設定的[自訂角色](agents-permissions.md)。

   1. 針對**選取模型**，選取一個 FM，供代理程式在協同運作期間調用。

      根據預設，會顯示針對代理程式最佳化的模型。若要查看 Amazon Bedrock 代理程式支援的所有模型，請清除 **Bedrock 代理程式已最佳化**。  
![\[您可以使用任何基礎模型建立代理程式。目前，供應的部分模型已經過最佳化，其提示/剖析器經過微調，可與代理程式架構整合。隨著時間的經過，我們打算為所有提供的模型提供最佳化。\]](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/images/agents/agents-optimized-model-selection.png)

   1. 在**代理程式的指示**中，輸入詳細資訊以告知代理程式應該執行什麼動作，以及應該如何與使用者互動。指示會取代[協同運作提示範本](prompt-placeholders.md#placeholders-orchestration)中的 \$1instructions\$1 預留位置。以下是指示的範例：

      ```
      You are an office assistant in an insurance agency. You are friendly and polite. You help with managing insurance claims and coordinating pending paperwork.
      ```

   1. 如果您展開**其他設定**，您可以修改下列組態：
      + **程式碼解譯器** – (選用) 選擇是否讓代理程式處理涉及編寫、執行、測試和疑難排解程式碼的任務。如需詳細資訊，請參閱 [使用程式碼解譯來產生、執行和測試程式碼](agents-code-interpretation.md)。
      + **使用者輸入** – (選用) 選擇是否允許代理程式在資訊不足時向使用者請求更多資訊。如需詳細資訊，請參閱 [設定代理程式向使用者請求資訊](agents-user-input.md)。
      + **KMS 金鑰選取** – (選用) 預設情況下，AWS 會使用 AWS 受管金鑰來加密代理程式資源。若要使用您自己的客戶自管金鑰來加密代理程式，請在 KMS 金鑰選取區段中選取**自訂加密設定 (進階)**。若要建立新的金鑰，請選取**建立 AWS KMS 金鑰**，並重新整理此視窗。若要使用現有金鑰，請在**選擇 AWS KMS 金鑰**中選取一個金鑰。
      + **閒置工作階段逾時** – 根據預設，如果使用者在 Amazon Bedrock 代理程式的工作階段中 30 分鐘無回應，則代理程式不再保留對話歷史記錄。對話歷程記錄可用來恢復互動，也可以使用對話中的內容來擴增回應。若要變更此預設時間長度，請在**工作階段逾時**欄位中輸入數字，然後選擇時間單位。

   1. 針對 **IAM 許可**區段的**代理程式資源角色**，選擇[服務角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html#iam-term-service-role)。若要讓 Amazon Bedrock 代表您建立服務角色，請選擇**建立並使用新的服務角色**。若要使用您之前建立的[自訂角色](agents-permissions.md)，請選擇**使用現有服務角色**。
**注意**  
Amazon Bedrock 為您建立的服務角色不包含預覽功能的許可。若要使用這些功能，請[將正確的許可連接至服務角色](agents-permissions.md)。

   1. (選用) 根據預設，AWS 會使用 AWS 受管金鑰來加密代理程式資源。若要使用您自己的客戶自管金鑰來加密代理程式，請在 **KMS 金鑰選取**區段中選取**自訂加密設定 (進階)**。若要建立新的金鑰，請選取**建立 AWS KMS 金鑰**，並重新整理此視窗。若要使用現有金鑰，請在**選擇 AWS KMS 金鑰**中選取一個金鑰。

   1. (選用) 若要將標籤與此代理程式建立關聯，請在**標籤 – 選用**區段中，選擇**新增標籤**並提供鍵/值對。

   1. 完成代理程式組態設定後，選取**下一步**。

1. 在**動作群組**區段中，您可以選擇**新增**，將動作群組新增至您的代理程式。如需設定動作群組的詳細資訊，請參閱[使用動作群組來定義代理程式要執行的動作](agents-action-create.md)。若要了解如何將動作群組新增至您的代理程式，請參閱[在 Amazon Bedrock 中將動作群組新增至您的代理程式](agents-action-add.md)。

1. 在**知識庫**區段中，您可以選擇**新增**以將知識群組與您的代理程式建立關聯。如需設定知識庫的詳細資訊，請參閱[使用 Amazon Bedrock 知識庫擷取資料並產生 AI 回應](knowledge-base.md)。若要了解如何將知識庫與您的代理程式建立關聯，請參閱[使用知識庫為您的代理程式產生增強回應](agents-kb-add.md)。

1. 在**防護機制詳細資訊**區段中，您可以選擇**編輯**，將防護機制與您的代理程式建立關聯，以封鎖和篩選有害內容。從**選取防護機制**下的下拉式選單中選取您要使用的防護機制，然後在**防護機制版本**下選擇要使用的版本。您可以選取**檢視**來查看您的防護機制設定。如需詳細資訊，請參閱 [使用 Amazon Bedrock 防護機制偵測和篩選有害內容](guardrails.md)。

1. 在**協同運作策略**區段中，您可以選擇**編輯**來自訂代理程式的協同運作。如需可用於代理程式之協同運作策略的詳細資訊，請參閱[自訂代理程式協同運作策略](orch-strategy.md)。

1. 在**多代理協同作業**區段中，您可以選擇**編輯**來建立多代理協同作業團隊。如需多代理協同作業的詳細資訊，請參閱[搭配 Amazon Bedrock 代理人使用多代理協同作業](agents-multi-agent-collaboration.md)。

1. 當您完成設定代理程式時，請選取下列其中一個選項：
   + 若要留在**代理程式建置器**中，請選擇**儲存**。然後，您可以**準備**代理程式，以便在測試視窗中使用更新後的組態進行測試。若要了解如何測試您的代理程式，請參閱[測試代理程式行為並進行疑難排解](agents-test.md)。
   + 若要返回**代理程式詳細資訊**頁面，請選擇**儲存並結束**。

------
#### [ API ]

若要建立代理程式，請使用 [Amazon Bedrock 代理程式建置時期端點](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-bt)傳送 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_CreateAgent.html) 請求 (請參閱連結以了解請求和回應格式及欄位詳細資訊)。

[查看程式碼範例](bedrock-agent_example_bedrock-agent_CreateAgent_section.md)

若要準備您的代理程式以便進行[測試](agents-test.md)或[部署](agents-deploy.md)，您必須至少包含下列欄位 (您也可以先略過這些組態，稍後再傳送 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_UpdateAgent.html) 請求來進行設定)：


****  

| 欄位 | 使用案例 | 
| --- | --- | 
| agentResourceRoleArn | 指定具有許可的服務角色 ARN，以呼叫代理程式上的 API 操作 | 
| foundationModel | 為代理程式指定基礎模型 (FM) 以與以下項目協調 | 
| 指示 | 提供指示來告知代理程式該怎麼做。用於協同運作提示範本的 \$1instructions\$1 預留位置。 | 

以下是選填欄位：


****  

| 欄位 | 使用案例 | 
| --- | --- | 
| 描述 | 描述代理程式執行的操作 | 
| idleSessionTTLInSeconds | 持續時間，代理程式在此時間後會結束工作階段與刪除任何預存資訊。 | 
| customerEncryptionKeyArn | 用於加密代理程式資源的 KMS 金鑰 ARN | 
| tags | 將[標籤](tagging.md)與代理程式建立關聯。 | 
| promptOverrideConfiguration | 在協同運作的每個步驟[自訂傳送至 FM 的提示](advanced-prompts.md)。 | 
| guardrailConfiguration | 將[防護機制](guardrails.md)新增至代理程式。指定防護機制的 ID 或 ARN，以及要使用的版本。 | 
| clientToken | 為確保 API 請求，僅完成一次。如需詳細資訊，請參閱[確保冪等性](https://docs.aws.amazon.com/ec2/latest/devguide/ec2-api-idempotency.html)。 | 
| cachingState | 啟用代理程式輸入的提示快取。如需詳細資訊，請參閱 [提示快取可加快模型推論速度](prompt-caching.md)。 | 
| reasoning\$1config | 啟用模型推理，讓模型解釋如何得出結論。在 additionalModelRequestFields 欄位內使用。您必須指定用於模型推理的 budget\$1tokens 數目，這是輸出字符的子集。如需詳細資訊，請參閱[使用模型推理增強模型回應](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html)。 | 

回應會傳回 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) 物件，其中包含新建立代理程式的詳細資訊。如果無法建立代理程式，回應中的 [https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) 物件會傳回 `failureReasons` 的清單和 `recommendedActions` 的清單，供您進行疑難排解。

```
    def create_agent(self, agent_name, foundation_model, role_arn, instruction):
        """
        Creates an agent that orchestrates interactions between foundation models,
        data sources, software applications, user conversations, and APIs to carry
        out tasks to help customers.

        :param agent_name: A name for the agent.
        :param foundation_model: The foundation model to be used for orchestration by the agent.
        :param role_arn: The ARN of the IAM role with permissions needed by the agent.
        :param instruction: Instructions that tell the agent what it should do and how it should
                            interact with users.
        :return: The response from Amazon Bedrock Agents if successful, otherwise raises an exception.
        """
        try:
            response = self.client.create_agent(
                agentName=agent_name,
                foundationModel=foundation_model,
                agentResourceRoleArn=role_arn,
                instruction=instruction,
            )
        except ClientError as e:
            logger.error(f"Error: Couldn't create agent. Here's why: {e}")
            raise
        else:
            return response["agent"]
```

如需詳細資訊，請參閱 [Hello Amazon Bedrock 代理人](bedrock-agent_example_bedrock-agent_Hello_section.md)。

------