View a markdown version of this page

搭配 AWS Organizations 使用 AWS 代理程式登錄檔 - Amazon Bedrock AgentCore
自動偵測如何與 AWS Organizations 搭配使用先決條件許可啟用整個組織的自動偵測使用自動偵測的記錄關閉自動偵測疑難排解

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

搭配 AWS Organizations 使用 AWS 代理程式登錄檔

AWS 代理程式登錄檔與 AWS Organizations 整合，讓您可以在單一登錄檔中自動為組織成員帳戶間支援的資源編製目錄。

當您為登錄檔啟用自動偵測時，組織中的成員帳戶中支援的 資源 — AgentCore 執行期和閘道 — 會自動分類為登錄檔記錄，成員帳戶中不需要設定。為整個組織自動偵測設定的登錄檔稱為組織範圍登錄檔；當資源建立、更新或刪除，以及帳戶加入或離開組織時，它會保持同步。

此頁面說明自動偵測如何與 AWS Organizations 搭配使用、如何啟用它，以及如何管理它產生的記錄。

注意

自動偵測會從其探索的資源填入登錄檔。您仍然可以在相同的登錄檔中手動建立和管理記錄。由自動偵測建立的記錄會加上標記，因此您可以將它們與您自行新增的記錄分開。

自動偵測如何與 AWS Organizations 搭配使用

帳戶

兩個帳戶參與自動偵測：

  • 管理帳戶 – AWS 組織的管理帳戶可啟用受信任存取以進行自動偵測，並註冊委派的管理員。這些是只有管理帳戶才能執行的 AWS Organizations 操作。

  • 登錄管理員 – 擁有組織範圍登錄檔及其自動偵測記錄的帳戶。我們建議您使用委派管理員帳戶，並遵循最低權限 AWS 的安全最佳實務。管理帳戶也可以擁有登錄檔，但不建議這麼做。

注意

每個區域只能有一個作用中的組織範圍登錄。在管理帳戶或委派管理員中建立它 — 如果組織中已存在該區域，則會拒絕建立另一個。

自動偵測發現什麼

為組織範圍的登錄檔啟用自動偵測時，它會從您的成員帳戶探索下列資源類型：

  • Amazon Bedrock AgentCore 執行期 (AWS::BedrockAgentCore::Runtime)

  • Amazon Bedrock AgentCore Gateways (AWS::BedrockAgentCore::Gateway)

當您啟用之後建立的功能和資源時，自動偵測會探索已存在的資源。

偵測到的資源如何成為記錄

對於每個探索到的資源， AWS 代理登錄檔會在管理員的登錄檔中建立登錄檔記錄。每個自動偵測的記錄都包含一個來源項目，該項目會將其連結到來源資源，其中包含來源資源的 ARN (sourceId)、類型 (sourceType) 和關係 DETECTED_FROM。您可以使用原始伺服器，將任何記錄追蹤回來源於資源 - 和成員帳戶。

自動偵測是完全受管的。啟用之後，就不需要在個別成員帳戶中安裝或設定 - 沒有客服人員、每個帳戶沒有許可，也不需要設定成員帳戶資源。

資源欄位如何映射至記錄欄位

下表顯示自動偵測如何將屬性從來源資源映射到登錄檔記錄欄位。

AgentCore 執行期 → 登錄檔記錄

來源 （執行期屬性） 記錄欄位 備註

帳戶 ID、區域、資源 ID

name

自動產生為 aws-autodetected-<accountId>-<region>-<resourceId> 。不是執行時間的顯示名稱 (AgentRuntimeName)。

ProtocolConfiguration.ServerProtocol

recordType

一律為 AGENT。每個執行時間通訊協定 (MCP、HTTPA2A、、AGUI) 都會對應至 AGENT，因為自動偵測無法區分獨立 MCP 伺服器與公開 MCP 介面的代理程式。您可以將執行時間偵測到的記錄從 縮小AGENT到MCP您自己 – 請參閱 充實自動偵測的記錄。

ProtocolConfiguration.ServerProtocol

描述項類型 （在 內descriptors)

MCP → mcpServer； HTTP → http； A2A → a2aAgentCard； AGUI → agui。 http 如果不存在或無法辨識，則預設為 。

AgentRuntimeVersion

recordVersion

在第一次偵測時從執行階段版本設定 ，然後視為您擁有的值 - 稍後對執行階段版本的變更不會變更它 （請參閱 充實自動偵測的記錄)。"1" 如果不存在，則預設為 。

從執行時間 ARN 和區域建構

端點 URL （在 內descriptors)

格式：https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations?qualifier=DEFAULT

執行時間 ARN

provenance[].sourceId

來源執行時間的完整 ARN。

AWS::BedrockAgentCore::Runtime

provenance[].sourceType

所有執行時間記錄的常數。

ProtocolConfiguration.ServerProtocol

provenance[].sourceDetails.agentcoreRuntime.protocolConfiguration.serverProtocol

原始線路值 （例如，、MCPHTTP、A2A)。

AuthorizerConfiguration.CustomJWTAuthorizer.DiscoveryUrl

provenance[].sourceDetails.agentcoreRuntime.authorizerConfiguration.customJWTAuthorizer.discoveryUrl

僅適用於具有 JWT 授權的執行時間。其他授權方欄位 (AllowedClients、AllowedAudience、AllowedScopes) 不會帶入記錄中。

WorkloadIdentityDetails.WorkloadIdentityArn

provenance[].sourceDetails.agentcoreRuntime.workloadIdentityDetails.workloadIdentityArn

當執行時間已設定工作負載身分時出現。

AgentCore Gateway → 登錄檔記錄

來源 （閘道屬性） 記錄欄位 備註

帳戶 ID、區域、資源 ID

name

自動產生為 aws-autodetected-<accountId>-<region>-<resourceId> 。不是閘道的顯示名稱 (Name)。

ProtocolType

recordType

MCP → GATEWAY。 閘道偵測到的記錄一律為 GATEWAY，且無法變更為其他類型。目前不支援其他通訊協定類型。

ProtocolType

描述項類型 （在 內descriptors)

MCP → mcpServer。 目前不支援其他通訊協定類型。

（硬式編碼）

recordVersion

一律為 "1"。閘道沒有版本概念；已備妥更新。

GatewayUrl

端點 URL （在 內descriptors)

從閘道組態逐字取得 （例如，\https://<gateway-id>.gateway.bedrock-agentcore.<region>.amazonaws.com/mcp)。

閘道 ARN

provenance[].sourceId

來源閘道的完整 ARN。

AWS::BedrockAgentCore::Gateway

provenance[].sourceType

所有閘道記錄的常數。

ProtocolType

provenance[].sourceDetails.agentcoreGateway.protocolType

原始線路值 （例如 MCP)。

AuthorizerType

provenance[].sourceDetails.agentcoreGateway.authorizerType

例如 AWS_IAM 或 CUSTOM_JWT。

AuthorizerConfiguration.CustomJWTAuthorizer.DiscoveryUrl

provenance[].sourceDetails.agentcoreGateway.authorizerConfiguration.customJWTAuthorizer.discoveryUrl

僅適用於具有 JWT 授權的閘道。其他授權方欄位 (AllowedClients、AllowedAudience、AllowedScopes) 不會帶入記錄中。

WorkloadIdentityDetails.WorkloadIdentityArn

provenance[].sourceDetails.agentcoreGateway.workloadIdentityDetails.workloadIdentityArn

當閘道已設定工作負載身分時出現。

目錄如何保持同步

自動偵測作用中後， AWS 代理登錄檔會讓登錄檔與您組織的狀態保持一致：

成員帳戶中的事件 對登錄檔的影響

當您啟用自動偵測時，支援的資源已存在

會為其建立記錄。

已建立支援的資源

會為其建立記錄。

支援的資源已更新

當來源衍生屬性變更 （例如資源的通訊協定、授權方或端點） 時，記錄的來源衍生欄位 - 其描述項和來源 - 會重新整理，而您自行設定的值 （例如 name、 description和 recordVersion) 則會保留。如果通訊協定變更，描述項會調整為新的通訊協定，並recordType重設為來源預設值 (AGENT 代表執行時間）。如果您已經核准記錄，則重新整理會套用為必須核准的新Draft修訂，而您先前核准的修訂仍然可以探索 – 請參閱 核准。

已刪除支援的資源

其記錄已移除。

帳戶加入組織

偵測到並新增其支援的資源。

帳戶離開 （或從中移除） 組織

從該帳戶偵測到的所有記錄都會移除。
注意

如果您棄用自動偵測的記錄 （將其狀態設定為 DEPRECATED)，自動偵測會停止將變更從來源資源同步至該記錄。來源資源的後續更新，例如通訊協定、授權方或端點變更，不會套用至已棄用的記錄。當您想要凍結特定自動偵測的記錄，同時在登錄檔中其他自動偵測的記錄持續進行重新同步時，請使用棄用。

自動偵測設定與其狀態

自動偵測包含兩個相關欄位：一個由您設定，另一個由服務報告：

  • autoDetectionConfiguration.enabled 是您控制的設定。您在建立或更新登錄檔時設定它，以請求自動偵測開啟 (true) 或關閉 (false)。 AWS 代理登錄檔也會在幾個遞減情況下為您關閉它：當自動偵測的受信任存取停用時，或當擁有登錄檔的委派管理員取消註冊時。

  • autoDetection.status 是服務報告 – ACTIVE或 的狀態INACTIVE。您未設定它。 AWS 代理登錄檔ACTIVE只會在 enabled 為 true且組織符合自動偵測先決條件時進行，否則為 INACTIVE。

簡言之， enabled 是您的請求， autoDetection.status 是實際生效的。enabled 將 設定為 true是必要的，但不足以autoDetection.status讓 成為 ACTIVE。

先決條件

啟用自動偵測之前，請確定您有下列項目：

  • 您的帳戶是 AWS Organizations 中組織的成員，已啟用所有功能。如需詳細資訊，請參閱 AWS 《 Organizations 使用者指南》中的啟用組織中的所有功能。

  • 您可以登入 管理帳戶，以啟用受信任存取並註冊委派的管理員。

  • 您可以登入將成為登錄管理員的帳戶 — 建議委派管理員 — 以建立組織範圍的登錄。

  • 您擁有這些帳戶中 許可中所述的許可。

許可

在管理帳戶中

若要啟用受信任存取並註冊委派管理員，管理帳戶中的發起人需要這些 AWS Organizations 許可：

  • organizations:EnableAWSServiceAccess

  • organizations:RegisterDelegatedAdministrator

  • organizations:DeregisterDelegatedAdministrator 和 organizations:DisableAWSServiceAccess 稍後關閉此功能

管理帳戶也需要iam:CreateServiceLinkedRole建立 AWS Agent Registry 服務連結角色。此角色必須存在於管理帳戶中，才能建立組織範圍的登錄檔 — 請參閱「在整個組織中啟用自動偵測」中的步驟 1。

在登錄管理員帳戶中

若要建立和管理組織範圍的登錄檔及其記錄，發起人需要 AWS 客服人員登錄檔許可，包括 agent-registry:CreateRegistry、agent-registry:UpdateRegistry、agent-registry:GetRegistry、 agent-registry:ListRegistryRecords和 agent-registry:UpdateRegistryRecord。如需完整清單和範例政策，請參閱 IAM 許可。

啟用整個組織的自動偵測

啟用自動偵測是一個三步驟的程序：管理帳戶啟用受信任的存取並註冊委派的管理員，然後管理員建立開啟自動偵測的組織範圍登錄。

注意

本節中的步驟必須依序執行。註冊委派管理員 （步驟 2) 之後，組織狀態可能需要一小段時間才能傳播。在此之前，建立組織範圍的登錄檔 （步驟 3) 會遭到拒絕。請參閱 疑難排解。

步驟 1：啟用受信任的存取並建立服務連結角色 （管理帳戶）

登入 管理帳戶，啟用受信任存取以進行自動偵測，並確認管理帳戶具有 AWS Agent Registry 服務連結角色。

重要

AWS 代理程式登錄檔服務連結角色 (AWSServiceRoleForAgentRegistry) 必須存在於管理帳戶中，才能建立組織範圍的登錄檔，包括何時由委派管理員而非管理帳戶建立登錄檔。從 AWS Agent Registry 主控台啟用受信任存取會為您建立此角色。如果您使用 AWS CLI 或 API 設定 ，請使用以下第二個命令明確建立它。

如果使用客戶受管金鑰加密組織範圍的登錄檔，則CreateRegistry呼叫 之前，服務連結角色也必須存在於登錄檔管理員帳戶 （通常是委派管理員） 中。該帳戶中的 KMS 金鑰政策會將服務連結角色命名為委託人，而 IAM 會拒絕參考尚未存在之委託人的任何金鑰政策。啟用受信任存取會透過 ASLRP 佈建登錄管理員帳戶中的角色，但傳播可能會短暫延遲，直到角色到達該處為止，針對 KMS 金鑰政策CreateRegistry失敗。若要避免此競賽，請讓登錄管理員帳戶直接使用 建立角色aws iam create-service-linked-role --aws-service-name agent-registry.amazonaws.com。

不使用客戶受管金鑰的組織範圍登錄檔不需要此額外步驟 — 如果尚未在登錄檔管理員帳戶中CreateRegistry建立服務連結角色。

主控台

  1. 開啟AWS 客服人員登錄檔主控台 — 設定。

  2. 在 AWS 組織整合詳細資訊區段中，選擇編輯。

  3. 在 AWS 組織設定頁面的信任存取下，開啟已啟用切換。這會授權 AWS 客服人員登錄檔跨成員帳戶探索資源，並在此帳戶中建立AWSServiceRoleForAgentRegistry服務連結角色。

  4. 在委派管理員帳戶下，輸入您要用作登錄管理員之成員帳戶的 12 位數帳戶 ID。

  5. 選擇儲存。

AWS CLI

啟用受信任存取以進行自動偵測：

aws organizations enable-aws-service-access \
  --service-principal agent-registry.amazonaws.com

在管理帳戶中建立 AWS 客服人員登錄檔服務連結角色：

aws iam create-service-linked-role \
  --aws-service-name agent-registry.amazonaws.com

步驟 2：註冊委派管理員 （管理帳戶）

仍然在管理帳戶中，將擁有組織範圍登錄的帳戶註冊為委派管理員以進行自動偵測。

注意

您註冊的帳戶必須已經是組織的成員。如果不是，請在 AWS Organizations 中新增它，再執行此步驟。

主控台

委派管理員已註冊為上述步驟 1 的一部分。當您在 AWS 組織設定頁面上設定受信任存取並輸入委派管理員帳戶 ID 時，這兩個步驟會一起完成。

AWS CLI

<delegated-admin-account-id> 將 取代為您要做為登錄管理員之帳戶的 12 位數帳戶 ID。

aws organizations register-delegated-administrator \
  --account-id <delegated-admin-account-id> \
  --service-principal agent-registry.amazonaws.com

步驟 3：建立組織範圍的登錄檔 （登錄檔管理員）

登入委派的管理員帳戶，並使用設定為 ORGANIZATION和 scope 的自動偵測組態建立登錄enabledtrue檔。 enabled必須是true自動偵測才能啟用 - 如果是 false，則會建立登錄檔，但其自動偵測狀態永遠不會變成 ACTIVE ，也不會偵測到任何資源。

主控台

  1. 開啟 AWS 代理程式登錄檔主控台 — 登錄檔。

  2. 選擇建立登錄檔。

  3. 完成必要欄位 (名稱，以及選擇性的描述、探索授權、記錄核准、KMS 金鑰和標籤)。

  4. 展開自動偵測區段。

  5. 開啟啟用自動偵測切換。範圍設定為 Organization，並顯示服務存取許可。

  6. 選擇建立登錄檔。

注意

自動偵測會在目前區域中執行。若要探索其他區域中的資源，請在每個區域中建立啟用自動偵測的個別登錄檔。每個區域只能啟用一個登錄檔的自動偵測。

AWS CLI 

aws agent-registry-control create-registry \
  --name "my-organization-registry" \
  --description "Auto-detected resources across my organization" \
  --auto-detection-configuration '{"scope":"ORGANIZATION","enabled":true}' \
  --region us-east-1

當您執行 get-registry或 時list-registries，您會看到兩個不同的狀態欄位。登錄status欄位會開始為 ，CREATING並在佈建完成READY時轉換為 。autoDetection.status 欄位會個別追蹤：INACTIVE直到自動偵測執行，然後變成 ACTIVE。當登錄status檔為 READY且autoDetection.status為 時ACTIVE，會開始顯示您成員帳戶中支援資源的記錄。

注意

enabled 將 設定為 true請求自動偵測，但本身不夠。ACTIVE 只有當兩個先決條件都符合時， autoDetection.status 欄位才會變成：啟用受信任存取以進行自動偵測，且登錄檔由管理帳戶或註冊的委派管理員擁有。這些條件也必須傳播，這可能需要您啟用受信任存取或註冊委派管理員後的一小段時間。

確認偵測到資源

列出登錄檔的記錄，並尋找自動偵測所建立的記錄：

aws agent-registry-control list-registry-records \
  --registry-id <registry-id-or-arn> \
  --region us-east-1
注意

第一次設定時，自動偵測會探索成員帳戶中已存在的資源，而此初始探索最多可能需要 20 分鐘。預先存在資源的記錄可能不會立即顯示。

有關如何在您自行新增的記錄之外告知自動偵測的記錄，請參閱 識別自動偵測的記錄。

使用自動偵測的記錄

識別自動偵測的記錄

自動偵測的記錄由兩個特性識別：

  • 他們的記錄名稱字首為 aws-autodetected-。

  • 其中包括來源項目，其關係為 DETECTED_FROM，其sourceId為來源資源的 ARN，且其sourceType識別資源類型 （例如 AWS::BedrockAgentCore::Runtime或 AWS::BedrockAgentCore::Gateway)。

使用名稱字首來快速篩選自動偵測的記錄，以及將記錄追蹤回資源 — 和成員帳戶 — 的來源。

主控台

您可以在 主控台中以下列方式識別自動偵測的記錄：

  • 登錄檔記錄表格 – 登錄檔詳細資訊頁面上的記錄表格包含自動偵測記錄的三欄：自動偵測 （是/否）、來源類型 （例如 Bedrock AgentCore 執行期） 和來源 ID （來源資源 ARN)。

  • 屬性篩選條件 – 使用記錄資料表中的屬性篩選條件，依自動偵測 = 是或自動偵測 = 否進行篩選。

  • 記錄詳細資訊頁面 – 對於自動偵測的記錄，記錄詳細資訊頁面會顯示可擴展的驗證區段，其中顯示關聯 （偵測來源）、來源 ARN、來源類型、伺服器通訊協定和工作負載身分 ARN。

充實自動偵測的記錄

您可以使用 編輯自動偵測的記錄，以新增您自己的資訊，例如，更描述描述update-registry-record。您的編輯會保留；自動偵測會更新記錄的來源衍生欄位，而不會覆寫您設定的值。

aws agent-registry-control update-registry-record \
  --registry-id <registry-id-or-arn> \
  --record-id <record-id> \
  --description '{"optionalValue":"MCP server exposing the order-management API as agent tools"}' \
  --region us-east-1

AWS 客服人員登錄檔會將您擁有的欄位與自動偵測在自動偵測記錄上擁有的欄位分開：

欄位 您可以編輯 Behavior (行為)

name, description, recordVersion

是

已接受並保留；自動偵測不會在從來源重新整理記錄時覆寫它們。

描述項 data

是

您可以充實它。

recordType

有限

您可以將執行時間偵測到的記錄從 縮小AGENT為 MCP。任何其他變更 （例如 SKILL、 GATEWAY或 CUSTOM) 都會遭到拒絕，閘道偵測到的記錄一律為 GATEWAY。

描述項通訊協定 (kind)

否

衍生自來源資源；變更會遭到拒絕。

描述項來源 URL

否

衍生自來源資源；您無法變更或清除它。若要連接登入資料提供者以進行同步，請使用相同的 URL 提供描述項來源 — 請參閱同步記錄。

provenance

否

將記錄連結至其來源資源；變更會遭到拒絕。
注意

如果來源資源的通訊協定稍後變更，自動偵測會協調記錄的描述項，以符合新通訊協定，並重設recordType為 AGENT，以覆寫您所做的縮小範圍。會保留您的其他編輯，例如 name和 description 。

例如，使用MCP通訊協定偵測到的執行期會以 mcpServer 描述項分類為 recordType AGENT ，而您將記錄縮減為 MCP。如果該執行時間稍後更新為使用A2A通訊協定，則下一次重新整理會將mcpServer描述項取代為a2aAgentCard描述項，並從recordTypeMCP返回 重設為 AGENT。name您recordVersion設定的 description、 和 保持不變。

刪除自動偵測的記錄

啟用自動偵測時，您無法刪除自動偵測的記錄 (autoDetectionConfiguration.enabled 為 true)。自動偵測會管理這些記錄的生命週期 — 當來源資源刪除或成員帳戶離開組織時，記錄會自動移除。

若要手動刪除自動偵測的記錄，您必須先將 enabled設定為 來停用登錄檔上的自動偵測false。停用自動偵測後，您可以刪除自動偵測的記錄，就像刪除任何其他記錄一樣。

核准

自動偵測的記錄會遵循與您手動建立的記錄相同的核准工作流程：記錄必須處於 APPROVED 狀態，才能透過登錄檔的探索 APIs和記錄目錄探索。如果登錄檔設定為自動核准，則無需手動檢閱即可探索記錄，否則策展者會檢閱並核准記錄。如需詳細資訊，請參閱策劃登錄檔。

當自動偵測重新整理您已核准的記錄時，例如，因為來源資源的通訊協定已變更，重新整理的內容會寫入為新的Draft修訂版本，且在核准之前無法探索。您先前核准的修訂會同時保持可探索狀態，因此探索不會中斷。核准重新整理的修訂以進行發佈 — 如果登錄檔使用自動核准，則提交以供核准會立即核准；否則，策展者會檢閱並核准它。不會變更來源來源欄位的重新整理會讓記錄保持不變。

關閉自動偵測

在登錄檔上停用自動偵測

若要停止探索資源，請更新登錄檔，將自動偵測設定為 enabled false。您必須先停用自動偵測，才能刪除組織範圍的登錄。

若要刪除組織範圍的登錄檔，請依序完成這些步驟：

  1. 在登錄檔上停用自動偵測。

  2. 刪除所有登錄檔記錄。

  3. 刪除登錄檔。

aws agent-registry-control update-registry \
  --registry-id <registry-id-or-arn> \
  --auto-detection-configuration '{"optionalValue":{"scope":"ORGANIZATION","enabled":false}}' \
  --region us-east-1

更新是非同步的：當變更生效READY時，登錄檔會移至 UPDATING 並返回 。

取消註冊委派管理員或停用受信任存取

若要移除組織層級的自動偵測，管理帳戶可以取消註冊委派管理員並停用信任的存取：

aws organizations deregister-delegated-administrator \
  --account-id <delegated-admin-account-id> \
  --service-principal agent-registry.amazonaws.com
aws organizations disable-aws-service-access \
  --service-principal agent-registry.amazonaws.com

停用受信任存取，或取消註冊擁有登錄檔的委派管理員， 也會將登錄檔的 autoDetectionConfiguration.enabled 設定為 ，false而其 autoDetection.status設定為 INACTIVE。狀態原因顯示「組織的信任存取已停用。」

重要

如果您在停用信任的存取之後重新啟用，則自動偵測不會自動恢復。您必須手動更新登錄檔的自動偵測組態，才能將 設enabled回 true。

疑難排解

如需自動偵測問題的故障診斷，請參閱主要故障診斷頁面中的自動偵測錯誤。