Skip to content

feat(capacity-provider): capacity provider support #2068

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
xxuam wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(capacity-provider): capacity provider support #2068

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d82f49c
Revert "revert: remove capacity-provider Journey 1 (#2045)"
xxuam Aug 19, 2026
9c6e3cc
feat(capacity-provider): complete journeys 2-4, TUI wizard parity, an…
xxuam Aug 22, 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,13 +32,14 @@ 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, payment-manager, payment-connector)
policy, payment-manager, payment-connector, capacity-provider)
- `remove` - Remove resources (agent, memory, credential, evaluator, online-eval, gateway, gateway-target,
policy-engine, policy, payment-manager, payment-connector, all)
policy-engine, policy, payment-manager, payment-connector, capacity-provider, 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)
- `invoke` - Invoke agents (local or deployed)
- `capacity-provider delete-session` - Delete (deprovision) a live capacity provider session (data-plane)
- `run eval` - Run on-demand evaluation against agent sessions
- `evals history` - View past eval run results
- `fetch access` - Fetch access info for a deployed gateway or agent
Expand Down Expand Up @@ -90,6 +91,7 @@ Current primitives:
- `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
- `CapacityProviderPrimitive` — capacity provider creation/removal (customer-managed EC2 compute pool for runtimes)

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
12 changes: 6 additions & 6 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,10 +91,10 @@ agentcore invoke

### Resource Management

| Command | Description |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add` | Add harnesses, agents, memory, credentials, gateways and gateway-targets, evaluators, online evals, online insights, knowledge bases, config bundles, datasets, policy engines and policies, payment managers and payment connectors, runtime endpoints |
| `remove` | Remove any of the above resources from the project |
| Command | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `add` | Add harnesses, agents, memory, credentials, gateways and gateway-targets, evaluators, online evals, online insights, knowledge bases, config bundles, datasets, policy engines and policies, payment managers and payment connectors, capacity providers, runtime endpoints |
| `remove` | Remove any of the above resources from the project |

> **Note**: Run `agentcore deploy` after `add` or `remove` to update resources in AWS.

Expand Down Expand Up @@ -264,8 +264,8 @@ my-project/
Projects use JSON schema files in the `agentcore/` directory:

- `agentcore.json` - Project resources (agents, memory, credentials, gateways, evaluators, online evals/insights,
knowledge bases, harnesses, policy engines and policies, payment managers and connectors, config bundles, datasets,
runtime endpoints)
knowledge bases, harnesses, policy engines and policies, payment managers and connectors, capacity providers, config
bundles, datasets, runtime endpoints)
- `deployed-state.json` - Runtime state in agentcore/.cli/ (auto-managed)
- `aws-targets.json` - Deployment targets (account, region)

Expand Down
85 changes: 85 additions & 0 deletions docs/commands.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -318,6 +318,9 @@ agentcore add agent \
| `--client-secret <secret>` | OAuth client secret |
| `--request-header-allowlist <headers>` | Comma-separated list of inbound header names to forward to the agent. `X-*` names (e.g. `X-Api-Key`, `X-Custom-Signature`) pass through unchanged; bare names without an `X-` prefix are auto-prefixed with the legacy `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` prefix for backward compatibility. |
| `--session-storage-mount-path <path>` | Absolute mount path for session filesystem storage (e.g. `/mnt/session-storage`) |
| `--capacity-provider <name-or-arn>` | Attach the runtime to a capacity provider (customer-managed EC2 compute). Accepts an in-project capacity-provider name or an external CP ARN. Mutually exclusive with `--network-mode VPC`. |
| `--cp-volume-name <name>` | Capacity provider volume name to mount (repeatable, paired by position with `--cp-volume-mount-path`). The name must match a volume defined on the attached capacity provider. |
| `--cp-volume-mount-path <path>` | Capacity provider volume mount path under `/mnt` (e.g. `/mnt/models`, repeatable, paired with `--cp-volume-name`) |
| `--with-config-bundle` | Wire a config bundle into the generated agent template |
| `--idle-timeout <seconds>` | Idle session timeout in seconds |
| `--max-lifetime <seconds>` | Max instance lifetime in seconds |
Expand Down Expand Up @@ -778,6 +781,58 @@ agentcore add config-bundle \
| `--commit-message <text>` | Commit message for this version |
| `--json` | JSON output |

### add capacity-provider

Add a capacity provider — a customer-managed pool of AWS-managed EC2 compute that agent runtimes can run on instead of
the default managed fleet. Everything except the description and tags is immutable after creation.

**Operator role.** AgentCore assumes an IAM _operator role_ to create and manage the EC2 compute on your behalf. Omit
`--operator-role-arn` and the CLI provisions one for you at deploy time — a role that trusts
`bedrock-agentcore.amazonaws.com` (scoped to your account and region) and carries the AWS managed policy
`BedrockAgentCoreRuntimeInstancesOperatorRolePolicy` (EC2/Auto Scaling/fleet management plus the
`agentcore-lifecycle-events-*` EventBridge permissions the service needs). Pass `--operator-role-arn` only when you want
to bring your own role; it must grant those same permissions, or capacity provider creation fails asynchronously
(surfaced by CloudFormation as `NotStabilized`).

```bash
# Minimal — operator role is created automatically
agentcore add capacity-provider \
--name MyCapacityProvider \
--subnets subnet-0123456789abcdef0 \
--security-groups sg-0123456789abcdef0 \
--instance-types c6a.large

# With a named EBS volume, lifecycle limits, and ARM64 (and a bring-your-own operator role)
agentcore add capacity-provider \
--name MyCapacityProvider \
--operator-role-arn arn:aws:iam::123456789012:role/MyOperatorRole \
--subnets subnet-0123456789abcdef0,subnet-0fedcba9876543210 \
--security-groups sg-0123456789abcdef0 \
--os LINUX_ARM64 \
--instance-types c7g.large,c7g.xlarge \
--volume-name data --volume-size 20 --volume-encrypted \
--idle-instance-timeout 3600 \
--max-lifetime 28800
```

| Flag | Description |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `--name <name>` | Capacity provider name (required); immutable after creation |
| `--operator-role-arn <arn>` | IAM role ARN AgentCore assumes to manage the capacity provider (optional — auto-created if omitted); immutable |
| `--description <desc>` | Description (the only mutable field besides tags) |
| `--subnets <subnets>` | Comma-separated subnet IDs, 1–16 (required) |
| `--security-groups <groups>` | Comma-separated security group IDs, 1–16 (required) |
| `--os <os>` | `LINUX_X86_64` (default) or `LINUX_ARM64` |
| `--instance-types <types>` | Comma-separated allowed EC2 instance types, 1–30 (required) |
| `--volume-name <name>` | Named EBS volume name (repeatable, max 5; paired with `--volume-size`) |
| `--volume-size <sizeGiB>` | EBS volume size in GiB (repeatable; paired with `--volume-name`) |
| `--volume-encrypted` | Encrypt EBS volumes |
| `--volume-kms-key <arn>` | KMS key ARN for EBS volume encryption |
| `--instance-profile-arn <arn>` | IAM instance profile ARN for launched instances |
| `--idle-instance-timeout <secs>` | Idle instance timeout in seconds (60–1209600) |
| `--max-lifetime <secs>` | Maximum instance lifetime in seconds (60–1209600) |
| `--json` | JSON output |

### remove

Remove resources from project.
Expand All @@ -797,6 +852,7 @@ agentcore remove dataset --name MyDataset
agentcore remove config-bundle --name MyBundle
agentcore remove payment-manager --name MyManager -y
agentcore remove payment-connector --name MyCDPConnector --manager MyManager -y
agentcore remove capacity-provider --name MyCapacityProvider -y

# Reset everything
agentcore remove all -y
Expand Down Expand Up @@ -846,6 +902,35 @@ agentcore dev call-tool --tool myTool --input '{"arg": "value"}'
| `-b, --no-browser` | Use terminal TUI instead of web-based chat UI |
| `--no-traces` | Disable local OTEL trace collection |

### capacity-provider delete-session

Delete (deprovision) a single live capacity provider session. This is a data-plane operation: it terminates the
session's EC2 instance and **permanently deletes any persistent EBS volumes** attached to the session (data loss). The
operation is asynchronous — it returns immediately with status `Deprovisioning`. You get the session id from `invoke`
(it echoes the session it used); there is no list-sessions API.

```bash
# By in-project capacity provider name (resolved to its id from deployed state)
agentcore capacity-provider delete-session --capacity-provider my-pool --session-id <sessionId>

# By capacity provider id, without a project (the data-plane API is keyed on the id)
agentcore capacity-provider delete-session \
--capacity-provider my-pool-a1b2c3d4e5 --session-id <sessionId> --region us-west-2 --yes

# By ARN (the id is extracted from it), without a project (region auto-detected from the ARN)
agentcore capacity-provider delete-session \
--capacity-provider arn:aws:bedrock-agentcore:us-west-2:123456789012:capacity-provider/my-pool-a1b2c3d4e5 \
--session-id <sessionId> --yes
```

| Option | Description |
| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--capacity-provider <name-id-or-arn>` | Capacity provider: an in-project name (resolved to its id via deployed state), a capacity provider id, or an ARN (id extracted from it). The API is keyed on the id. (**required**) |
| `--session-id <id>` | Session id to delete (**required**) |
| `--region <region>` | AWS region (auto-detected from the ARN / project otherwise; required with a bare id outside a project unless the environment sets one) |
| `--yes` | Skip the destructive confirmation prompt (required for non-interactive use) |
| `--json` | JSON output |

### invoke

Invoke a deployed agent endpoint.
Expand Down
Loading
Loading