AgentCore 결제 빠른 시작

다음 단계에서 이러한 값을 사용합니다.

다음 단계에서는 다음 네 가지 값을 사용합니다.

import boto3

client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

credential_provider = client.create_payment_credential_provider(
    name="my-coinbase-credentials",
    credentialProviderVendor="CoinbaseCDP",
    coinbaseCdpConfig={
        "apiKeyId": "<YOUR_CDP_API_KEY_ID>",
        "apiKeySecret": "<YOUR_CDP_API_KEY_SECRET>",
        "walletSecret": "<YOUR_CDP_WALLET_SECRET>"
    }
)
CREDENTIAL_PROVIDER_ARN = credential_provider["credentialProviderArn"]
print(f"Credential provider created: {CREDENTIAL_PROVIDER_ARN}")

import boto3

client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

credential_provider = client.create_payment_credential_provider(
    name="my-privy-credentials",
    credentialProviderVendor="StripePrivy",
    stripePrivyConfig={
        "appId": "<YOUR_PRIVY_APP_ID>",
        "appSecret": "<YOUR_PRIVY_APP_SECRET>",
        "authorizationId": "<YOUR_PRIVY_AUTHORIZATION_ID>",
        "authorizationPrivateKey": "<YOUR_PRIVY_PRIVATE_KEY_BASE64>"
    }
)
CREDENTIAL_PROVIDER_ARN = credential_provider["credentialProviderArn"]
print(f"Credential provider created: {CREDENTIAL_PROVIDER_ARN}")

JWT 권한 부여 및 사용자 지정 클레임을 포함한 전체 콘솔 연습은 Payment Manager 및 커넥터 생성을 참조하세요.

agentcore add payment-manager \
  --name my-payment-manager \
  --auto-payment \
  --default-spend-limit 5.00

아래 공급자 섹션에 커넥터를 추가한 다음를 실행합니다agentcore deploy.

from bedrock_agentcore.payments.client import PaymentClient

payment_client = PaymentClient(region_name="us-west-2")

manager = payment_client.create_payment_manager(
    name="my-first-payment-manager",
    authorizer_type="AWS_IAM",
    role_arn="<YOUR_SERVICE_ROLE_ARN>",
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]

와 PAYMENT_MANAGER_ID 함께 payment_client를 사용하여 아래 공급자 섹션에서 커넥터를 생성합니다.

aws bedrock-agentcore-control create-payment-manager \
  --name "my-first-payment-manager" \
  --authorizer-type AWS_IAM \
  --role-arn "<YOUR_SERVICE_ROLE_ARN>" \
  --region us-west-2

관리자가에 도달할 때까지 기다린 READY다음 아래 공급자 섹션에서 커넥터를 생성합니다.

import time

manager = client.create_payment_manager(
    name="my-first-payment-manager",
    authorizerType="AWS_IAM",
    roleArn="<YOUR_SERVICE_ROLE_ARN>"
)
PAYMENT_MANAGER_ID = manager["paymentManagerId"]

while client.get_payment_manager(paymentManagerId=PAYMENT_MANAGER_ID)["status"] != "READY":
    time.sleep(5)

agentcore add payment-connector \
  --manager my-payment-manager \
  --name my-coinbase-connector \
  --provider CoinbaseCDP \
  --provision-mode QUICK_CREATE

agentcore deploy

CLI는 Coinbase 권한 부여 흐름을 엽니다. 권한을 부여하면 서비스가 자격 증명을 프로비저닝하고 커넥터가에 도달합니다READY.

connector = payment_client.create_payment_connector(
    payment_manager_id=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    connector_type="CoinbaseCDP",
    credential_provider_configurations=[],
    provision_mode="QUICK_CREATE",
)
# Open connector["authorizationUrl"], authorize through Coinbase,
# then poll get_payment_connector until status == "READY".

aws bedrock-agentcore-control create-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --name "my-coinbase-connector" \
  --type CoinbaseCDP \
  --credential-provider-configurations '[]' \
  --provision-mode QUICK_CREATE \
  --region us-west-2

응답에는 status: PENDING_AUTHENTICATION 및가 포함됩니다authorizationUrl. 브라우저에서 URL을 열고 Coinbase 권한 부여를 완료한 다음 커넥터가가 될 때까지 폴링합니다READY.

aws bedrock-agentcore-control get-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --payment-connector-id "<PAYMENT_CONNECTOR_ID>" \
  --region us-west-2

connector = client.create_payment_connector(
    paymentManagerId=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    type="CoinbaseCDP",
    credentialProviderConfigurations=[],
    provisionMode="QUICK_CREATE",
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(connector["status"], connector.get("authorizationUrl"))
# PENDING_AUTHENTICATION  https://...
# Open the authorizationUrl, authorize, then poll get_payment_connector until READY.

agentcore add payment-connector \
  --manager <manager-name> \
  --name my-coinbase-connector \
  --provider CoinbaseCDP \
  --api-key-id <YOUR_API_KEY_ID> \
  --api-key-secret <YOUR_API_KEY_SECRET> \
  --wallet-secret <YOUR_WALLET_SECRET>

agentcore deploy

CLI는 자격 증명을 AgentCore 자격 증명에 저장하고를 실행할 때 커넥터를 생성합니다agentcore deploy.

connector = payment_client.create_payment_connector(
    payment_manager_id=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    connector_type="CoinbaseCDP",
    credential_provider_configurations=[
        {"coinbaseCDP": {"credentialProviderArn": CREDENTIAL_PROVIDER_ARN}}
    ],
)

aws bedrock-agentcore-control create-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --name "my-coinbase-connector" \
  --type CoinbaseCDP \
  --credential-provider-configurations '[{"coinbaseCDP":{"credentialProviderArn":"<CREDENTIAL_PROVIDER_ARN>"}}]' \
  --region us-west-2

connector = client.create_payment_connector(
    paymentManagerId=PAYMENT_MANAGER_ID,
    name="my-coinbase-connector",
    type="CoinbaseCDP",
    credentialProviderConfigurations=[{"coinbaseCDP": {"credentialProviderArn": CREDENTIAL_PROVIDER_ARN}}],
)

agentcore add payment-connector \
  --manager <manager-name> \
  --name my-privy-connector \
  --provider StripePrivy \
  --app-id <YOUR_APP_ID> \
  --app-secret <YOUR_APP_SECRET> \
  --authorization-id <YOUR_AUTHORIZATION_ID> \
  --authorization-private-key <YOUR_PRIVATE_KEY_BASE64>

agentcore deploy

CLI는 자격 증명을 AgentCore 자격 증명에 저장하고를 실행할 때 커넥터를 생성합니다agentcore deploy.

connector = payment_client.create_payment_connector(
    payment_manager_id=PAYMENT_MANAGER_ID,
    name="my-privy-connector",
    connector_type="StripePrivy",
    credential_provider_configurations=[
        {"stripePrivy": {"credentialProviderArn": CREDENTIAL_PROVIDER_ARN}}
    ],
)

aws bedrock-agentcore-control create-payment-connector \
  --payment-manager-id "<PAYMENT_MANAGER_ID>" \
  --name "my-privy-connector" \
  --type StripePrivy \
  --credential-provider-configurations '[{"stripePrivy":{"credentialProviderArn":"<CREDENTIAL_PROVIDER_ARN>"}}]' \
  --region us-west-2

connector = client.create_payment_connector(
    paymentManagerId=PAYMENT_MANAGER_ID,
    name="my-privy-connector",
    type="StripePrivy",
    credentialProviderConfigurations=[{"stripePrivy": {"credentialProviderArn": CREDENTIAL_PROVIDER_ARN}}],
)

from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

instrument = manager.create_payment_instrument(
    user_id="test-user-123",
    payment_connector_id=PAYMENT_CONNECTOR_ID,
    payment_instrument_type="EMBEDDED_CRYPTO_WALLET",
    payment_instrument_details={
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    },
)
INSTRUMENT_ID = instrument["paymentInstrumentId"]
REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"]
print(f"Instrument created: {INSTRUMENT_ID}")
print(f"Fund the wallet at: {REDIRECT_URL}")

aws bedrock-agentcore create-payment-instrument \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-connector-id "$PAYMENT_CONNECTOR_ID" \
    --user-id "test-user-123" \
    --payment-instrument-type "EMBEDDED_CRYPTO_WALLET" \
    --payment-instrument-details '{
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

응답에서 paymentInstrumentId 및 redirectUrl를 저장합니다.

import uuid

dp_client = boto3.client("bedrock-agentcore", region_name="us-west-2",
    endpoint_url="https://bedrock-agentcore.us-west-2.amazonaws.com")

instrument = dp_client.create_payment_instrument(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentConnectorId=PAYMENT_CONNECTOR_ID,
    paymentInstrumentType="EMBEDDED_CRYPTO_WALLET",
    paymentInstrumentDetails={
        "embeddedCryptoWallet": {
            "network": "ETHEREUM",
            "linkedAccounts": [{"email": {"emailAddress": "your-email@example.com"}}]
        }
    },
    clientToken=str(uuid.uuid4()),
)
INSTRUMENT_ID = instrument["paymentInstrumentId"]
REDIRECT_URL = instrument["paymentInstrumentDetails"]["redirectUrl"]
print(f"Instrument created: {INSTRUMENT_ID}")
print(f"Fund the wallet at: {REDIRECT_URL}")

instrument = manager.get_payment_instrument(
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID
)
print(f"Status: {instrument['status']}")

aws bedrock-agentcore get-payment-instrument \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --region us-west-2

while True:
    inst_status = dp_client.get_payment_instrument(
        paymentManagerArn=PAYMENT_MANAGER_ARN,
        paymentInstrumentId=INSTRUMENT_ID
    )
    if inst_status["status"] == "ACTIVE":
        print("Instrument is active and funded.")
        break
    print(f"Instrument status: {inst_status['status']}... waiting for funding")
    time.sleep(10)

CLI를 사용하는 경우 세션을 수동으로 생성할 필요가 없습니다. --auto-session 로 전달 agentcore invoke 및 CLI는 결제 관리자에 구성한 기본 지출 한도로 세션을 생성하거나 재사용합니다.

agentcore invoke \
  --prompt "your prompt here" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id test-user-123

SDK를 통해 생성한 특정 세션을 사용하려면 --payment-session-id 대신를 전달합니다--auto-session.

from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

session = manager.create_payment_session(
    user_id="test-user-123",
    limits={"maxSpendAmount": {"value": "5.00", "currency": "USD"}},
    expiry_time_in_minutes=60
)
SESSION_ID = session["paymentSessionId"]
print(f"Session created: {SESSION_ID} (expires in 60 minutes, $5.00 limit)")

aws bedrock-agentcore create-payment-session \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --user-id "test-user-123" \
    --expiry-time-in-minutes 60 \
    --limits '{"maxSpendAmount": {"value": "5.00", "currency": "USD"}}' \
    --client-token "$(uuidgen)" \
    --region us-west-2

session = dp_client.create_payment_session(
    userId="test-user-123",
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    expiryTimeInMinutes=60,
    limits={"maxSpendAmount": {"value": "5.00", "currency": "USD"}},
    clientToken=str(uuid.uuid4()),
)
SESSION_ID = session["paymentSessionId"]
print(f"Session created: {SESSION_ID} (expires in 60 minutes, $5.00 limit)")

전체 요청 및 응답 스키마는 API 참조의 CreatePaymentSession을 참조하세요.

결제 컨텍스트를 사용하여 배포된 에이전트를 호출합니다. CLI는 런타임에 결제 수단과 세션을 에이전트에게 전달하고 에이전트의 x402 인터셉터는 결제를 자동으로 처리합니다.

agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id test-user-123

세션을 자동으로 생성하는 대신 명시적 세션을 전달하려면:

agentcore invoke \
  --prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --payment-session-id <SESSION_ID> \
  --payment-user-id test-user-123

HTTP 402 응답을 받을 때 PaymentManager 클래스를 사용하여 결제 헤더를 생성합니다.

import uuid
from bedrock_agentcore.payments import PaymentManager

manager = PaymentManager(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    region_name="us-west-2"
)

# When you receive a 402 response, generate payment proof
payment_required_request = {
    "statusCode": 402,
    "headers": payment_required["headers"],
    "body": payment_required["body"],
}
payment_proof_headers = manager.generate_payment_header(
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID,
    payment_session_id=SESSION_ID,
    payment_required_request=payment_required_request,
    client_token=str(uuid.uuid4()),
)

payment_proof_headers 에는 결제 증명 헤더가 포함되어 있습니다. 유료 엔드포인트에 대한 요청을 재시도할 때이 헤더를 포함합니다.

x402 페이로드(지급 오케스트레이션을 직접 처리할 때 사용)를 사용하여 process-payment 직접를 호출합니다.

aws bedrock-agentcore process-payment \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-session-id "$SESSION_ID" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --payment-type "CRYPTO_X402" \
    --payment-input '{
        "cryptoX402": {
            "version": "2",
            "payload": {
                "scheme": "exact",
                "network": "eip155:84532",
                "amount": "100000",
                "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
                "payTo": "0xMERCHANT_ADDRESS",
                "maxTimeoutSeconds": 300,
                "extra": {"name": "USDC", "version": "2"}
            }
        }
    }' \
    --client-token "$(uuidgen)" \
    --region us-west-2

전체 요청 및 응답 스키마는 API 참조의 ProcessPayment를 참조하세요.

from strands import Agent
from strands_tools import http_request
from bedrock_agentcore.payments.integrations.config import AgentCorePaymentsPluginConfig
from bedrock_agentcore.payments.integrations.strands.plugin import AgentCorePaymentsPlugin

config = AgentCorePaymentsPluginConfig(
    payment_manager_arn=PAYMENT_MANAGER_ARN,
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID,
    payment_session_id=SESSION_ID,
    region="us-west-2",
)

plugin = AgentCorePaymentsPlugin(config=config)
agent = Agent(
    system_prompt="You are a helpful assistant that can access paid APIs.",
    tools=[http_request],
    plugins=[plugin],
)

# The agent handles 402 responses automatically
response = agent("Access the premium endpoint at https://example-x402-merchant.com/paid-api")
print(response)

기본 API 호출의 전체 요청 및 응답 스키마는 API 참조의 ProcessPayment를 참조하세요.

session = manager.get_payment_session(
    user_id="test-user-123",
    payment_session_id=SESSION_ID
)
print(f"Status: {session['status']}, Remaining: {session['remainingAmount']}")

계측 밸런스를 확인할 수도 있습니다.

balance = manager.get_payment_instrument_balance(
    user_id="test-user-123",
    payment_instrument_id=INSTRUMENT_ID
)
print(f"Remaining balance: {balance['amount']} {balance['currency']}")

aws bedrock-agentcore get-payment-session \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-session-id "$SESSION_ID" \
    --region us-west-2

aws bedrock-agentcore get-payment-instrument-balance \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --region us-west-2

session_status = dp_client.get_payment_session(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentSessionId=SESSION_ID
)
print(f"Session status: {session_status['status']}")
print(f"Amount spent: {session_status.get('spentAmount', '0.00')} USD")

계측 밸런스를 확인할 수도 있습니다.

balance = dp_client.get_payment_instrument_balance(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentInstrumentId=INSTRUMENT_ID
)
print(f"Remaining balance: {balance['amount']} {balance['currency']}")

agentcore remove payment-connector --manager my-payment-manager --name my-coinbase-connector --yes
agentcore remove payment-manager --name my-payment-manager --yes
agentcore deploy

remove 명령은 로컬 구성을 업데이트합니다. 후속 작업은 계정의 결제 인프라를 deploy 해제합니다.

from bedrock_agentcore.payments.client import PaymentClient

payment_client = PaymentClient(region_name="us-west-2")

payment_client.delete_payment_manager(
    payment_manager_id="<paymentManagerId>"
)

print("Payment Manager deleted.")

aws bedrock-agentcore delete-payment-instrument \
    --payment-manager-arn "$PAYMENT_MANAGER_ARN" \
    --payment-instrument-id "$INSTRUMENT_ID" \
    --region us-west-2

aws bedrock-agentcore-control delete-payment-connector \
    --payment-manager-id "$PAYMENT_MANAGER_ID" \
    --payment-connector-id "$PAYMENT_CONNECTOR_ID" \
    --region us-west-2

aws bedrock-agentcore-control delete-payment-manager \
    --payment-manager-id "$PAYMENT_MANAGER_ID" \
    --region us-west-2

# Delete payment instrument
dp_client.delete_payment_instrument(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentInstrumentId=INSTRUMENT_ID
)

# Delete payment connector
client.delete_payment_connector(
    paymentManagerArn=PAYMENT_MANAGER_ARN,
    paymentConnectorId=PAYMENT_CONNECTOR_ID
)

# Delete payment manager
client.delete_payment_manager(
    paymentManagerArn=PAYMENT_MANAGER_ARN
)

print("All payment resources deleted.")