# AgentCore 결제 빠른 시작
이 자습서에서는 AgentCore 결제를 설정하고 첫 번째 마이크로트랜잭션을 처리하는 방법을 안내합니다. 결국 에이전트는 테스트 네트워크에서 x402 프로토콜을 사용하여 리소스에 대한 비용을 지불합니다.
다음 두 가지 방법으로 결제를 설정할 수 있습니다.
+ [AgentCore Payments 스킬 사용](#payments-getting-started-skill) - Kiro, Claude Code 또는 Codex와 같은 AI 코딩 에이전트와의 안내 대화를 통해 모든 리소스를 프로비저닝하는 자동화된 설정 환경입니다. 스킬은 CLI 명령, SDK 스크립트 및 프레임워크 와이어링을 처리합니다.
+ [CLI, SDK 또는 Boto3 사용](#payments-getting-started-manual) step-by-step 수동 설정입니다. AgentCore AWS AWS
## AgentCore Payments 스킬 사용
AgentCore Payments 스킬은 대화형 안내 경험을 통해 전체 설정 프로세스를 자동화합니다. 다음 리소스를 프로비저닝합니다.
+ **PaymentCredentialProvider** - AgentCore 자격 증명에 결제 공급자 자격 증명을 저장합니다.
+ **Payment Manager** - 결제 작업을 조정하는 최상위 리소스입니다.
+ **Payment Connector** - AgentCore CLI를 통해 관리자를 자격 증명에 연결합니다.
+ **Payment Instrument** - 에이전트가 사용자를 대신하여 가맹점에 결제하는 데 사용하는 암호화 지갑입니다.
+ **결제 세션** - 지출 한도가 있는 시간 제한 컨텍스트입니다.
또한이 스킬은 프레임워크에 구애받지 않는 도구를 사용하여 에이전트에 결제를 연결하므로 Strands, LangGraph, OpenAI Agents SDK 또는 Python 프레임워크와 함께 작동합니다.
### 사전 조건
시작하기 전에 다음이 있는지 확인합니다.
+ ** AWS 자격 증명이 구성된 계정**(`aws configure`)
+ **AgentCore 결제를 사용할 수 있는 AWS 리전** - us-east-1, us-west-2, eu-central-1 또는 ap-southeast-2. [지원되는 AWS 리전을 참조하세요](agentcore-regions.md).
+ **Node.js 20 이상** 설치됨(Skill이 AgentCore CLI를 자동으로 설치함)
+ **유료 엔드포인트에 액세스하는 에이전트** -이 기술을 사용하면 에이전트가 x402 보호 APIs. 테스트에는 샌드박스 엔드포인트를 사용할 수 있습니다`https://sandbox.node4all.com/v1/x402-test`.
+ AI 코딩** [에이전트에 설치된 플러그인용 에이전트 도구 AWS](https://github.com/aws/agent-toolkit-for-aws) `aws-agents` ** 키트:
**Example**
------
#### [ Claude Code ]
```
/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-agents@agent-toolkit-for-aws
```
------
#### [ Codex ]
플러그인은 Marketplace 매니페스트에서 자동으로 검색됩니다. 마켓플레이스를 추가하려면 다음 명령을 실행합니다.
```
codex plugin marketplace add aws/agent-toolkit-for-aws
```
------
### 스킬 호출
결제 스킬은 [Agent Toolkit for AWS](https://github.com/aws/agent-toolkit-for-aws) `agents-build` 스킬의 일부입니다. 이를 트리거하려면 AI 코딩 에이전트에서 의도를 설명하세요. 예제:
+ “`aws-agents`플러그인에서 `agents-build` 스킬을 사용하여 에이전트에 결제 추가”
+ “`aws-agents`플러그인에서 `agents-build` 스킬을 사용하여 에이전트에 대한 마이크로트랜잭션 설정”
+ “`aws-agents`플러그인에서 `agents-build` 스킬을 사용하여 402 Payment Required 응답을 처리해야 합니다.”
+ “`aws-agents`플러그인에서 `agents-build` 스킬을 사용하여 x402 보호 APIs에 대한 요금을 지불하도록 에이전트에게 연결”
스킬은 결제 관련 의도를 감지하고 결제 워크플로를 자동으로 로드합니다.
### 스킬이 수행하는 작업
스킬은 결제 인프라를 end-to-end로 프로비저닝하는 자동화된 프로세스를 실행합니다. 스킬은 대부분의 단계를 자동으로 실행하고 입력을 위해 두 번 일시 중지합니다.
1. AgentCore CLI를 확인 또는 설치하고 프로젝트를 설정합니다.
1. 결제 관리자를 생성합니다.
1. **일시 중지 **-를 실행`agentcore add payment-connector`하여 공급자 보안 암호(Coinbase CDP 또는 Stripe Privy 보안 인증)를 입력합니다.
1. AWS 계정에 리소스를 배포합니다(`agentcore deploy -y`).
1. 프레임워크에 구애받지 않는 결제 도구(`x402_payment_tool.py`)를 에이전트에 연결
1. SDK를 통해 사용자당 Wallet(계측기) 및 예산 경계 세션을 생성합니다.
1. **일시 중지 **- 월렛(위임)에 권한을 부여하고 [Circle faucet](https://faucet.circle.com/) 웹 사이트에서 testnet USDC로 자금을 조달합니다.
1. 환경 변수를 설정하고 유료 엔드포인트에 대해 테스트 결제를 실행합니다.
커넥터 명령을 실행하기 전에 공급자로부터 자격 증명을 얻습니다.
+ **Coinbase CDP** - [Coinbase 개발자 플랫폼](https://portal.cdp.coinbase.com/) 웹 사이트의 API 키 ID, API 키 보안 암호 및 Wallet 보안 암호(위임된 서명 활성화됨).
+ **Stripe 권한** - [권한 대시보드](https://dashboard.privy.io/) 웹 사이트의 앱 ID, 앱 보안 암호, 권한 부여 ID 및 권한 부여 프라이빗 키입니다.
실행에 성공하면 에이전트가를 호출하고`x402_fetch`,를 감지하고`402`, AgentCore SDK를 통해 결제를 설정하고, 유료 콘텐츠`200`와 함께 반환을 재시도합니다.
## CLI, SDK 또는 Boto3 사용
이 섹션에서는 AgentCore CLI, CLI AWS 또는 AWS SDK(Boto3)를 사용하여 각 단계를 수동으로 안내합니다.
### 사전 조건
시작하기 전에 다음이 있는지 확인합니다.
+ ** AWS 자격 증명이 구성된 계정**(`aws configure`)
+ **Python 3.10 이상** 설치됨
+ **AgentCore 결제를 사용할 수 있는 AWS 리전** - us-east-1, us-west-2, eu-central-1 또는 ap-southeast-2. [지원되는 AWS 리전을 참조하세요](agentcore-regions.md).
필수 패키지를 설치합니다.
```
pip install boto3 bedrock-agentcore[strands-agents] strands-agents strands-agents-tools
```
자격 증명이 구성되어 있는지 확인합니다.
```
aws sts get-caller-identity
```
**작은 정보**
AgentCore CLI v0.19.0 이상이 설치되어 있는 경우 2, 3, 5, 6단계에서 SDK의 대안으로 CLI 명령을 사용할 수 있습니다. 아래 각 단계는 두 옵션을 모두 보여줍니다.
### 1단계: 결제 공급자 자격 증명 획득
AgentCore 결제는 Wallet 작업을 위해 외부 결제 공급자에 연결됩니다. 계속하기 전에 지원되는 공급자 중 하나의 자격 증명이 필요합니다.
**Example**
1. [Coinbase 개발자 플랫폼에](https://docs.cdp.coinbase.com/api-reference/v2/authentication) 로그인하고 프로젝트를 생성하거나 선택합니다.
1. API 키를 생성하고 **API 키 ID**, **API 키 보안** 암호 및 **Wallet 보안 암호를** 기록해 둡니다.
1. **프로젝트** > **지갑** > **비관리형 지갑** > **보안**에서 **위임 서명을** 활성화합니다.
다음 단계에서는 다음 세 가지 값을 사용합니다.
| 자격 증명 | 설명 |
| --- | --- |
| `API Key ID` | CDP 프로젝트의 퍼블릭 식별자 |
| `API Key Secret` | API 요청에 서명하기 위한 프라이빗 보안 암호 |
| `Wallet Secret` | 암호화 Wallet 작업에 대한 보안 암호(주소 추출, 트랜잭션 서명) |
1. [dashboard.privy.io](https://dashboard.privy.io/) **전용** Privy 앱을 생성합니다. 다른 용도로 사용되는 앱을 재사용하지 마십시오.
1. **앱 설정에서 앱 ID** 및 **앱 보안** 암호를 복사합니다.
1. **Wallet Infrastructure** > **Authorization**으로 이동하여 **New Key**를 선택하여 P-256 키 페어를 생성합니다.
다음 단계에서는 다음 네 가지 값을 사용합니다.
| 자격 증명 | 설명 |
| --- | --- |
| `App ID` | 권한 애플리케이션 식별자 |
| `App Secret` | server-to-server 기본 인증의 보안 암호 |
| `Authorization ID` | P-256 키 페어의 퍼블릭 키 식별자 |
| `Authorization Private Key` | P-256 키 페어의 프라이빗 키 |
보안 모범 사례 및 자격 증명 교체를 포함한 전체 세부 정보는 [사전 조건을 참조하세요](payments-prerequisites.md).
### 2단계: AgentCore 자격 증명에 자격 증명 저장
결제 공급자 자격 증명을 PaymentCredentialProvider로 저장합니다. 이렇게 하면 애플리케이션 코드가 아닌 AWS Secrets Manager에 보안 암호가 보관됩니다.
**Example**
```
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": "",
"apiKeySecret": "",
"walletSecret": ""
}
)
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": "",
"appSecret": "",
"authorizationId": "",
"authorizationPrivateKey": ""
}
)
CREDENTIAL_PROVIDER_ARN = credential_provider["credentialProviderArn"]
print(f"Credential provider created: {CREDENTIAL_PROVIDER_ARN}")
```
전체 요청 및 응답 스키마는 API 참조의 [CreatePaymentCredentialProvider](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentCredentialProvider.html)를 참조하세요.
#### CLI 대안: 자격 증명 저장
AgentCore CLI를 사용하면 결제 커넥터를 추가할 때 자격 증명 스토리지가 자동으로 수행됩니다(3단계). CLI 경로를 사용하려는 경우이 단계를 건너뜁니다.
### 3단계: Payment Manager 및 커넥터 생성
Payment Manager는 결제 작업을 조정하는 최상위 리소스입니다. Payment Connector는 관리자를 결제 공급자 자격 증명에 연결합니다. 이러한 리소스를 생성하기 전에 [ AgentCore 결제에 대한 IAM 역할에 설명된 대로 필요한 IAM 역할을](payments-iam-roles.md) 설정합니다.
**Example**
JWT 권한 부여 및 사용자 지정 클레임을 포함한 전체 콘솔 연습은 [Payment Manager 및 커넥터 생성을 참조하세요](payments-create-manager.md).
1. [Amazon Bedrock AgentCore 콘솔](https://console.aws.amazon.com/bedrock-agentcore/)을 엽니다.
1. 탐색 창의 **빌드**에서 **결제**를 선택합니다.
1. **Payment Manager 생성을** 선택합니다.
1. Payment Manager의 **이름을** 입력합니다.
1. **권한**에서 **새 서비스 역할 생성 및 사용을** 선택합니다(또는 기존 역할 선택).
1. **인바운드 인증**에서 **IAM 권한 부여에 IAM 사용자 이름 사용을** 선택합니다.
1. (선택 사항) **결제 커넥터** 섹션에서 커넥터의 이름을 선택하고 기존 아웃바운드 인증을 선택하거나 공급자(Coinbase 또는 Stripe Privy)를 선택하고 자격 증명을 입력하여 새 아웃바운드 인증을 생성합니다.
1. **Payment Manager 생성을** 선택합니다.
CLI는 자격 증명 공급자, Payment Manager 및 Payment Connector를 한 번에 생성합니다. AgentCore 프로젝트 디렉터리에서 결제 관리자와 커넥터를 함께 추가합니다.
**대화형 마법사:**
```
agentcore add payment-manager
```
마법사는 관리자 이름, 패턴(인터셉터), 자동 결제 토글 및 기본 지출 한도를 묻는 메시지를 표시합니다. 그런 다음 커넥터를 추가할지 여부를 묻고 공급자 선택 및 자격 증명 입력을 안내합니다.
**비대화형(Coinbase CDP):**
```
agentcore add payment-manager \
--name my-payment-manager \
--auto-payment \
--default-spend-limit 5.00
agentcore add payment-connector \
--manager my-payment-manager \
--name my-coinbase-connector \
--provider CoinbaseCDP \
--api-key-id \
--api-key-secret \
--wallet-secret
```
**비대화형(프라이비):**
```
agentcore add payment-manager \
--name my-payment-manager \
--auto-payment \
--default-spend-limit 5.00
agentcore add payment-connector \
--manager my-payment-manager \
--name my-privy-connector \
--provider StripePrivy \
--app-id \
--app-secret \
--authorization-id \
--authorization-private-key
```
추가한 후를 배포하여 결제 인프라를 프로비저닝합니다.
```
agentcore deploy
```
배포 단계에서는 IAM 역할을 생성하고, AgentCore 자격 증명을 AgentCore 자격 증명에 저장하고, Payment Manager 및 커넥터를 프로비저닝합니다. 출력에 "결제 인프라 생성..."이 표시됩니다.
AgentCore SDK는 한 번의 호출로 Payment Manager, 자격 증명 공급자 및 커넥터를 생성합니다.
```
from bedrock_agentcore.payments import PaymentClient
payment_client = PaymentClient(region_name="us-west-2")
response = payment_client.create_payment_manager_with_connector(
payment_manager_name="my-first-payment-manager",
payment_manager_description="Payment manager for my agent.",
authorizer_type="AWS_IAM",
role_arn="",
payment_connector_config={
"name": "my-coinbase-connector",
"description": "Coinbase CDP connector",
"payment_credential_provider_config": {
"name": "my-coinbase-provider",
"credential_provider_vendor": "CoinbaseCDP",
"credentials": {
"api_key_id": "",
"api_key_secret": "",
"wallet_secret": "",
},
},
},
wait_for_ready=True,
max_wait=300,
poll_interval=5,
)
PAYMENT_MANAGER_ARN = response["paymentManager"]["paymentManagerArn"]
PAYMENT_CONNECTOR_ID = response["paymentConnector"]["paymentConnectorId"]
print(f"Payment Manager ARN: {PAYMENT_MANAGER_ARN}")
print(f"Connector ID: {PAYMENT_CONNECTOR_ID}")
```
Stripe 권한의 경우를 `credential_provider_vendor: "StripePrivy"` 및 해당 권한 자격 증명`payment_credential_provider_config`으로 바꿉니다.
Payment Manager를 생성합니다.
```
aws bedrock-agentcore-control create-payment-manager \
--name "my-first-payment-manager" \
--authorizer-type AWS_IAM \
--role-arn "" \
--region us-west-2
```
관리자가 `READY` 상태에 도달하면 자격 증명 공급자와 커넥터를 생성합니다. 전체 AWS CLI 워크플로[는 Payment Manager 및 커넥터 생성을](payments-create-manager.md) 참조하세요.
먼저 Payment Manager를 생성합니다(두 공급자 모두 동일).
```
import time
manager = client.create_payment_manager(
name="my-first-payment-manager",
authorizerType="AWS_IAM",
roleArn=""
)
PAYMENT_MANAGER_ARN = manager["paymentManagerArn"]
print(f"Payment Manager created: {PAYMENT_MANAGER_ARN}")
# Wait for the manager to reach READY state
while True:
status = client.get_payment_manager(paymentManagerArn=PAYMENT_MANAGER_ARN)
if status["status"] == "READY":
break
print(f"Status: {status['status']}... waiting")
time.sleep(5)
```
그런 다음 공급자에 대한 Payment Connector를 생성합니다.
**Coinbase CDP:**
```
connector = client.create_payment_connector(
paymentManagerArn=PAYMENT_MANAGER_ARN,
name="my-coinbase-connector",
paymentConnectorType="CoinbaseCDP",
credentialProviderArn=CREDENTIAL_PROVIDER_ARN
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(f"Connector created: {PAYMENT_CONNECTOR_ID}")
```
**권한:**
```
connector = client.create_payment_connector(
paymentManagerArn=PAYMENT_MANAGER_ARN,
name="my-privy-connector",
paymentConnectorType="StripePrivy",
credentialProviderArn=CREDENTIAL_PROVIDER_ARN
)
PAYMENT_CONNECTOR_ID = connector["paymentConnectorId"]
print(f"Connector created: {PAYMENT_CONNECTOR_ID}")
```
서비스 역할이 없는 경우 생성 지침은 [ AgentCore 결제에 대한 IAM 역할을](payments-iam-roles.md) 참조하세요. 콘솔은 사용자를 대신하여 역할을 생성할 수도 있습니다. 전체 요청 및 응답 스키마는 API 참조의 [CreatePaymentManager](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentManager.html) 및 [CreatePaymentConnector](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_CreatePaymentConnector.html)를 참조하세요.
### 4단계: 결제 수단 생성
결제 수단은 에이전트가 사용자를 대신하여 가맹점에 결제하는 데 사용하는 임베디드 암호화 지갑입니다. 각 계측은 특정 블록체인 네트워크와 연결됩니다.
**Example**
```
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}")
```
전체 요청 및 응답 스키마는 API 참조의 [CreatePaymentInstrument](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreatePaymentInstrument.html)를 참조하세요.
#### Wallet에 자금 지원 및 권한 부여
에이전트가 트랜잭션하려면 먼저 최종 사용자가 Wallet에 자금을 지원하고 서명 권한을 부여해야 합니다. 브라우저에서 위의 응답`redirectUrl`에서를 엽니다. Wallet Hub에서 사용자는 다음을 수행할 수 있습니다.
+ 암호화 전송, 신용/직불 카드, Apple Pay, Google Pay 또는 ACH를 사용하여 지갑 보충
+ 에이전트를 대신하여 트랜잭션에 서명할 수 있는 권한을 에이전트에 부여합니다.
테스트 환경의 경우 testnet USDC로 Wallet에 자금을 지원합니다.
펀딩 후가 될 때까지 계측 상태를 폴링합니다`ACTIVE`.
**Example**
```
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)
```
공급자별 자금 흐름에 대한 자세한 내용은 [Wallet에 자금 지원을 참조하세요](payments-how-it-works.md#payments-how-it-works-funding-wallet).
### 5단계: 결제 세션 생성
결제 세션은 선택적 지출 한도가 있는 시간 제한 컨텍스트입니다. 세션이 만료되거나 예산이 소진되면 에이전트는 해당 세션 내에서 추가 결제를 수행할 수 없습니다.
**Example**
CLI를 사용하는 경우 세션을 수동으로 생성할 필요가 없습니다. `--auto-session` 로 전달 `agentcore invoke` 및 CLI는 결제 관리자에 구성한 기본 지출 한도로 세션을 생성하거나 재사용합니다.
```
agentcore invoke \
--prompt "your prompt here" \
--payment-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](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_CreatePaymentSession.html)을 참조하세요.
### 6단계: Strands 에이전트로 결제 처리
모든 리소스를 준비한 상태에서 x402 결제를 자동으로 처리하는 Strands 에이전트를 생성합니다. 에이전트가 유료 엔드포인트를 호출하고 HTTP 402 응답을 수신하면 결제 플러그인이 트랜잭션에 서명하고 요청을 재시도합니다.
**Example**
결제 컨텍스트로 배포된 에이전트를 호출합니다. CLI는 런타임에 결제 수단과 세션을 에이전트에게 전달하고 에이전트의 x402 인터셉터는 결제를 자동으로 처리합니다.
```
agentcore invoke \
--prompt "Access the premium endpoint at https://example-x402-merchant.com/paid-api" \
--payment-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 \
--payment-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](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ProcessPayment.html)를 참조하세요.
```
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](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_ProcessPayment.html)를 참조하세요.
### 결제 확인
에이전트가 결제를 처리한 후 세션을 확인하여 트랜잭션이 기록되었는지 확인합니다.
**Example**
```
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']}")
```
## 문제 해결
다음 문제는 스킬 기반 및 수동 설정 경로 모두에 적용됩니다.
| 문제 | Solution |
| --- | --- |
| Payment Manager가 CREATING에 멈춤 | 최대 2분간 기다립니다. CREATE\_FAILED로 이동하는 경우 서비스 역할 ARN 및 권한이 올바른지 확인합니다. |
| "PaymentInstrument가 활성화되지 않음" | 최종 사용자는 에이전트가 트랜잭션하려면 먼저 리디렉션 URL을 통해 Wallet에 자금을 지원하고 서명 권한을 부여해야 합니다. |
| “세션 만료 또는 예산 초과” | 만료 기간이 더 길거나 지출 한도가 더 높은 새 결제 세션을 생성합니다. |
| "CredentialProvider를 찾을 수 없음" | 자격 증명 공급자 ARN이 2단계에서 생성한 것과 일치하는지 확인합니다. 리전이 모든 호출에서 일관된지 확인합니다. |
| ProcessPayment에서 FAILED 반환 | Wallet에 거래 금액에 가스 요금을 더한 USDC 잔고가 충분한지 확인합니다. |
## 정리
이 자습서 중에 생성한 리소스를 삭제합니다.
**Example**
```
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 import PaymentClient
payment_client = PaymentClient(region_name="us-west-2")
payment_client.delete_payment_manager(
payment_manager_id=""
)
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.")
```
## 빌드한 내용
이 자습서를 통해 다음을 생성했습니다.
+ **PaymentCredentialProvider** - AgentCore 자격 증명에 저장된 결제 공급자 자격 증명
+ **PaymentManager** - 결제 작업을 조정하는 최상위 리소스
+ **PaymentConnector** - 관리자와 외부 결제 공급자 간의 통합
+ **PaymentInstrument** - 최종 사용자가 자금을 지원하고 승인한 임베디드 암호화 지갑
+ **PaymentSession** - 시간 제한, 예산 제한 결제 컨텍스트
+ **Strands 에이전트** - x402 결제를 자동으로 처리하는 AI 에이전트
## 다음 단계
+ [Coinbase x402 Bazaar에 연결하여](payments-connect-bazaar.md) 10,000개 이상의 유료 MCP 도구를 검색합니다.
+ [브라우저 도구와 통합하여](payments-browser.md) Paywalled 웹 사이트에 액세스합니다.
+ [관찰성을 활성화](payments-observability.md)하여 CloudWatch에서 결제 작업을 모니터링할 수 있습니다.
+ [IAM 역할을 검토하여](payments-iam-roles.md) 프로덕션에 대한 최소 권한 액세스를 구성합니다.