Skip to content

feat(payments): add AgentCore Payments as first-class CLI resource #1261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aidandaly24 wants to merge 3 commits into
base: main
Choose a base branch
from
+11,241 −118
Open

feat(payments): add AgentCore Payments as first-class CLI resource #1261

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
fbee47b
feat(payments): add AgentCore Payments as first-class CLI resource
aidandaly24 Jun 2, 2026
5e9dd0d
fix(payments): route vended CDK spec access through specAny
aidandaly24 Jun 2, 2026
ab9408e
Merge remote-tracking branch 'origin/main' into feat/payments
aidandaly24 Jun 2, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,9 @@ These options are available on all commands:

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

Singletons are created in `registry.ts` and wired into CLI commands via `cli.ts`. See `src/cli/AGENTS.md` for details on
adding new primitives.
Expand Down
149 changes: 117 additions & 32 deletions docs/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,14 +140,14 @@ agentcore status --runtime-id abc123
agentcore status --json
```

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

### validate

Expand Down Expand Up @@ -473,6 +473,85 @@ agentcore add gateway-target \
> `open-api-schema` requires `--outbound-auth` (`oauth` or `api-key`). `api-gateway` supports `api-key` or `none`.
> `mcp-server` supports `oauth` or `none`.

### add payment-manager

Add a payment manager to the project. See [Payments](payments.md) for full usage guide.

```bash
# Minimal (defaults: AWS_IAM, interceptor, auto-payment enabled)
agentcore add payment-manager --name MyManager

# With CUSTOM_JWT authorization
agentcore add payment-manager \
--name MyManager \
--authorizer-type CUSTOM_JWT \
--discovery-url https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/.well-known/openid-configuration \
--allowed-clients "client-id-1,client-id-2"

# With advanced options
agentcore add payment-manager \
--name MyManager \
--auto-payment true \
--default-spend-limit 25.00 \
--tool-allowlist "web_search,fetch_url" \
--network-preferences "eip155:84532"
```

| Flag | Description |
| ---------------------------------- | ----------------------------------------------------- |
| `--name <name>` | Manager name (required in non-interactive mode) |
| `--authorizer-type <type>` | `AWS_IAM` (default) or `CUSTOM_JWT` |
| `--discovery-url <url>` | OIDC discovery URL (required for CUSTOM_JWT) |
| `--allowed-clients <clients>` | Comma-separated client IDs (CUSTOM_JWT only) |
| `--allowed-audience <audience>` | Comma-separated allowed audiences (CUSTOM_JWT only) |
| `--allowed-scopes <scopes>` | Comma-separated allowed scopes (CUSTOM_JWT only) |
| `--pattern <pattern>` | `interceptor` (default) or `tool-based` |
| `--auto-payment [value]` | Enable automatic payment: `true` (default) or `false` |
| `--default-spend-limit <amount>` | Default session spend limit in USD (default: `10.00`) |
| `--tool-allowlist <tools>` | Comma-separated tool names eligible for payment |
| `--network-preferences <networks>` | Comma-separated network IDs (e.g., `eip155:84532`) |
| `--description <desc>` | Human-readable description |
| `--json` | JSON output |

### add payment-connector

Add a payment connector to an existing payment manager. See [Payments](payments.md) for credential details.

```bash
# CoinbaseCDP provider
agentcore add payment-connector \
--manager MyManager \
--name MyCDPConnector \
--provider CoinbaseCDP \
--api-key-id your-api-key-id \
--api-key-secret your-api-key-secret \
--wallet-secret your-wallet-secret

# StripePrivy provider
agentcore add payment-connector \
--manager MyManager \
--name MyStripeConnector \
--provider StripePrivy \
--app-id your-app-id \
--app-secret your-app-secret \
--authorization-private-key your-private-key \
--authorization-id your-auth-id
```

| Flag | Description |
| ----------------------------------- | ------------------------------------------ |
| `--manager <name>` | Parent payment manager (required) |
| `--name <name>` | Connector name (required) |
| `--provider <provider>` | `CoinbaseCDP` (default) or `StripePrivy` |
| `--api-key-id <id>` | Coinbase CDP API Key ID |
| `--api-key-secret <secret>` | Coinbase CDP API Key Secret |
| `--wallet-secret <secret>` | Coinbase CDP Wallet Secret |
| `--app-id <id>` | Privy App ID (StripePrivy) |
| `--app-secret <secret>` | Privy App Secret (StripePrivy) |
| `--authorization-private-key <key>` | ECDSA P-256 private key (StripePrivy) |
| `--authorization-id <id>` | Authorization key identifier (StripePrivy) |
| `--json` | JSON output |

### add credential

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

# Reset everything
agentcore remove all -y
agentcore remove all --dry-run # Preview
```

| Flag | Description |
| ------------------- | ------------------------------------------------- |
| `--name <name>` | Resource name |
| `--engine <engine>` | Policy engine name (required for `remove policy`) |
| `-y, --yes` | Skip confirmation |
| `--dry-run` | Preview (`remove all` only) |
| `--json` | JSON output |
| Flag | Description |
| ------------------- | --------------------------------------------------------- |
| `--name <name>` | Resource name |
| `--engine <engine>` | Policy engine name (required for `remove policy`) |
| `--manager <name>` | Parent payment manager (required for `payment-connector`) |
| `-y, --yes` | Skip confirmation |
| `--dry-run` | Preview (`remove all` only) |
| `--json` | JSON output |

---

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

| Flag | Description |
| ---------------------- | ---------------------------------------------------------------- |
| `[prompt]` | Prompt text (positional argument) |
| `--prompt <text>` | Prompt text (flag, takes precedence over positional) |
| `--prompt-file <path>` | Read the prompt from a file (useful for long / structured input) |
| `--runtime <name>` | Specific runtime |
| `--target <name>` | Deployment target |
| `--session-id <id>` | Continue a specific session |
| `--user-id <id>` | User ID for runtime invocation (default: `default-user`) |
| `--stream` | Stream response in real-time |
| `--tool <name>` | MCP tool name (use with `call-tool` prompt) |
| `--input <json>` | MCP tool arguments as JSON (use with `--tool`) |
| `-H, --header <h>` | Custom header (`"Name: Value"`, repeatable) |
| `--bearer-token <t>` | Bearer token for CUSTOM_JWT auth |
| `--exec` | Execute a shell command in the runtime container |
| `--timeout <seconds>` | Timeout in seconds for `--exec` commands |
| `--json` | JSON output |
| Flag | Description |
| ------------------------------ | ---------------------------------------------------------------- |
| `[prompt]` | Prompt text (positional argument) |
| `--prompt <text>` | Prompt text (flag, takes precedence over positional) |
| `--prompt-file <path>` | Read the prompt from a file (useful for long / structured input) |
| `--runtime <name>` | Specific runtime |
| `--target <name>` | Deployment target |
| `--session-id <id>` | Continue a specific session |
| `--user-id <id>` | User ID for runtime invocation (default: `default-user`) |
| `--stream` | Stream response in real-time |
| `--tool <name>` | MCP tool name (use with `call-tool` prompt) |
| `--input <json>` | MCP tool arguments as JSON (use with `--tool`) |
| `-H, --header <h>` | Custom header (`"Name: Value"`, repeatable) |
| `--bearer-token <t>` | Bearer token for CUSTOM_JWT auth |
| `--payment-instrument-id <id>` | Payment instrument ID for x402 payments |
| `--payment-session-id <id>` | Payment session ID for budget tracking |
| `--auto-session` | Auto-create/reuse a payment session for testing |
| `--exec` | Execute a shell command in the runtime container |
| `--timeout <seconds>` | Timeout in seconds for `--exec` commands |
| `--json` | JSON output |

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

Expand Down
99 changes: 98 additions & 1 deletion docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
],
"memories": [],
"credentials": [],
"payments": [],
"evaluators": [],
"onlineEvalConfigs": [],
"agentCoreGateways": [],
Expand All @@ -57,6 +58,7 @@ Main project configuration using a **flat resource model**. Agents, memories, an
| `credentials` | Yes | Array of credential providers (API key or OAuth) |
| `evaluators` | Yes | Array of custom evaluator definitions |
| `onlineEvalConfigs` | Yes | Array of online eval configurations |
| `payments` | No | Array of payment manager configurations |
| `policyEngines` | No | Array of policy engine configurations |
| `agentCoreGateways` | No | Array of gateway definitions |
| `mcpRuntimeTools` | No | Array of MCP runtime tool definitions |
Expand Down Expand Up @@ -482,6 +484,88 @@ implementations.

---

## Payment Manager Resource

Payment managers define how agents handle x402 microtransactions. Each manager has one or more connectors that provide
wallet credentials. See [Payments](payments.md) for the full usage guide.

```json
{
"payments": [
{
"name": "MyManager",
"authorizerType": "AWS_IAM",
"pattern": "interceptor",
"autoPayment": true,
"defaultSpendLimit": "10.00",
"paymentToolAllowlist": ["web_search", "fetch_url"],
"networkPreferences": ["eip155:84532"],
"description": "Production payment manager",
"connectors": [
{
"name": "MyCDPConnector",
"provider": "CoinbaseCDP",
"credentialName": "my-cdp-creds"
}
]
}
]
}
```

### Payment Manager Fields

| Field | Required | Description |
| ------------------------- | -------- | -------------------------------------------------------------------- |
| `name` | Yes | Manager name (alphanumeric + underscore, max 48, starts with letter) |
| `authorizerType` | No | `"AWS_IAM"` (default) or `"CUSTOM_JWT"` |
| `authorizerConfiguration` | Cond. | Required when `authorizerType` is `"CUSTOM_JWT"` (see below) |
| `pattern` | No | `"interceptor"` (default) or `"tool-based"` |
| `connectors` | Yes | Array of payment connector objects |
| `autoPayment` | No | Enable automatic payment (default: `true`) |
| `defaultSpendLimit` | No | Default session budget in USD (e.g., `"10.00"`) |
| `paymentToolAllowlist` | No | Array of tool names eligible for payment |
| `networkPreferences` | No | Array of network identifiers (e.g., `"eip155:84532"`) |
| `description` | No | Human-readable description |

### Authorizer Configuration (CUSTOM_JWT)

```json
{
"authorizerConfiguration": {
"customJWTAuthorizer": {
"discoveryUrl": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/.well-known/openid-configuration",
"allowedClients": ["client-id-1"],
"allowedAudience": ["https://api.example.com"],
"allowedScopes": ["payments:read", "payments:write"]
}
}
}
```

| Field | Required | Description |
| ----------------- | -------- | --------------------------- |
| `discoveryUrl` | Yes | OIDC discovery URL |
| `allowedClients` | No | Array of allowed client IDs |
| `allowedAudience` | No | Array of allowed audiences |
| `allowedScopes` | No | Array of allowed scopes |

### Payment Connector

| Field | Required | Description |
| ---------------- | -------- | -------------------------------------------------- |
| `name` | Yes | Connector name (alphanumeric + underscore, max 48) |
| `provider` | No | `"CoinbaseCDP"` (default) or `"StripePrivy"` |
| `credentialName` | Yes | Name of the credential (maps to `.env.local` vars) |

### Payment Credential Provider

Payment connectors use a `PaymentCredentialProvider` credential type, distinct from `ApiKeyCredentialProvider` and
`OAuthCredentialProvider`. The credential is automatically created during `agentcore deploy` from values in
`.env.local`. You do not need to add it to the `credentials` array manually.

---

## aws-targets.json

Deployment target
Expand Down Expand Up @@ -524,6 +608,19 @@ AGENTCORE_CREDENTIAL_{projectName}GEMINI=...
# OAuth credentials
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_ID=my-client-id
AGENTCORE_CREDENTIAL_{projectName}{credentialName}_CLIENT_SECRET=my-client-secret

# Payment credentials - CoinbaseCDP (3 variables per connector)
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_ID=your-api-key-id
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_API_KEY_SECRET=your-api-key-secret
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_WALLET_SECRET=your-wallet-secret

# Payment credentials - StripePrivy (4 variables per connector)
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_ID=your-app-id
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_APP_SECRET=your-app-secret
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_PRIVATE_KEY=your-private-key
AGENTCORE_CREDENTIAL_{CREDENTIAL_NAME}_AUTHORIZATION_ID=your-auth-id
```

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