Skip to content

Commit 122e7c3

Browse files
aidandaly24aidandaly24
committed
feat(payments): add AgentCore Payments as first-class CLI resource
Adds AgentCore Payments as a first-class resource type in the CLI: - `agentcore add/remove payment-manager` and `payment-connector` (CoinbaseCDP + StripePrivy), CLI + TUI wizard - Cascading delete of connectors + credentials + .env.local cleanup - CDK-backed deploy via AgentCorePaymentManager / AgentCorePaymentConnector L3 constructs, including runtime-role payment data-plane IAM grants - Payment credential provider setup (imperative, AgentCore Identity vault) - CFN output parsing into deployed-state - Invoke flags: --payment-instrument-id, --payment-session-id, --auto-session - Strands template wires AgentCorePaymentsPlugin; PAYMENT_SYSTEM_PROMPT references the plugin-provided http_request tool Schema: - payments[] in agentcore.json, .optional() (non-breaking: absent configs are not rewritten with payments: []) - payment manager name regex matches CreatePaymentManager API (no underscore); connector names allow underscores per CreatePaymentConnector - getOrCreatePaymentSession unwraps the CreatePaymentSession `paymentSession` response so --auto-session forwards a real session id Verified end-to-end on Base Sepolia: real on-chain USDC settle via the SDK plugin (bedrock-agentcore >= 1.12.0 / PR #493).
1 parent f0bc9de commit 122e7c3

105 files changed

Lines changed: 11196 additions & 126 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -32,9 +32,9 @@ These options are available on all commands:
3232

3333
- `create` - Create new AgentCore project
3434
- `add` - Add resources (agent, memory, credential, evaluator, online-eval, gateway, gateway-target, policy-engine,
35-
policy)
35+
policy, payment-manager, payment-connector)
3636
- `remove` - Remove resources (agent, memory, credential, evaluator, online-eval, gateway, gateway-target,
37-
policy-engine, policy, all)
37+
policy-engine, policy, payment-manager, payment-connector, all)
3838
- `deploy` - Deploy infrastructure to AWS
3939
- `status` - Check deployment status
4040
- `dev` - Local development server (CodeZip: uvicorn with hot-reload; Container: Docker build + run with volume mount)
@@ -88,6 +88,8 @@ Current primitives:
8888
- `GatewayTargetPrimitive` — gateway target creation/removal with code generation
8989
- `PolicyEnginePrimitive` — Cedar policy engine creation/removal
9090
- `PolicyPrimitive` — Cedar policy creation/removal within policy engines
91+
- `PaymentManagerPrimitive` — payment manager creation/removal with agent code wiring
92+
- `PaymentConnectorPrimitive` — payment connector creation/removal with credential management
9193

9294
Singletons are created in `registry.ts` and wired into CLI commands via `cli.ts`. See `src/cli/AGENTS.md` for details on
9395
adding new primitives.

‎docs/commands.md‎

Lines changed: 117 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -140,14 +140,14 @@ agentcore status --runtime-id abc123
140140
agentcore status --json
141141
```
142142

143-
| Flag | Description |
144-
| ------------------- | -------------------------------------------------------------------------------------------------------------------------- |
145-
| `--runtime-id <id>` | Look up a specific runtime by ID |
146-
| `--target <name>` | Select deployment target |
147-
| `--type <type>` | Filter by resource type: `agent`, `memory`, `credential`, `gateway`, `evaluator`, `online-eval`, `policy-engine`, `policy` |
148-
| `--state <state>` | Filter by deployment state: `deployed`, `local-only`, `pending-removal` |
149-
| `--runtime <name>` | Filter to a specific runtime |
150-
| `--json` | JSON output |
143+
| Flag | Description |
144+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
145+
| `--runtime-id <id>` | Look up a specific runtime by ID |
146+
| `--target <name>` | Select deployment target |
147+
| `--type <type>` | Filter by resource type: `agent`, `memory`, `credential`, `gateway`, `evaluator`, `online-eval`, `payment`, `policy-engine`, `policy` |
148+
| `--state <state>` | Filter by deployment state: `deployed`, `local-only`, `pending-removal` |
149+
| `--runtime <name>` | Filter to a specific runtime |
150+
| `--json` | JSON output |
151151

152152
### validate
153153

@@ -473,6 +473,85 @@ agentcore add gateway-target \
473473
> `open-api-schema` requires `--outbound-auth` (`oauth` or `api-key`). `api-gateway` supports `api-key` or `none`.
474474
> `mcp-server` supports `oauth` or `none`.
475475
476+
### add payment-manager
477+
478+
Add a payment manager to the project. See [Payments](payments.md) for full usage guide.
479+
480+
```bash
481+
# Minimal (defaults: AWS_IAM, interceptor, auto-payment enabled)
482+
agentcore add payment-manager --name MyManager
483+
484+
# With CUSTOM_JWT authorization
485+
agentcore add payment-manager \
486+
--name MyManager \
487+
--authorizer-type CUSTOM_JWT \
488+
--discovery-url https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/.well-known/openid-configuration \
489+
--allowed-clients "client-id-1,client-id-2"
490+
491+
# With advanced options
492+
agentcore add payment-manager \
493+
--name MyManager \
494+
--auto-payment true \
495+
--default-spend-limit 25.00 \
496+
--tool-allowlist "web_search,fetch_url" \
497+
--network-preferences "eip155:84532"
498+
```
499+
500+
| Flag | Description |
501+
| ---------------------------------- | ----------------------------------------------------- |
502+
| `--name <name>` | Manager name (required in non-interactive mode) |
503+
| `--authorizer-type <type>` | `AWS_IAM` (default) or `CUSTOM_JWT` |
504+
| `--discovery-url <url>` | OIDC discovery URL (required for CUSTOM_JWT) |
505+
| `--allowed-clients <clients>` | Comma-separated client IDs (CUSTOM_JWT only) |
506+
| `--allowed-audience <audience>` | Comma-separated allowed audiences (CUSTOM_JWT only) |
507+
| `--allowed-scopes <scopes>` | Comma-separated allowed scopes (CUSTOM_JWT only) |
508+
| `--pattern <pattern>` | `interceptor` (default) or `tool-based` |
509+
| `--auto-payment [value]` | Enable automatic payment: `true` (default) or `false` |
510+
| `--default-spend-limit <amount>` | Default session spend limit in USD (default: `10.00`) |
511+
| `--tool-allowlist <tools>` | Comma-separated tool names eligible for payment |
512+
| `--network-preferences <networks>` | Comma-separated network IDs (e.g., `eip155:84532`) |
513+
| `--description <desc>` | Human-readable description |
514+
| `--json` | JSON output |
515+
516+
### add payment-connector
517+
518+
Add a payment connector to an existing payment manager. See [Payments](payments.md) for credential details.
519+
520+
```bash
521+
# CoinbaseCDP provider
522+
agentcore add payment-connector \
523+
--manager MyManager \
524+
--name MyCDPConnector \
525+
--provider CoinbaseCDP \
526+
--api-key-id your-api-key-id \
527+
--api-key-secret your-api-key-secret \
528+
--wallet-secret your-wallet-secret
529+
530+
# StripePrivy provider
531+
agentcore add payment-connector \
532+
--manager MyManager \
533+
--name MyStripeConnector \
534+
--provider StripePrivy \
535+
--app-id your-app-id \
536+
--app-secret your-app-secret \
537+
--authorization-private-key your-private-key \
538+
--authorization-id your-auth-id
539+
```
540+
541+
| Flag | Description |
542+
| ----------------------------------- | ------------------------------------------ |
543+
| `--manager <name>` | Parent payment manager (required) |
544+
| `--name <name>` | Connector name (required) |
545+
| `--provider <provider>` | `CoinbaseCDP` (default) or `StripePrivy` |
546+
| `--api-key-id <id>` | Coinbase CDP API Key ID |
547+
| `--api-key-secret <secret>` | Coinbase CDP API Key Secret |
548+
| `--wallet-secret <secret>` | Coinbase CDP Wallet Secret |
549+
| `--app-id <id>` | Privy App ID (StripePrivy) |
550+
| `--app-secret <secret>` | Privy App Secret (StripePrivy) |
551+
| `--authorization-private-key <key>` | ECDSA P-256 private key (StripePrivy) |
552+
| `--authorization-id <id>` | Authorization key identifier (StripePrivy) |
553+
| `--json` | JSON output |
554+
476555
### add credential
477556

478557
Add a credential to the project. Supports API key and OAuth credential types.
@@ -739,19 +818,22 @@ agentcore remove runtime-endpoint --name prod
739818
agentcore remove dataset --name MyDataset
740819
agentcore remove config-bundle --name MyBundle
741820
agentcore remove ab-test --name PromptComparison
821+
agentcore remove payment-manager --name MyManager -y
822+
agentcore remove payment-connector --name MyCDPConnector --manager MyManager -y
742823

743824
# Reset everything
744825
agentcore remove all -y
745826
agentcore remove all --dry-run # Preview
746827
```
747828

748-
| Flag | Description |
749-
| ------------------- | ------------------------------------------------- |
750-
| `--name <name>` | Resource name |
751-
| `--engine <engine>` | Policy engine name (required for `remove policy`) |
752-
| `-y, --yes` | Skip confirmation |
753-
| `--dry-run` | Preview (`remove all` only) |
754-
| `--json` | JSON output |
829+
| Flag | Description |
830+
| ------------------- | --------------------------------------------------------- |
831+
| `--name <name>` | Resource name |
832+
| `--engine <engine>` | Policy engine name (required for `remove policy`) |
833+
| `--manager <name>` | Parent payment manager (required for `payment-connector`) |
834+
| `-y, --yes` | Skip confirmation |
835+
| `--dry-run` | Preview (`remove all` only) |
836+
| `--json` | JSON output |
755837

756838
---
757839

@@ -815,23 +897,26 @@ agentcore invoke --exec "cat /etc/os-release" --json
815897
The prompt can come from four sources, resolved in this precedence order: `--prompt` > positional > `--prompt-file` >
816898
piped stdin. `--prompt-file` combined with piped stdin content returns a collision error — pick one.
817899

818-
| Flag | Description |
819-
| ---------------------- | ---------------------------------------------------------------- |
820-
| `[prompt]` | Prompt text (positional argument) |
821-
| `--prompt <text>` | Prompt text (flag, takes precedence over positional) |
822-
| `--prompt-file <path>` | Read the prompt from a file (useful for long / structured input) |
823-
| `--runtime <name>` | Specific runtime |
824-
| `--target <name>` | Deployment target |
825-
| `--session-id <id>` | Continue a specific session |
826-
| `--user-id <id>` | User ID for runtime invocation (default: `default-user`) |
827-
| `--stream` | Stream response in real-time |
828-
| `--tool <name>` | MCP tool name (use with `call-tool` prompt) |
829-
| `--input <json>` | MCP tool arguments as JSON (use with `--tool`) |
830-
| `-H, --header <h>` | Custom header (`"Name: Value"`, repeatable) |
831-
| `--bearer-token <t>` | Bearer token for CUSTOM_JWT auth |
832-
| `--exec` | Execute a shell command in the runtime container |
833-
| `--timeout <seconds>` | Timeout in seconds for `--exec` commands |
834-
| `--json` | JSON output |
900+
| Flag | Description |
901+
| ------------------------------ | ---------------------------------------------------------------- |
902+
| `[prompt]` | Prompt text (positional argument) |
903+
| `--prompt <text>` | Prompt text (flag, takes precedence over positional) |
904+
| `--prompt-file <path>` | Read the prompt from a file (useful for long / structured input) |
905+
| `--runtime <name>` | Specific runtime |
906+
| `--target <name>` | Deployment target |
907+
| `--session-id <id>` | Continue a specific session |
908+
| `--user-id <id>` | User ID for runtime invocation (default: `default-user`) |
909+
| `--stream` | Stream response in real-time |
910+
| `--tool <name>` | MCP tool name (use with `call-tool` prompt) |
911+
| `--input <json>` | MCP tool arguments as JSON (use with `--tool`) |
912+
| `-H, --header <h>` | Custom header (`"Name: Value"`, repeatable) |
913+
| `--bearer-token <t>` | Bearer token for CUSTOM_JWT auth |
914+
| `--payment-instrument-id <id>` | Payment instrument ID for x402 payments |
915+
| `--payment-session-id <id>` | Payment session ID for budget tracking |
916+
| `--auto-session` | Auto-create/reuse a payment session for testing |
917+
| `--exec` | Execute a shell command in the runtime container |
918+
| `--timeout <seconds>` | Timeout in seconds for `--exec` commands |
919+
| `--json` | JSON output |
835920

836921
Piped stdin is auto-detected: when no prompt is supplied and stdin is not a TTY, the prompt is read from stdin.
837922

‎docs/configuration.md‎

Lines changed: 98 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
3838
],
3939
"memories": [],
4040
"credentials": [],
41+
"payments": [],
4142
"evaluators": [],
4243
"onlineEvalConfigs": [],
4344
"agentCoreGateways": [],
@@ -57,6 +58,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
5758
| `credentials` | Yes | Array of credential providers (API key or OAuth) |
5859
| `evaluators` | Yes | Array of custom evaluator definitions |
5960
| `onlineEvalConfigs` | Yes | Array of online eval configurations |
61+
| `payments` | No | Array of payment manager configurations |
6062
| `policyEngines` | No | Array of policy engine configurations |
6163
| `agentCoreGateways` | No | Array of gateway definitions |
6264
| `mcpRuntimeTools` | No | Array of MCP runtime tool definitions |
@@ -482,6 +484,88 @@ implementations.
482484

483485
---
484486

487+
## Payment Manager Resource
488+
489+
Payment managers define how agents handle x402 microtransactions. Each manager has one or more connectors that provide
490+
wallet credentials. See [Payments](payments.md) for the full usage guide.
491+
492+
```json
493+
{
494+
"payments": [
495+
{
496+
"name": "MyManager",
497+
"authorizerType": "AWS_IAM",
498+
"pattern": "interceptor",
499+
"autoPayment": true,
500+
"defaultSpendLimit": "10.00",
501+
"paymentToolAllowlist": ["web_search", "fetch_url"],
502+
"networkPreferences": ["eip155:84532"],
503+
"description": "Production payment manager",
504+
"connectors": [
505+
{
506+
"name": "MyCDPConnector",
507+
"provider": "CoinbaseCDP",
508+
"credentialName": "my-cdp-creds"
509+
}
510+
]
511+
}
512+
]
513+
}
514+
```
515+
516+
### Payment Manager Fields
517+
518+
| Field | Required | Description |
519+
| ------------------------- | -------- | -------------------------------------------------------------------- |
520+
| `name` | Yes | Manager name (alphanumeric + underscore, max 48, starts with letter) |
521+
| `authorizerType` | No | `"AWS_IAM"` (default) or `"CUSTOM_JWT"` |
522+
| `authorizerConfiguration` | Cond. | Required when `authorizerType` is `"CUSTOM_JWT"` (see below) |
523+
| `pattern` | No | `"interceptor"` (default) or `"tool-based"` |
524+
| `connectors` | Yes | Array of payment connector objects |
525+
| `autoPayment` | No | Enable automatic payment (default: `true`) |
526+
| `defaultSpendLimit` | No | Default session budget in USD (e.g., `"10.00"`) |
527+
| `paymentToolAllowlist` | No | Array of tool names eligible for payment |
528+
| `networkPreferences` | No | Array of network identifiers (e.g., `"eip155:84532"`) |
529+
| `description` | No | Human-readable description |
530+
531+
### Authorizer Configuration (CUSTOM_JWT)
532+
533+
```json
534+
{
535+
"authorizerConfiguration": {
536+
"customJWTAuthorizer": {
537+
"discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/.well-known/openid-configuration",
538+
"allowedClients": ["client-id-1"],
539+
"allowedAudience": ["https://api.example.com"],
540+
"allowedScopes": ["payments:read", "payments:write"]
541+
}
542+
}
543+
}
544+
```
545+
546+
| Field | Required | Description |
547+
| ----------------- | -------- | --------------------------- |
548+
| `discoveryUrl` | Yes | OIDC discovery URL |
549+
| `allowedClients` | No | Array of allowed client IDs |
550+
| `allowedAudience` | No | Array of allowed audiences |
551+
| `allowedScopes` | No | Array of allowed scopes |
552+
553+
### Payment Connector
554+
555+
| Field | Required | Description |
556+
| ---------------- | -------- | -------------------------------------------------- |
557+
| `name` | Yes | Connector name (alphanumeric + underscore, max 48) |
558+
| `provider` | No | `"CoinbaseCDP"` (default) or `"StripePrivy"` |
559+
| `credentialName` | Yes | Name of the credential (maps to `.env.local` vars) |
560+
561+
### Payment Credential Provider
562+
563+
Payment connectors use a `PaymentCredentialProvider` credential type, distinct from `ApiKeyCredentialProvider` and
564+
`OAuthCredentialProvider`. The credential is automatically created during `agentcore deploy` from values in
565+
`.env.local`. You do not need to add it to the `credentials` array manually.
566+
567+
---
568+
485569
## aws-targets.json
486570

487571
Deployment target
@@ -524,6 +608,19 @@ AGENTCORE_CREDENTIAL_{projectName}GEMINI=...
524608
# OAuth credentials
525609
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_ID=my-client-id
526610
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_SECRET=my-client-secret
611+
612+
# Payment credentials - CoinbaseCDP (3 variables per connector)
613+
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_ID=your-api-key-id
614+
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_SECRET=your-api-key-secret
615+
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_WALLET_SECRET=your-wallet-secret
616+
617+
# Payment credentials - StripePrivy (4 variables per connector)
618+
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_ID=your-app-id
619+
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_SECRET=your-app-secret
620+
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_PRIVATE_KEY=your-private-key
621+
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_ID=your-auth-id
527622
```
528623

529-
Environment variable names should match the credential names in your configuration.
624+
Environment variable names should match the credential names in your configuration. For payment credentials,
625+
`{CREDENTIAL_NAME}` is the connector's `credentialName` uppercased with hyphens replaced by underscores (e.g.,
626+
`my-cdp-creds` becomes `MY_CDP_CREDS`). See [Payments](payments.md#credential-storage) for details.

0 commit comments

Comments
 (0)