建置您的第一個已驗證代理程式

此入門教學課程將逐步引導您使用 Amazon Bedrock AgentCore Identity 從頭開始建置完整的已驗證代理程式，並協助您開始在代理程式應用程式中實作身分功能。您將了解如何設定開發環境、使用 Cognito 建立身分驗證基礎設施、將代理程式部署到 AgentCore 執行期，以及測試完整的身分驗證工作流程。

在本教學課程結束時，您將擁有完全部署的代理程式，可透過 OAuth2 流程驗證使用者、安全地取得存取權杖，並示範完整的身分管理生命週期。您的代理程式將在具有適當 IAM 許可的 AgentCore 執行期上執行，建立測試實驗室環境，您可以在其中示範和測試整合功能。

先決條件

開始前，請確保您具備以下條件：

本教學課程需要您擁有 OAuth 2.0 授權伺服器。如果您沒有，步驟 1 將使用 Amazon Cognito 使用者集區為您建立一個。如果您的 OAuth 2.0 授權伺服器已設定用戶端 ID、用戶端秘密和使用者，您可以繼續進行步驟 2。此授權伺服器將充當資源登入資料提供者，代表授權代理程式傳出 OAuth 2.0 存取字符。

安裝 SDK 和相依性

建立本指南的資料夾、建立 Python 虛擬環境，並安裝 AgentCore SDK 和 AWS Python SDK (boto3)。

mkdir agentcore-identity-quickstart
cd agentcore-identity-quickstart
python3 -m venv .venv
source .venv/bin/activate
pip install bedrock-agentcore boto3 strands-agents pyjwt

也請使用下列內容建立 requirements.txt 檔案。這稍後將由 AgentCore 部署工具使用。

bedrock-agentcore
boto3
pyjwt
strands-agents

步驟 1：建立 Cognito 使用者集區 （選用）

本教學課程需要 OAuth 2.0 授權伺服器。如果您沒有可用於測試的 ，或者如果您想要將測試與授權伺服器分開，此指令碼將使用您的 AWS 登入資料來設定 Amazon Cognito 執行個體，供您做為授權伺服器使用。指令碼將建立：

刪除 Cognito 使用者集區 AgentCoreIdentityQuickStartPool 也會刪除相關聯的 client_id 和使用者。

您可以選擇將此指令碼儲存為 create_cognito.sh，然後從命令列執行，或將指令碼貼到您的命令列。

#!/bin/bash

REGION=$(aws configure get region)

# Create user pool
USER_POOL_ID=$(aws cognito-idp create-user-pool \
  --pool-name AgentCoreIdentityQuickStartPool \
  --query 'UserPool.Id' \
  --no-cli-pager \
  --output text)

# Create user pool domain
DOMAIN_NAME="agentcore-quickstart-$(LC_ALL=C tr -dc 'a-z0-9' < /dev/urandom | head -c 5)"
aws cognito-idp create-user-pool-domain \
  --domain $DOMAIN_NAME \
  --no-cli-pager \
  --user-pool-id $USER_POOL_ID > /dev/null

# Create user pool client with secret and hosted UI settings
CLIENT_RESPONSE=$(aws cognito-idp create-user-pool-client \
  --user-pool-id $USER_POOL_ID \
  --client-name AgentCoreQuickStart \
  --generate-secret \
  --allowed-o-auth-flows "code" \
  --allowed-o-auth-scopes "openid" "profile" "email" \
  --allowed-o-auth-flows-user-pool-client \
  --supported-identity-providers "COGNITO" \
  --query 'UserPoolClient.{ClientId:ClientId,ClientSecret:ClientSecret}' \
  --output json)

CLIENT_ID=$(echo $CLIENT_RESPONSE | jq -r '.ClientId')
CLIENT_SECRET=$(echo $CLIENT_RESPONSE | jq -r '.ClientSecret')

# Generate random username and password
USERNAME="AgentCoreTestUser$(printf "%04d" $((RANDOM % 10000)))"
PASSWORD="$(LC_ALL=C tr -dc 'A-Za-z0-9!@#$%^&*()_+-=[]{}|;:,.<>?' < /dev/urandom | head -c 16)$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 1)"

# Create user with permanent password
aws cognito-idp admin-create-user \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --output text > /dev/null

aws cognito-idp admin-set-user-password \
  --user-pool-id $USER_POOL_ID \
  --username $USERNAME \
  --password $PASSWORD \
  --output text > /dev/null \
  --permanent

# Get region

ISSUER_URL="https://cognito-idp.$REGION.amazonaws.com/$USER_POOL_ID/.well-known/openid-configuration"
HOSTED_UI_URL="https://$DOMAIN_NAME.auth.$REGION.amazoncognito.com"

# Output results
echo "User Pool ID: $USER_POOL_ID"
echo "Client ID: $CLIENT_ID"
echo "Client Secret: $CLIENT_SECRET"
echo "Issuer URL: $ISSUER_URL"
echo "Hosted UI URL: $HOSTED_UI_URL"
echo "Test User: $USERNAME"
echo "Test Password: $PASSWORD"

echo ""
echo "# Copy and paste these exports to set environment variables for later use:"
echo "export USER_POOL_ID='$USER_POOL_ID'"
echo "export CLIENT_ID='$CLIENT_ID'"
echo "export CLIENT_SECRET='$CLIENT_SECRET'"
echo "export ISSUER_URL='$ISSUER_URL'"
echo "export HOSTED_UI_URL='$HOSTED_UI_URL'"
echo "export COGNITO_USERNAME='$USERNAME'"
echo "export COGNITO_PASSWORD='$PASSWORD'"

步驟 2：建立登入資料提供者

登入資料提供者是您的代理程式存取外部服務的方式。建立登入資料提供者，並使用授權伺服器的 OAuth 2.0 用戶端進行設定。

如果您使用自己的授權伺服器，請從授權伺服器設定環境變數 ISSUER_URL 、 CLIENT_ID 和 CLIENT_SECRET及其適當的值。如果您使用先前的指令碼來建立 Cognito 的授權伺服器，請將輸出中的 EXPORT 陳述式複製到終端機，以設定環境變數。

此登入資料提供者將由代理程式的程式碼使用，以取得存取權杖以代表您的使用者採取行動。

步驟 2.5：將回呼 URL 新增至 OAuth 2.0 授權伺服器

若要防止未經授權的重新導向，請將從 CreateOauth2CredentialProvider 或 GetOauth2CredentialProvider 擷取的回呼 URL 新增至您的 OAuth 2.0 授權伺服器。

如果您使用先前的指令碼建立具有 Cognito 的授權伺服器，請將輸出的 EXPORT 陳述式複製到終端機，以設定環境變數，並使用 OAuth2 憑證提供者回呼 URL 更新 Cognito 使用者集區用戶端。

#!/bin/bash
aws cognito-idp update-user-pool-client \
    --user-pool-id $USER_POOL_ID \
    --client-id $CLIENT_ID \
    --client-name AgentCoreQuickStart \
    --allowed-o-auth-flows "code" \
    --allowed-o-auth-scopes "openid" "profile" "email" \
    --allowed-o-auth-flows-user-pool-client \
    --supported-identity-providers "COGNITO" \
    --callback-urls "$OAUTH2_CALLBACK_URL"

步驟 3：建立啟動 OAuth 2.0 流程的範例代理程式

在此步驟中，我們將建立啟動 OAuth 2.0 授權流程的代理程式，以取得代表使用者的字符。為求簡化，客服人員不會代表使用者實際呼叫外部服務，但會向我們證明已取得代表測試使用者的同意。

客服人員代碼

建立名為 agentcoreidentityquickstart.py 的檔案，並儲存此程式碼。

"""
AgentCore Identity Outbound Token Agent

This agent demonstrates the USER_FEDERATION OAuth 2.0 flow.

It handles the OAuth 2.0 user consent flow and inspects the resulting OAuth 2.0 access token.
"""

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from bedrock_agentcore.identity import requires_access_token
import asyncio
import jwt
import logging

app = BedrockAgentCoreApp()

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def decode_jwt(token):
    try:
        decoded = jwt.decode(token, options={"verify_signature": False})
        return decoded
    except Exception as e:
        return {"error": f"Error decoding JWT: {str(e)}"}

class StreamingQueue:
    def __init__(self):
        self.finished = False
        self.queue = asyncio.Queue()

    async def put(self, item):
        await self.queue.put(item)

    async def finish(self):
        self.finished = True
        await self.queue.put(None)

    async def stream(self):
        while True:
            item = await self.queue.get()
            if item is None and self.finished:
                break
            yield item

queue = StreamingQueue()

async def handle_auth_url(url):
    await queue.put(f"Authorization URL, please copy to your preferred browser: {url}")

@requires_access_token(
    provider_name="AgentCoreIdentityQuickStartProvider",
    scopes=["openid"],
    auth_flow="USER_FEDERATION",
    on_auth_url=handle_auth_url, # streams authorization URL to client
    force_authentication=True,
    callback_url='insert_oauth2_callback_url_for_session_binding',
)
async def introspect_with_decorator(*, access_token: str):
    """Introspect token using decorator"""
    logger.info("Inside introspect_with_decorator - decorator succeeded")
    await queue.put({
        "message": "Successfully received an access token to act on behalf of your user!",
        "token_claims": decode_jwt(access_token),
        "token_length": len(access_token),
        "token_preview": f"{access_token[:50]}...{access_token[-10:]}"
    })
    await queue.finish()

@app.entrypoint
async def agent_invocation(payload, context):
    """Handler that uses only the decorator approach"""
    logger.info("Agent invocation started")

    # Start the agent task and immediately begin streaming
    task = asyncio.create_task(introspect_with_decorator())

    # Stream items as they come in
    async for item in queue.stream():
        yield item

    # Wait for task completion
    await task

if __name__ == "__main__":
    app.run()

步驟 4：將代理程式部署到 AgentCore 執行期

我們將在 AgentCore 執行期託管此代理程式。我們可以透過 AgentCore CLI 輕鬆執行此操作。

從終端機安裝 AgentCore CLI 並建立新的專案：

npm install -g @aws/agentcore
agentcore create --name IdentityQuickstart --defaults

將您的代理程式指令碼複製到專案的代理程式目錄，取代預設代理程式：

cp agentcoreidentityquickstart.py IdentityQuickstart/app/IdentityQuickstart/main.py

同時將您的需求檔案複製到代理程式目錄，以確保所有相依性都包含在部署中：

cp requirements.txt IdentityQuickstart/app/IdentityQuickstart/

然後部署您的專案：

cd IdentityQuickstart
agentcore deploy

CLI 會合成 AWS CDK 堆疊，並將您的代理程式部署到 AgentCore 執行期。這大約需要 2-3 分鐘。

更新代理程式的 IAM 政策，以存取字符保存庫和用戶端秘密

AgentCore CLI 會在部署期間建立代理程式的執行角色，但該角色不會自動包含權杖保存庫存取的許可。您需要連接其他政策，以允許代理程式在執行時間擷取 OAuth 2.0 權杖。

此指令碼會從 CLI AWS 擷取您的帳戶和區域，從 CloudFormation 堆疊尋找代理程式的執行角色，並連接適當的政策。您可以複製並貼上此指令碼，或將其儲存至檔案並執行。

#!/bin/bash

# Get account and region from AWS CLI
AWS_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
REGION=$(aws configure get region)

# Get execution role from CloudFormation stack outputs
EXECUTION_ROLE=$(aws cloudformation describe-stack-resources \
  --stack-name AgentCore-IdentityQuickstart-prod \
  --query "StackResources[?ResourceType=='AWS::IAM::Role'].PhysicalResourceId" \
  --output text | head -1)

echo "Parsed values:"
echo "Execution Role: $EXECUTION_ROLE"
echo "Account: $AWS_ACCOUNT"
echo "Region: $REGION"

# Create the policy document with proper variable substitution
cat > agentcore-identity-policy.json << EOF
{
"Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AccessTokenVault",
      "Effect": "Allow",
      "Action": [
        "bedrock-agentcore:GetResourceOauth2Token",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": ["arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default/workload-identity/*",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default/oauth2credentialprovider/AgentCoreIdentityQuickStartProvider",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:workload-identity-directory/default",
        "arn:aws:bedrock-agentcore:$REGION:$AWS_ACCOUNT:token-vault/default",
        "arn:aws:secretsmanager:$REGION:$AWS_ACCOUNT:secret:bedrock-agentcore-identity!default/oauth2/AgentCoreIdentityQuickStartProvider*"
      ]
    }
  ]
}
EOF

# Create the policy
POLICY_ARN=$(aws iam create-policy \
    --policy-name AgentCoreIdentityQuickStartPolicy$(LC_ALL=C tr -dc '0-9' < /dev/urandom | head -c 4) \
    --policy-document file://agentcore-identity-policy.json \
    --query 'Policy.Arn' \
    --output text)

# Extract role name from ARN and attach policy
ROLE_NAME=$(echo $EXECUTION_ROLE | awk -F'/' '{print $NF}')
aws iam attach-role-policy \
    --role-name $ROLE_NAME \
    --policy-arn $POLICY_ARN

echo "Policy created and attached: $POLICY_ARN"

# Cleanup
rm agentcore-identity-policy.json

步驟 5：叫用代理程式

現在所有設定完成，您可以叫用 代理程式。在此示範中，我們將使用 agentcore invoke命令和我們的 IAM 登入資料。使用 IAM 身分驗證時，我們需要傳遞 --user-id和 --session-id引數。

agentcore invoke "TestPayload" --runtime IdentityQuickstart --user-id "SampleUserID" --session-id "ALongThirtyThreeCharacterMinimumSessionIdYouCanChangeThisAsYouNeed"

然後，代理程式會將 URL 傳回至您的agentcore invoke命令。將該 URL 複製並貼到您偏好的瀏覽器，然後系統會將您重新導向至授權伺服器的登入頁面。--user-id 參數是您向 AgentCore Identity 呈現的使用者 ID。--session-id 參數是工作階段 ID，長度必須至少為 33 個字元。

在瀏覽器上出現提示時，輸入授權伺服器上使用者的使用者名稱和密碼，或使用您設定的偏好身分驗證方法。如果您使用步驟 1 的指令碼來建立 Cognito 執行個體，您可以從終端機歷史記錄中擷取。

您的瀏覽器應該重新導向至您設定的 OAuth2 回呼 URL，這會處理工作階段繫結流程 。確保您的 OAuth2 回呼伺服器提供明確的成功和錯誤回應，以指出授權狀態。

除錯

如果您遇到任何錯誤或意外行為，代理程式的輸出會擷取在 Amazon CloudWatch logs中。日誌結尾命令會在您執行 後提供agentcore deploy。

清除

完成後，agentcore deploy從您的專案目錄執行 agentcore remove all ，然後從中解壓縮已部署的 AgentCore 執行期資源。然後刪除 Amazon Cognito 使用者集區，分離並刪除您建立的 IAM 政策，然後刪除登入資料提供者。

安全最佳實務

使用身分資訊時：