2026/05/07 - Amazon Bedrock AgentCore - 11 new1 updated api methods
Changes Launching AgentCore payments - a capability that provides secure, instant microtransaction payments for AI agents to access paid APIs, MCP servers, and content. It handles payment processing for x402 protocol, payment limits, and 3P wallet integrations with Coinbase CDP and Stripe (Privy).
Get the balance of a payment instrument
See also: AWS API Documentation
Request Syntax
client.get_payment_instrument_balance(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentConnectorId='string',
paymentInstrumentId='string',
chain='BASE'|'BASE_SEPOLIA'|'ETHEREUM'|'SOLANA'|'SOLANA_DEVNET',
token='USDC'
)
string
The user ID associated with this payment instrument.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns this payment instrument.
string
[REQUIRED]
The ID of the payment connector associated with this instrument.
string
[REQUIRED]
The ID of the payment instrument to query balance for.
string
[REQUIRED]
The specific blockchain chain to query balance on. Required because balances are chain-specific — the same wallet address may hold different token balances on different chains.
string
[REQUIRED]
The token to query balance for. Required to specify which supported token's balance to return.
dict
Response Syntax
{
'paymentInstrumentId': 'string',
'tokenBalance': {
'amount': 'string',
'decimals': 123,
'token': 'USDC',
'network': 'ETHEREUM'|'SOLANA',
'chain': 'BASE'|'BASE_SEPOLIA'|'ETHEREUM'|'SOLANA'|'SOLANA_DEVNET'
}
}
Response Structure
(dict) --
Response structure for getting payment instrument balance
paymentInstrumentId (string) --
The ID of the payment instrument.
tokenBalance (dict) --
The balance of the supported token on the requested chain.
amount (string) --
Raw balance in the smallest denomination (e.g., USDC base units where 1 USDC = 1000000).
decimals (integer) --
Number of decimal places for the token (e.g., 6 for USDC).
token (string) --
The supported token for this balance.
network (string) --
The blockchain network family (ETHEREUM or SOLANA).
chain (string) --
The specific blockchain chain.
List payment instruments for a manager
See also: AWS API Documentation
Request Syntax
client.list_payment_instruments(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentConnectorId='string',
nextToken='string',
maxResults=123
)
string
The user ID associated with the payment instruments.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns the payment instruments.
string
The ID of the payment connector to filter by.
string
Token for pagination to retrieve the next set of results.
integer
Maximum number of results to return in a single response.
dict
Response Syntax
{
'paymentInstruments': [
{
'paymentInstrumentId': 'string',
'paymentManagerArn': 'string',
'paymentConnectorId': 'string',
'userId': 'string',
'paymentInstrumentType': 'EMBEDDED_CRYPTO_WALLET',
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED',
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
Response structure for listing payment instruments
paymentInstruments (list) --
List of payment instrument summaries matching the request criteria.
(dict) --
Summary of a payment instrument for list operations
paymentInstrumentId (string) --
The unique identifier for this payment instrument.
paymentManagerArn (string) --
The ARN of the payment manager that owns this payment instrument.
paymentConnectorId (string) --
The ID of the payment connector associated with this instrument.
userId (string) --
The user ID associated with this payment instrument.
paymentInstrumentType (string) --
The type of payment instrument (e.g., EMBEDDED_CRYPTO_WALLET).
status (string) --
The current status of this payment instrument.
createdAt (datetime) --
The timestamp when this payment instrument was created.
updatedAt (datetime) --
The timestamp when this payment instrument was last updated.
nextToken (string) --
Token for pagination to retrieve the next set of results.
Create a new payment manager session
See also: AWS API Documentation
Request Syntax
client.create_payment_session(
userId='string',
agentName='string',
paymentManagerArn='string',
limits={
'maxSpendAmount': {
'value': 'string',
'currency': 'USD'
}
},
expiryTimeInMinutes=123,
clientToken='string'
)
string
The user ID associated with this payment session.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns this session.
dict
The spending limits for this payment session.
maxSpendAmount (dict) -- [REQUIRED]
The maximum amount that can be spent in this session.
value (string) -- [REQUIRED]
The numeric value of the amount.
currency (string) -- [REQUIRED]
The currency code for this amount.
integer
[REQUIRED]
The session expiry time in minutes. Must be between 15 and 480 minutes.
string
Idempotency token to ensure request uniqueness.
This field is autopopulated if not provided.
dict
Response Syntax
{
'paymentSession': {
'paymentSessionId': 'string',
'paymentManagerArn': 'string',
'limits': {
'maxSpendAmount': {
'value': 'string',
'currency': 'USD'
}
},
'userId': 'string',
'expiryTimeInMinutes': 123,
'createdAt': datetime(2015, 1, 1),
'availableLimits': {
'availableSpendAmount': {
'value': 'string',
'currency': 'USD'
},
'updatedAt': datetime(2015, 1, 1)
},
'updatedAt': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Response structure for creating a payment session
paymentSession (dict) --
Payment manager session
paymentSessionId (string) --
The unique identifier for this payment session.
paymentManagerArn (string) --
The ARN of the payment manager that owns this session.
limits (dict) --
The spending limits for this session.
maxSpendAmount (dict) --
The maximum amount that can be spent in this session.
value (string) --
The numeric value of the amount.
currency (string) --
The currency code for this amount.
userId (string) --
The user ID associated with this payment session.
expiryTimeInMinutes (integer) --
The session expiry time in minutes.
createdAt (datetime) --
The timestamp when this payment session was created.
availableLimits (dict) --
The available limits for this session after accounting for processed payments.
availableSpendAmount (dict) --
The available spend amount for this session.
value (string) --
The numeric value of the amount.
currency (string) --
The currency code for this amount.
updatedAt (datetime) --
The timestamp when the available limits were last updated.
updatedAt (datetime) --
The timestamp when this payment session was last updated.
Process a payment transaction
See also: AWS API Documentation
Request Syntax
client.process_payment(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentSessionId='string',
paymentInstrumentId='string',
paymentType='CRYPTO_X402',
paymentInput={
'cryptoX402': {
'version': 'string',
'payload': {...}|[...]|123|123.4|'string'|True|None
}
},
clientToken='string'
)
string
The user ID associated with this payment.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager handling this payment.
string
[REQUIRED]
The ID of the payment session for this transaction.
string
[REQUIRED]
The ID of the payment instrument to use for this transaction.
string
[REQUIRED]
The type of payment being processed.
dict
[REQUIRED]
The payment input details specific to the payment type.
cryptoX402 (dict) --
X402 payment requirement input
version (string) -- [REQUIRED]
The X402 protocol version (e.g., "v1", "v2")
payload (:ref:`document<document>`) -- [REQUIRED]
This can hold any JSON-like object
string
Idempotency token to ensure request uniqueness.
This field is autopopulated if not provided.
dict
Response Syntax
{
'processPaymentId': 'string',
'paymentManagerArn': 'string',
'paymentSessionId': 'string',
'paymentInstrumentId': 'string',
'paymentType': 'CRYPTO_X402',
'status': 'PROOF_GENERATED',
'paymentOutput': {
'cryptoX402': {
'version': 'string',
'payload': {...}|[...]|123|123.4|'string'|True|None
}
},
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
Response structure for processing a payment
processPaymentId (string) --
The unique ID of the processed payment transaction.
paymentManagerArn (string) --
The ARN of the payment manager that processed this payment.
paymentSessionId (string) --
The ID of the payment session for this transaction.
paymentInstrumentId (string) --
The ID of the payment instrument used for this transaction.
paymentType (string) --
The type of payment that was processed.
status (string) --
The status of the payment transaction.
paymentOutput (dict) --
The payment output details specific to the payment type.
cryptoX402 (dict) --
X402 payment requirement output
version (string) --
The X402 protocol version (e.g., "1", "2")
payload (:ref:`document<document>`) --
This can hold any JSON-like object
createdAt (datetime) --
The timestamp when the payment was created.
updatedAt (datetime) --
The timestamp when the payment was last updated.
Generates authentication tokens for payment providers that use vendor-specific authentication mechanisms.
See also: AWS API Documentation
Request Syntax
client.get_resource_payment_token(
workloadIdentityToken='string',
resourceCredentialProviderName='string',
paymentTokenRequest={
'coinbaseCdpTokenRequest': {
'requestMethod': 'GET'|'POST'|'PUT'|'DELETE'|'PATCH',
'requestHost': 'string',
'requestPath': 'string',
'includeWalletAuthToken': True|False,
'requestBody': 'string'
},
'stripePrivyTokenRequest': {
'requestHost': 'string',
'requestPath': 'string',
'requestBody': 'string',
'includeAuthorizationSignature': True|False
}
}
)
string
[REQUIRED]
Workload access token for authorization. Named workloadIdentityToken for consistency with APIKey and OAuth2CredentialProvider.
string
[REQUIRED]
Name of the payment credential provider to use
dict
[REQUIRED]
Vendor-specific token request input Contains all request parameters in a type-safe, vendor-specific structure
coinbaseCdpTokenRequest (dict) --
Coinbase CDP token request parameters
requestMethod (string) -- [REQUIRED]
The HTTP method for the payment API request.
requestHost (string) --
Optional - defaults to "api.cdp.coinbase.com"
requestPath (string) -- [REQUIRED]
The path of the payment API request.
includeWalletAuthToken (boolean) --
Set to true for wallet write operations (requires walletSecret configured)
requestBody (string) --
Request body JSON - used to generate wallet auth JWT
stripePrivyTokenRequest (dict) --
StripePrivy token request parameters
requestHost (string) --
Optional - defaults to "api.privy.io"
requestPath (string) -- [REQUIRED]
The path of the Stripe Privy API request.
requestBody (string) -- [REQUIRED]
Request body JSON for the Privy API call
includeAuthorizationSignature (boolean) --
Set to true to generate privy-authorization-signature
dict
Response Syntax
{
'paymentTokenResponse': {
'coinbaseCdpTokenResponse': {
'bearerToken': 'string',
'walletAuthToken': 'string'
},
'stripePrivyTokenResponse': {
'authorizationSignature': 'string',
'requestExpiry': 123,
'appId': 'string',
'basicAuthToken': 'string'
}
}
}
Response Structure
(dict) --
paymentTokenResponse (dict) --
Vendor-specific token response output Contains all response data in a type-safe, vendor-specific structure
coinbaseCdpTokenResponse (dict) --
Coinbase CDP token response
bearerToken (string) --
Bearer Token for Authorization header
walletAuthToken (string) --
Wallet Auth Token for X-Wallet-Auth header
stripePrivyTokenResponse (dict) --
StripePrivy token response containing appId, basicAuthToken, and optionally authorizationSignature
authorizationSignature (string) --
Base64-encoded ECDSA P-256 authorization signature (only present when includeAuthorizationSignature is true)
requestExpiry (integer) --
Unix timestamp in milliseconds when the authorization signature expires. Set as privy-request-expiry header.
appId (string) --
The Privy app ID for the privy-app-id header
basicAuthToken (string) --
Base64-encoded Basic Auth token (appId:appSecret) for the Authorization header
Delete a payment instrument
Marks a payment instrument as deleted by updating its status to DELETED. This is a soft delete operation that preserves the record in the database for audit and compliance purposes. The record remains queryable for audit purposes but is excluded from normal list and get operations.
Deleting an already-deleted or non-existent instrument returns ResourceNotFoundException (404).
Authorization: The caller must own the instrument (accountId, userId, and paymentManagerId must match). If authorization fails, a 403 Forbidden error is returned.
Timestamp Management: The updatedAt timestamp is set to the current time, while createdAt is preserved. The version field is incremented for optimistic locking.
Errors:
ResourceNotFoundException: The instrument does not exist or is already deleted
AccessDeniedException: The caller is not authorized to delete this instrument
ValidationException: Required fields are missing or invalid
InternalServerException: An unexpected server error occurred
See also: AWS API Documentation
Request Syntax
client.delete_payment_instrument(
userId='string',
paymentManagerArn='string',
paymentConnectorId='string',
paymentInstrumentId='string'
)
string
The user ID making the delete request. Must match the instrument's userId.
string
[REQUIRED]
The payment manager ARN. Must match the instrument's paymentManagerArn.
string
[REQUIRED]
The payment connector ID. Must match the instrument's paymentConnectorId.
string
[REQUIRED]
The payment instrument ID to delete.
dict
Response Syntax
{
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED'
}
Response Structure
(dict) --
Response structure for deleting a payment instrument
Returns the deletion status with HTTP 200 OK status code on successful soft deletion.
status (string) --
The status of the instrument after deletion. Always DELETED for successful soft delete.
List payment manager sessions
See also: AWS API Documentation
Request Syntax
client.list_payment_sessions(
userId='string',
agentName='string',
paymentManagerArn='string',
nextToken='string',
maxResults=123
)
string
The user ID associated with the payment sessions.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns the sessions.
string
Token for pagination to retrieve the next set of results.
integer
Maximum number of results to return in a single response.
dict
Response Syntax
{
'paymentSessions': [
{
'paymentSessionId': 'string',
'paymentManagerArn': 'string',
'userId': 'string',
'expiryTimeInMinutes': 123,
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
Response structure for listing payment sessions
paymentSessions (list) --
List of payment session summaries matching the request criteria.
(dict) --
Summary of a payment session for list operations
paymentSessionId (string) --
The unique identifier for this payment session.
paymentManagerArn (string) --
The ARN of the payment manager that owns this session.
userId (string) --
The user ID associated with this payment session.
expiryTimeInMinutes (integer) --
The session expiry time in minutes.
createdAt (datetime) --
The timestamp when this payment session was created.
updatedAt (datetime) --
The timestamp when this payment session was last updated.
nextToken (string) --
Token for pagination to retrieve the next set of results.
Create a new payment instrument for a connector
See also: AWS API Documentation
Request Syntax
client.create_payment_instrument(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentConnectorId='string',
paymentInstrumentType='EMBEDDED_CRYPTO_WALLET',
paymentInstrumentDetails={
'embeddedCryptoWallet': {
'network': 'ETHEREUM'|'SOLANA',
'linkedAccounts': [
{
'email': {
'emailAddress': 'string'
},
'sms': {
'phoneNumber': 'string'
},
'developerJwt': {
'kid': 'string',
'sub': 'string'
},
'oAuth2': {
'google': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'apple': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'x': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'telegram': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'github': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
}
}
},
],
'walletAddress': 'string',
'redirectUrl': 'string'
}
},
clientToken='string'
)
string
The user ID associated with this payment instrument.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns this payment instrument.
string
[REQUIRED]
The ID of the payment connector to use for this instrument.
string
[REQUIRED]
The type of payment instrument being created.
dict
[REQUIRED]
The details of the payment instrument.
embeddedCryptoWallet (dict) --
Embedded crypto wallet managed directly by end user
network (string) -- [REQUIRED]
The blockchain network for this embedded crypto wallet. Supported networks: ETHEREUM, SOLANA
linkedAccounts (list) -- [REQUIRED]
List of linkedAccounts linked to this wallet. Each linkedAccount represents a way the end user can authenticate to this wallet. Can be empty when adding a new linkedAccount to an existing wallet.
(dict) --
Represents different linkedAccounts that can be linked to an embedded wallet. This union supports multiple linkedAccount approaches: email, SMS, JWT, and OAuth2.
email (dict) --
Email-based linkedAccount
emailAddress (string) -- [REQUIRED]
The email address used for linkedAccount. Must be a valid email format.
sms (dict) --
SMS-based linkedAccount using phone number
phoneNumber (string) -- [REQUIRED]
The phone number in E.164 format (e.g., +1234567890). Must be a valid E.164 formatted phone number starting with + and containing 1-15 digits.
developerJwt (dict) --
Developer JWT linkedAccount with key ID and subject
kid (string) -- [REQUIRED]
The key ID (kid) from the JWT header. Identifies which key was used to sign the JWT.
sub (string) -- [REQUIRED]
The subject (sub) claim from the JWT payload. Identifies the principal that is the subject of the JWT.
oAuth2 (dict) --
OAuth2 provider linkedAccount (Google, Apple, X, Telegram, GitHub)
google (dict) --
Google OAuth2 authentication
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
apple (dict) --
Apple OAuth2 authentication
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
x (dict) --
X (formerly Twitter) OAuth2 authentication
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
telegram (dict) --
Telegram OAuth2 authentication
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
github (dict) --
GitHub OAuth2 authentication
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
walletAddress (string) --
The wallet address on the specified blockchain network.
redirectUrl (string) --
URL for the end user to complete a provider-specific action (e.g., wallet linking, onboarding). Returned by the payment connector during instrument creation.
string
Idempotency token to ensure request uniqueness.
This field is autopopulated if not provided.
dict
Response Syntax
{
'paymentInstrument': {
'paymentInstrumentId': 'string',
'paymentManagerArn': 'string',
'paymentConnectorId': 'string',
'userId': 'string',
'paymentInstrumentType': 'EMBEDDED_CRYPTO_WALLET',
'paymentInstrumentDetails': {
'embeddedCryptoWallet': {
'network': 'ETHEREUM'|'SOLANA',
'linkedAccounts': [
{
'email': {
'emailAddress': 'string'
},
'sms': {
'phoneNumber': 'string'
},
'developerJwt': {
'kid': 'string',
'sub': 'string'
},
'oAuth2': {
'google': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'apple': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'x': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'telegram': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'github': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
}
}
},
],
'walletAddress': 'string',
'redirectUrl': 'string'
}
},
'createdAt': datetime(2015, 1, 1),
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED',
'updatedAt': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Response structure for creating a payment instrument
paymentInstrument (dict) --
Represents a payment instrument
paymentInstrumentId (string) --
The unique identifier for this payment instrument.
paymentManagerArn (string) --
The ARN of the payment manager that owns this payment instrument.
paymentConnectorId (string) --
The ID of the payment connector associated with this instrument.
userId (string) --
The user ID associated with this payment instrument.
paymentInstrumentType (string) --
The type of payment instrument (e.g., EMBEDDED_CRYPTO_WALLET).
paymentInstrumentDetails (dict) --
The details specific to the payment instrument type.
embeddedCryptoWallet (dict) --
Embedded crypto wallet managed directly by end user
network (string) --
The blockchain network for this embedded crypto wallet. Supported networks: ETHEREUM, SOLANA
linkedAccounts (list) --
List of linkedAccounts linked to this wallet. Each linkedAccount represents a way the end user can authenticate to this wallet. Can be empty when adding a new linkedAccount to an existing wallet.
(dict) --
Represents different linkedAccounts that can be linked to an embedded wallet. This union supports multiple linkedAccount approaches: email, SMS, JWT, and OAuth2.
email (dict) --
Email-based linkedAccount
emailAddress (string) --
The email address used for linkedAccount. Must be a valid email format.
sms (dict) --
SMS-based linkedAccount using phone number
phoneNumber (string) --
The phone number in E.164 format (e.g., +1234567890). Must be a valid E.164 formatted phone number starting with + and containing 1-15 digits.
developerJwt (dict) --
Developer JWT linkedAccount with key ID and subject
kid (string) --
The key ID (kid) from the JWT header. Identifies which key was used to sign the JWT.
sub (string) --
The subject (sub) claim from the JWT payload. Identifies the principal that is the subject of the JWT.
oAuth2 (dict) --
OAuth2 provider linkedAccount (Google, Apple, X, Telegram, GitHub)
google (dict) --
Google OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
apple (dict) --
Apple OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
x (dict) --
X (formerly Twitter) OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
telegram (dict) --
Telegram OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
github (dict) --
GitHub OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
walletAddress (string) --
The wallet address on the specified blockchain network.
redirectUrl (string) --
URL for the end user to complete a provider-specific action (e.g., wallet linking, onboarding). Returned by the payment connector during instrument creation.
createdAt (datetime) --
The timestamp when this payment instrument was created.
status (string) --
The current status of this payment instrument.
updatedAt (datetime) --
The timestamp when this payment instrument was last updated.
Get a payment instrument by ID
See also: AWS API Documentation
Request Syntax
client.get_payment_instrument(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentConnectorId='string',
paymentInstrumentId='string'
)
string
The user ID associated with this payment instrument.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns this payment instrument.
string
The ID of the payment connector.
string
[REQUIRED]
The ID of the payment instrument to retrieve.
dict
Response Syntax
{
'paymentInstrument': {
'paymentInstrumentId': 'string',
'paymentManagerArn': 'string',
'paymentConnectorId': 'string',
'userId': 'string',
'paymentInstrumentType': 'EMBEDDED_CRYPTO_WALLET',
'paymentInstrumentDetails': {
'embeddedCryptoWallet': {
'network': 'ETHEREUM'|'SOLANA',
'linkedAccounts': [
{
'email': {
'emailAddress': 'string'
},
'sms': {
'phoneNumber': 'string'
},
'developerJwt': {
'kid': 'string',
'sub': 'string'
},
'oAuth2': {
'google': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'apple': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'x': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'telegram': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'github': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
}
}
},
],
'walletAddress': 'string',
'redirectUrl': 'string'
}
},
'createdAt': datetime(2015, 1, 1),
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED',
'updatedAt': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Response structure for getting a payment instrument
paymentInstrument (dict) --
Represents a payment instrument
paymentInstrumentId (string) --
The unique identifier for this payment instrument.
paymentManagerArn (string) --
The ARN of the payment manager that owns this payment instrument.
paymentConnectorId (string) --
The ID of the payment connector associated with this instrument.
userId (string) --
The user ID associated with this payment instrument.
paymentInstrumentType (string) --
The type of payment instrument (e.g., EMBEDDED_CRYPTO_WALLET).
paymentInstrumentDetails (dict) --
The details specific to the payment instrument type.
embeddedCryptoWallet (dict) --
Embedded crypto wallet managed directly by end user
network (string) --
The blockchain network for this embedded crypto wallet. Supported networks: ETHEREUM, SOLANA
linkedAccounts (list) --
List of linkedAccounts linked to this wallet. Each linkedAccount represents a way the end user can authenticate to this wallet. Can be empty when adding a new linkedAccount to an existing wallet.
(dict) --
Represents different linkedAccounts that can be linked to an embedded wallet. This union supports multiple linkedAccount approaches: email, SMS, JWT, and OAuth2.
email (dict) --
Email-based linkedAccount
emailAddress (string) --
The email address used for linkedAccount. Must be a valid email format.
sms (dict) --
SMS-based linkedAccount using phone number
phoneNumber (string) --
The phone number in E.164 format (e.g., +1234567890). Must be a valid E.164 formatted phone number starting with + and containing 1-15 digits.
developerJwt (dict) --
Developer JWT linkedAccount with key ID and subject
kid (string) --
The key ID (kid) from the JWT header. Identifies which key was used to sign the JWT.
sub (string) --
The subject (sub) claim from the JWT payload. Identifies the principal that is the subject of the JWT.
oAuth2 (dict) --
OAuth2 provider linkedAccount (Google, Apple, X, Telegram, GitHub)
google (dict) --
Google OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
apple (dict) --
Apple OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
x (dict) --
X (formerly Twitter) OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
telegram (dict) --
Telegram OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
github (dict) --
GitHub OAuth2 authentication
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider (optional).
name (string) --
The user's name from the OAuth2 provider (optional).
username (string) --
The username from the OAuth2 provider (optional).
walletAddress (string) --
The wallet address on the specified blockchain network.
redirectUrl (string) --
URL for the end user to complete a provider-specific action (e.g., wallet linking, onboarding). Returned by the payment connector during instrument creation.
createdAt (datetime) --
The timestamp when this payment instrument was created.
status (string) --
The current status of this payment instrument.
updatedAt (datetime) --
The timestamp when this payment instrument was last updated.
Get a payment session
See also: AWS API Documentation
Request Syntax
client.get_payment_session(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentSessionId='string'
)
string
The user ID associated with this payment session.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns this session.
string
[REQUIRED]
The ID of the payment session to retrieve.
dict
Response Syntax
{
'paymentSession': {
'paymentSessionId': 'string',
'paymentManagerArn': 'string',
'limits': {
'maxSpendAmount': {
'value': 'string',
'currency': 'USD'
}
},
'userId': 'string',
'expiryTimeInMinutes': 123,
'createdAt': datetime(2015, 1, 1),
'availableLimits': {
'availableSpendAmount': {
'value': 'string',
'currency': 'USD'
},
'updatedAt': datetime(2015, 1, 1)
},
'updatedAt': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Response structure for getting a payment session
paymentSession (dict) --
Payment manager session
paymentSessionId (string) --
The unique identifier for this payment session.
paymentManagerArn (string) --
The ARN of the payment manager that owns this session.
limits (dict) --
The spending limits for this session.
maxSpendAmount (dict) --
The maximum amount that can be spent in this session.
value (string) --
The numeric value of the amount.
currency (string) --
The currency code for this amount.
userId (string) --
The user ID associated with this payment session.
expiryTimeInMinutes (integer) --
The session expiry time in minutes.
createdAt (datetime) --
The timestamp when this payment session was created.
availableLimits (dict) --
The available limits for this session after accounting for processed payments.
availableSpendAmount (dict) --
The available spend amount for this session.
value (string) --
The numeric value of the amount.
currency (string) --
The currency code for this amount.
updatedAt (datetime) --
The timestamp when the available limits were last updated.
updatedAt (datetime) --
The timestamp when this payment session was last updated.
Delete a payment manager session
Permanently removes a payment session record from the database. This is a hard delete operation that removes the session completely.
Deleting a non-existent or already-deleted session returns ResourceNotFoundException (404).
Authorization: The caller must own the session (accountId, userId, and paymentManagerId must match). If authorization fails, a 403 Forbidden error is returned.
Errors:
ResourceNotFoundException: The session does not exist or has already been deleted
AccessDeniedException: The caller is not authorized to delete this session
ValidationException: Required fields are missing or invalid
InternalServerException: An unexpected server error occurred
See also: AWS API Documentation
Request Syntax
client.delete_payment_session(
userId='string',
paymentManagerArn='string',
paymentSessionId='string'
)
string
The user ID making the delete request. Must match the session's userId.
string
[REQUIRED]
The payment manager ARN. Must match the session's paymentManagerArn.
string
[REQUIRED]
The payment session ID to delete.
dict
Response Syntax
{
'status': 'ACTIVE'|'EXPIRED'|'DELETED'
}
Response Structure
(dict) --
Response structure for deleting a payment session
Returns the deletion status with HTTP 200 status code on successful deletion.
status (string) --
The status of the deletion. Always DELETED for successful hard delete.
{'tools': {'config': {'agentCoreGateway': {'outboundAuth': {'oauth': {'grantType': {'TOKEN_EXCHANGE'}}}}}}}
Operation to invoke a Harness.
See also: AWS API Documentation
Request Syntax
client.invoke_harness(
harnessArn='string',
runtimeSessionId='string',
messages=[
{
'role': 'user'|'assistant',
'content': [
{
'text': 'string',
'toolUse': {
'name': 'string',
'toolUseId': 'string',
'input': {...}|[...]|123|123.4|'string'|True|None,
'type': 'tool_use'|'server_tool_use'|'mcp_tool_use',
'serverName': 'string'
},
'toolResult': {
'toolUseId': 'string',
'content': [
{
'text': 'string',
'json': {...}|[...]|123|123.4|'string'|True|None
},
],
'status': 'success'|'error',
'type': 'tool_use'|'server_tool_use'|'mcp_tool_use'
},
'reasoningContent': {
'reasoningText': {
'text': 'string',
'signature': 'string'
},
'redactedContent': b'bytes'
}
},
]
},
],
model={
'bedrockModelConfig': {
'modelId': 'string',
'maxTokens': 123,
'temperature': ...,
'topP': ...
},
'openAiModelConfig': {
'modelId': 'string',
'apiKeyArn': 'string',
'maxTokens': 123,
'temperature': ...,
'topP': ...
},
'geminiModelConfig': {
'modelId': 'string',
'apiKeyArn': 'string',
'maxTokens': 123,
'temperature': ...,
'topP': ...,
'topK': 123
}
},
systemPrompt=[
{
'text': 'string'
},
],
tools=[
{
'type': 'remote_mcp'|'agentcore_browser'|'agentcore_gateway'|'inline_function'|'agentcore_code_interpreter',
'name': 'string',
'config': {
'remoteMcp': {
'url': 'string',
'headers': {
'string': 'string'
}
},
'agentCoreBrowser': {
'browserArn': 'string'
},
'agentCoreGateway': {
'gatewayArn': 'string',
'outboundAuth': {
'awsIam': {}
,
'none': {}
,
'oauth': {
'providerArn': 'string',
'scopes': [
'string',
],
'customParameters': {
'string': 'string'
},
'grantType': 'CLIENT_CREDENTIALS'|'AUTHORIZATION_CODE'|'TOKEN_EXCHANGE',
'defaultReturnUrl': 'string'
}
}
},
'inlineFunction': {
'description': 'string',
'inputSchema': {...}|[...]|123|123.4|'string'|True|None
},
'agentCoreCodeInterpreter': {
'codeInterpreterArn': 'string'
}
}
},
],
skills=[
{
'path': 'string'
},
],
allowedTools=[
'string',
],
maxIterations=123,
maxTokens=123,
timeoutSeconds=123,
actorId='string'
)
string
[REQUIRED]
The ARN of the harness to invoke.
string
[REQUIRED]
The session ID for the invocation. Use the same session ID across requests to continue a conversation.
list
[REQUIRED]
The messages to send to the agent.
(dict) --
A message in the conversation.
role (string) -- [REQUIRED]
The role of the message sender.
content (list) -- [REQUIRED]
The content blocks of the message.
(dict) --
A content block within a message.
text (string) --
Text content.
toolUse (dict) --
A tool use request from the model.
name (string) -- [REQUIRED]
The name of the tool to call.
toolUseId (string) -- [REQUIRED]
The unique ID of this tool use.
input (:ref:`document<document>`) -- [REQUIRED]
The JSON input to pass to the tool.
type (string) --
The type of tool use.
serverName (string) --
The name of the MCP server providing this tool.
toolResult (dict) --
A tool execution result.
toolUseId (string) -- [REQUIRED]
The tool use ID that this result corresponds to.
content (list) -- [REQUIRED]
The content of the tool result.
(dict) --
A content block within a tool result.
text (string) --
Text content.
json (:ref:`document<document>`) --
JSON content.
status (string) --
The status of the tool execution.
type (string) --
The type of tool use that produced this result.
reasoningContent (dict) --
Model reasoning content.
reasoningText (dict) --
The reasoning text.
text (string) -- [REQUIRED]
The reasoning text.
signature (string) --
Signature for verifying the reasoning content.
redactedContent (bytes) --
Redacted reasoning content.
dict
The model configuration to use for this invocation. If specified, overrides the harness default.
bedrockModelConfig (dict) --
Configuration for an Amazon Bedrock model.
modelId (string) -- [REQUIRED]
The Bedrock model ID.
maxTokens (integer) --
The maximum number of tokens to allow in the generated response per iteration.
temperature (float) --
The temperature to set when calling the model.
topP (float) --
The topP set when calling the model.
openAiModelConfig (dict) --
Configuration for an OpenAI model.
modelId (string) -- [REQUIRED]
The OpenAI model ID.
apiKeyArn (string) -- [REQUIRED]
The ARN of your OpenAI API key on AgentCore Identity.
maxTokens (integer) --
The maximum number of tokens to allow in the generated response per iteration.
temperature (float) --
The temperature to set when calling the model.
topP (float) --
The topP set when calling the model.
geminiModelConfig (dict) --
Configuration for a Google Gemini model.
modelId (string) -- [REQUIRED]
The Gemini model ID.
apiKeyArn (string) -- [REQUIRED]
The ARN of your Gemini API key on AgentCore Identity.
maxTokens (integer) --
The maximum number of tokens to allow in the generated response per iteration.
temperature (float) --
The temperature to set when calling the model.
topP (float) --
The topP set when calling the model.
topK (integer) --
The topK set when calling the model.
list
The system prompt to use for this invocation. If specified, overrides the harness default.
(dict) --
A content block in the system prompt.
text (string) --
The text content of the system prompt block.
list
The tools available to the agent for this invocation. If specified, overrides the harness default.
(dict) --
A tool available to the agent loop.
type (string) -- [REQUIRED]
The type of tool.
name (string) --
Unique name for the tool. If not provided, a name will be inferred or generated.
config (dict) --
Tool-specific configuration.
remoteMcp (dict) --
Configuration for remote MCP server.
url (string) -- [REQUIRED]
URL of the MCP endpoint.
headers (dict) --
Custom headers to include when connecting to the remote MCP server.
(string) --
The key of an HTTP header.
(string) --
The value of an HTTP header.
agentCoreBrowser (dict) --
Configuration for AgentCore Browser.
browserArn (string) --
If not populated, the built-in Browser ARN is used.
agentCoreGateway (dict) --
Configuration for AgentCore Gateway.
gatewayArn (string) -- [REQUIRED]
The ARN of the desired AgentCore Gateway.
outboundAuth (dict) --
How harness authenticates to this Gateway. Defaults to AWS_IAM (SigV4) if omitted.
awsIam (dict) --
SigV4-sign requests using the agent's execution role.
none (dict) --
No authentication.
oauth (dict) --
OAuth 2.0 authentication via AgentCore Identity.
providerArn (string) -- [REQUIRED]
The ARN of the OAuth 2.0 credential provider in AgentCore Identity.
scopes (list) -- [REQUIRED]
The OAuth 2.0 scopes to request when obtaining an access token.
(string) --
customParameters (dict) --
Additional custom parameters to include in the OAuth 2.0 token request.
(string) --
(string) --
grantType (string) --
The OAuth 2.0 grant type to use for authentication.
defaultReturnUrl (string) --
The default return URL for the OAuth 2.0 authorization flow.
inlineFunction (dict) --
Configuration for an inline function tool.
description (string) -- [REQUIRED]
Description of what the tool does, provided to the model.
inputSchema (:ref:`document<document>`) -- [REQUIRED]
JSON Schema describing the tool's input parameters.
agentCoreCodeInterpreter (dict) --
Configuration for AgentCore Code Interpreter.
codeInterpreterArn (string) --
If not populated, the built-in Code Interpreter ARN is used.
list
The skills available to the agent for this invocation. If specified, overrides the harness default.
(dict) --
A skill available to the agent.
path (string) --
The filesystem path to the skill definition.
list
The tools that the agent is allowed to use for this invocation. If specified, overrides the harness default.
(string) --
integer
The maximum number of iterations the agent loop can execute. If specified, overrides the harness default.
integer
The maximum number of tokens the agent can generate per iteration. If specified, overrides the harness default.
integer
The maximum duration in seconds for the agent loop execution. If specified, overrides the harness default.
string
The actor ID for memory operations. Overrides the actor ID configured on the harness.
dict
The response of this operation contains an :class:`.EventStream` member. When iterated the :class:`.EventStream` will yield events based on the structure below, where only one of the top level keys will be present for any given event.
Response Syntax
{
'stream': EventStream({
'messageStart': {
'role': 'user'|'assistant'
},
'contentBlockStart': {
'contentBlockIndex': 123,
'start': {
'toolUse': {
'toolUseId': 'string',
'name': 'string',
'type': 'tool_use'|'server_tool_use'|'mcp_tool_use',
'serverName': 'string'
},
'toolResult': {
'toolUseId': 'string',
'status': 'success'|'error'
}
}
},
'contentBlockDelta': {
'contentBlockIndex': 123,
'delta': {
'text': 'string',
'toolUse': {
'input': 'string'
},
'toolResult': [
{
'text': 'string',
'json': {...}|[...]|123|123.4|'string'|True|None
},
],
'reasoningContent': {
'text': 'string',
'redactedContent': b'bytes',
'signature': 'string'
}
}
},
'contentBlockStop': {
'contentBlockIndex': 123
},
'messageStop': {
'stopReason': 'end_turn'|'tool_use'|'tool_result'|'max_tokens'|'stop_sequence'|'content_filtered'|'malformed_model_output'|'malformed_tool_use'|'interrupted'|'partial_turn'|'model_context_window_exceeded'|'max_iterations_exceeded'|'max_output_tokens_exceeded'|'timeout_exceeded'
},
'metadata': {
'usage': {
'inputTokens': 123,
'outputTokens': 123,
'totalTokens': 123,
'cacheReadInputTokens': 123,
'cacheWriteInputTokens': 123
},
'metrics': {
'latencyMs': 123
}
},
'internalServerException': {
'message': 'string'
},
'validationException': {
'message': 'string',
'reason': 'CannotParse'|'FieldValidationFailed'|'IdempotentParameterMismatchException'|'EventInOtherSession'|'ResourceConflict',
'fieldList': [
{
'name': 'string',
'message': 'string'
},
]
},
'runtimeClientError': {
'message': 'string'
}
})
}
Response Structure
(dict) --
stream (:class:`.EventStream`) --
The streaming output from the harness invocation.
messageStart (dict) --
Indicates the start of a new message from the agent.
role (string) --
The role of the message sender.
contentBlockStart (dict) --
Indicates the start of a new content block.
contentBlockIndex (integer) --
The index of the content block within the message.
start (dict) --
The content block start payload.
toolUse (dict) --
Start of a tool use content block.
toolUseId (string) --
The unique ID of this tool use.
name (string) --
The name of the tool being called.
type (string) --
The type of tool use.
serverName (string) --
The name of the MCP server providing this tool.
toolResult (dict) --
Start of a tool result content block.
toolUseId (string) --
The tool use ID that this result corresponds to.
status (string) --
The status of the tool execution.
contentBlockDelta (dict) --
A delta update to the current content block.
contentBlockIndex (integer) --
The index of the content block being updated.
delta (dict) --
The delta payload.
text (string) --
A text delta.
toolUse (dict) --
A tool use input delta.
input (string) --
The partial JSON input for the tool call.
toolResult (list) --
A tool result delta.
(dict) --
A delta update to a tool result content block.
text (string) --
A text tool result delta.
json (:ref:`document<document>`) --
A JSON tool result delta.
reasoningContent (dict) --
A reasoning content delta.
text (string) --
Reasoning text delta.
redactedContent (bytes) --
Redacted reasoning content.
signature (string) --
Signature for the reasoning content.
contentBlockStop (dict) --
Indicates the end of the current content block.
contentBlockIndex (integer) --
The index of the content block that ended.
messageStop (dict) --
Indicates the end of the current message.
stopReason (string) --
The reason the agent stopped generating.
metadata (dict) --
Token usage and latency metrics for the invocation.
usage (dict) --
Token usage counts.
inputTokens (integer) --
The number of input tokens consumed.
outputTokens (integer) --
The number of output tokens generated.
totalTokens (integer) --
The total number of tokens consumed.
cacheReadInputTokens (integer) --
The number of input tokens read from cache.
cacheWriteInputTokens (integer) --
The number of input tokens written to cache.
metrics (dict) --
Latency metrics.
latencyMs (integer) --
The end-to-end latency of the invocation in milliseconds.
internalServerException (dict) --
The exception that occurs when the service encounters an unexpected internal error. This is a temporary condition that will resolve itself with retries. We recommend implementing exponential backoff retry logic in your application.
message (string) --
validationException (dict) --
The exception that occurs when the input fails to satisfy the constraints specified by the service. Check the error message for details about which input parameter is invalid and correct your request.
message (string) --
reason (string) --
fieldList (list) --
(dict) --
Stores information about a field passed inside a request that resulted in an exception.
name (string) --
The name of the field.
message (string) --
A message describing why this field failed validation.
runtimeClientError (dict) --
The exception that occurs when there is an error in the runtime client. This can happen due to network issues, invalid configuration, or other client-side problems. Check the error message for specific details about the error.
message (string) --