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

# 在執行時期設定內嵌代理程式
<a name="agents-create-inline"></a>

您可以使用 [InvokeInlineAgent](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_InvokeInlineAgent.html) API，在執行時期動態設定和調用內嵌 Amazon Bedrock 代理程式。使用內嵌代理程式可讓您在調用代理程式的同時，靈活地指定代理程式功能，例如基礎模型、指示、動作群組、防護機制和知識庫。在使用代理程式之前，無需預先定義其功能。

以下是一些使用案例，其中使用內嵌代理程式可以為您提供在調用時設定代理程式的靈活性。
+ 透過使用不同的組態嘗試各種代理程式功能以及動態更新代理程式可用的工具，進行快速實驗，而無需建立單獨的代理程式。
+ 動態調用代理程式來執行特定任務，而無需建立新的代理程式版本或準備代理程式。
+ 透過在執行時期建立和調用代理程式，可執行簡單的查詢或使用程式碼解譯器執行簡單的任務。
+ 在[多代理協同作業](agents-multi-agent-collaboration.md)設定中建立多個代理程式，以共同處理任務或對話。

  若要使用多代理協同作業，您可以使用內嵌代理程式 API，以下列組合建立代理程式。  
**代理程式類型**    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/agents-create-inline.html)

**支援的模型和區域**

您可以使用 Amazon Bedrock 代理程式支援的任何基礎模型來設定內嵌代理程式，並可以在支援 Amazon Bedrock 代理程式的任何區域中調用內嵌代理程式。如需 Amazon Bedrock 代理程式支援之模型和區域的詳細資訊，請參閱下列內容：
+ [Amazon Bedrock 代理程式支援的區域](https://docs.aws.amazon.com//bedrock/latest/userguide/agents-supported.html)
+ [依功能的模型支援](https://docs.aws.amazon.com//bedrock/latest/userguide/models-features.html)

使用內嵌代理程式，您可以在模型之間切換。建議您在屬於相同系列的模型之間切換。在屬於不同系列的模型之間切換可能會導致行為不一致，並可能導致失敗。

Amazon Bedrock 主控台目前不支援設定和調用內嵌代理程式。

## 使用內嵌代理程式進階提示範本的準則
<a name="advanced-prompts-inline-guidelines"></a>
+ **基本提示範本** — 根據預設，Amazon Bedrock 將使用內嵌代理程式的預設基本提示範本，並且可以隨時在背景中變更提示。這可能會導致回應不一致。如果您想要對查詢做出一致的回應，請使用您自己的組態覆寫預設基本提示範本中的邏輯，以自訂內嵌代理程式的行為。如需詳細資訊，請參閱[進階提示範本](https://docs.aws.amazon.com//bedrock/latest/userguide/advanced-prompts-templates.html)。
+ **加密** – 使用 `customer managed key ` 加密工作階段的靜態/儲存詳細資訊。如果使用客戶自管金鑰啟動工作階段，則未來對相同工作階段提出的所有請求都需要該工作階段。針對相同工作階段使用不同的客戶自管金鑰將導致例外狀況。
+ **工作階段共用** — 轉送所有工作階段都是帳戶層級，而不是角色層級。您可以為 `agentName` 指定唯一值，在代理程式層級隔離工作階段。
+ **內嵌工作階段狀態** — `InlineSessionState` 中的屬性會透過工作階段持續存在。使用屬性為您的模型提供額外內容，並用於[少量樣本提示](https://docs.aws.amazon.com//bedrock/latest/userguide/what-is-a-prompt.html#few-shot-prompting-vs-zero-shot-prompting)。

# 先決條件
<a name="inline-agent-prereq"></a>

**注意**  
設定和調用內嵌代理程式功能是 Amazon Bedrock 的預覽版本，可能會有所變更。

在調用內嵌代理程式之前，請先完成下列必要條件：

1. 決定您要用於設定內嵌代理程式的基礎模型、您要調用代理程式的區域，以及指示內嵌代理程式應執行的動作。

1. 建立或準備要用於內嵌代理程式的下列一或多個 Amazon Bedrock 代理程式屬性。  
****    
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/bedrock/latest/userguide/inline-agent-prereq.html)

1. 建立 AWSIdentity and Access Management (IAM) 角色，並將此步驟中提及的政策連接至角色。

   您必須先建立 IAM 角色，以提供使用 `InvokeInlineAgent` API 和存取 Lambda 函數、知識庫和基礎模型等資源的必要許可，才能調用內嵌代理程式。

   遵循[建立角色以將許可委派給 IAM 使用者](https://docs.aws.amazon.com//bedrock/latest/userguide/getting-started.html)中的步驟，為您的內嵌代理程式建立自訂服務角色。建立 IAM 角色之後，請將下列政策連接至該角色。
**注意**  
基於安全考量，最佳實務是在建立 *\$1\$1region\$1*、*\$1\$1account-id\$1* 和 *\$1.ids* 之後，將其取代為區域、您的帳戶 ID 和特定資源 ID。

# 調用內嵌代理程式
<a name="inline-agent-invoke"></a>

**注意**  
設定和調用內嵌代理程式功能是 Amazon Bedrock 的預覽版本，可能會有所變更。

調用內嵌代理程式之前，請確定您已完成[必要條件](https://docs.aws.amazon.com//bedrock/latest/userguide/inline-agent-prereq.html)。

若要調用內嵌代理程式，請使用 [Amazon Bedrock 代理人執行時期端點](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt)傳送 [InvokeInlineAgent](https://docs.aws.amazon.com//bedrock/latest/APIReference/API_agent-runtime_InvokeInlineAgent.html) API 請求，並至少包含下列欄位。


****  

| 欄位 | 使用案例 | 
| --- | --- | 
| 指示 | 提供指示，告知內嵌代理程式應做什麼，以及應如何與使用者互動。 | 
| foundationModel | 指定要由您建立的內嵌代理程式用於協調的[基礎模型](https://docs.aws.amazon.com//bedrock/latest/userguide/foundation-models-reference.html)。例如，Anthropic Claude、meta Llama3.1 等。 | 
| sessionid | 工作階段的唯一識別碼。在請求之間使用相同的值，以繼續相同的對話。 | 

以下是選填欄位：


****  

| 欄位 | 使用案例 | 
| --- | --- | 
| actionGroups | 動作群組清單，其中每個動作群組定義內嵌代理程式可執行的動作。 | 
| knowledgeBases | 知識庫與內嵌代理程式的關聯，以增強模型產生的回應。 | 
| guardrailConfiguration | 用於封鎖主題、防止幻覺，以及為應用程式實作保護措施的防護機制組態。 | 
| agentCollaboration | 定義協作者代理程式如何處理跨多個協作者代理程式的資訊，以協調最終回應。協作者代理程式也可以是主管。 | 
| collaboratorConfigurations | 協作者代理程式的組態。 | 
| collaborators | 協作者代理程式的清單。 | 
| promptOverrideConfiguration | 用於覆寫預設提示的進階提示組態。 | 
| enableTrace | 指定是否開啟追蹤，以追蹤內嵌客服人員的推理程序。 | 
| idleSessionTTLInSeconds | 指定內嵌代理程式應結束工作階段並刪除任何預存資訊的持續時間。 | 
| customerEncryptionKeyArn | 指定 KMS 金鑰的 ARN 來加密代理程式資源， | 
| endSession | 指定是否要結束內嵌代理程式的工作階段。 | 
| inlineSessionState | 指定工作階段各種屬性的參數。 | 
| inputText | 指定要傳送給代理程式的提示文字。 | 
| reasoning\$1config | 啟用模型推理，讓模型解釋如何得出結論。在 additionalModelRequestFields 欄位內使用。您必須指定用於模型推理的 budget\$1tokens 數目，這是輸出字符的子集。如需詳細資訊，請參閱[使用模型推理增強模型回應](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-reasoning.html)。 | 

下列 `InvokeInlineAgent` API 範例提供完整的內嵌代理程式組態，包括基礎模型、指示、具有程式碼解譯器的動作群組、防護機制和知識庫。

```
response = bedrock_agent_runtime.invoke_inline_agent(
    // Initialization parameters: cannot be changed for a conversation
    sessionId='uniqueSessionId',
    customerEncryptionKeyArn: String,
    
    // Input
    inputText="Hello, can you help me with a task?",
    endSession=False,
    enableTrace=True,
    
    // Agent configurations
    foundationModel='anthropic.claude-3-7-sonnet-20250219-v1:0',
    instruction="You are a helpful assistant...",
    actionGroups=[
        {
            'name': 'CodeInterpreterAction',
            'parentActionGroupSignature': 'AMAZON.CodeInterpreter'
        },
        {
            'actionGroupName': 'FetchDetails',
            'parentActionGroupSignature': '',
            "actionGroupExecutor": { ... },
            "apiSchema": { ... },
            "description": "string",
            "functionSchema": { ... }
        }
    ],
    knowledgeBases=[
        {
            knowledgeBaseId: "string",
            description: 'Use this KB to get all the info',
            retrievalConfiguration: { 
                vectorSearchConfiguration: { 
                    filter: { ... },
                    numberOfResults: number,
                    overrideSearchType: "string"
               }
            }
        }
    ],
    guardrailConfiguration={
        guardrailIdentifier: 'BlockEverything',
        gurardrailVersion: '1.0'
    },
    promptOverrideConfiguration: {...}
    
    // session properties: persisted throughout conversation
    inlineSessionState = {
        sessionAttributes = { 'key': 'value' },
        promptSessionAttributes = {k:v},
        returnControlInvocationResults = {...},
        invocationId = 'abc',
        files = {...},
    }
  }
```

您可以在請求中包含模型推理參數。以下是在 `additionalModelRequestFields` 中開啟模型推理的單一提示範例。

```
{
    "basePromptTemplate": " ... ",
    "inferenceConfiguration": {
        "stopSequences": [
            "</answer>"
        ]
    },
    "parserMode": "DEFAULT",
    "promptCreationMode": "DEFAULT",
    "promptState": "DISABLED",
    "promptType": "ORCHESTRATION",
    "additionalModelRequestFields":
    "reasoning_config": {
        "type": "enabled",
        "budget_tokens": 1024
    }
}
```