# Create a configuration bundle
<a name="configuration-bundles-create"></a>

Create a configuration bundle to store a versioned snapshot of your agent’s dynamic configuration. The bundle is created with an initial version on the `mainline` branch.

**Note**  
The CLI `add config-bundle` command saves the bundle definition to `agentcore.json` locally. To actually create it on the service, you must run `agentcore deploy` afterwards.

## Code samples
<a name="create-bundle-examples"></a>

**Example**  
Create with inline components JSON, then deploy:  

```
agentcore add config-bundle \
  --name myAgentConfig \
  --components '{"arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-abc123": {"configuration": {"system_prompt": "You are a helpful assistant.", "model_id": "global.anthropic.claude-sonnet-4-5-20250929-v1:0"}}}'

agentcore deploy
```
Create from a components file, then deploy:  

```
agentcore add config-bundle \
  --name myAgentConfig \
  --components-file ./components.json

agentcore deploy
```
Sample `components.json`:  

```
{
    "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-abc123": {
        "configuration": {
            "system_prompt": "You are a helpful customer support assistant for Acme Store. When handling requests: 1) Identify ALL actions needed before starting any. 2) Execute each action in sequence. 3) Before ending any conversation, summarize what was done.",
            "model_id": "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
        }
    }
}
```

```
import boto3
import uuid

client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")

RUNTIME_ARN = "arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/MyAgent-abc123"

response = client.create_configuration_bundle(
    bundleName="myAgentConfig",
    components={
        RUNTIME_ARN: {
            "configuration": {
                "system_prompt": "You are a helpful customer support assistant.",
                "model_id": "global.anthropic.claude-sonnet-4-5-20250929-v1:0",
                "temperature": 0.7,
            }
        }
    },
    description="Initial configuration for MyAgent",
    branchName="mainline",
    commitMessage="Initial bundle creation",
    clientToken=str(uuid.uuid4()),
)

print(f"Bundle ID: {response['bundleId']}")
print(f"Bundle ARN: {response['bundleArn']}")
print(f"Version ID: {response['versionId']}")
```

## Request parameters
<a name="create-bundle-params"></a>


| Parameter | Type | Required | Description | 
| --- | --- | --- | --- | 
|  `bundleName`  | String | Yes | Name for the bundle. Must match `[a-zA-Z][a-zA-Z0-9_]{0,99}`. Names must be unique within your account. | 
|  `components`  | Map | Yes | Map of component identifier to component configuration. The key is typically the ARN of the AgentCore resource being configured (for example, a runtime ARN). Each value contains a `configuration` object with arbitrary key-value pairs. | 
|  `description`  | String | No | Description of the bundle. Maximum 500 characters. | 
|  `branchName`  | String | No | Branch name for version tracking. Defaults to `mainline`. Must match `[a-zA-Z][a-zA-Z0-9_/-]{0,127}`. | 
|  `commitMessage`  | String | No | Commit message for the initial version. Maximum 500 characters. | 
|  `createdBy`  | Object | No | Source that created this version. Contains `name` (required) and `arn` (optional). | 
|  `clientToken`  | String | No | Idempotency token. If you retry with the same token, the service returns the existing bundle instead of creating a new one. | 
|  `tags`  | Map | No | Resource tags. Maximum 50 tags. | 

## Response
<a name="create-bundle-response"></a>


| Field | Type | Description | 
| --- | --- | --- | 
|  `bundleArn`  | String | ARN of the created configuration bundle. | 
|  `bundleId`  | String | Unique identifier for the bundle. Format: `{name}-{10-char-suffix}`. | 
|  `versionId`  | String | UUID of the initial version created with the bundle. | 
|  `createdAt`  | Timestamp | When the bundle was created. | 

## Errors
<a name="create-bundle-errors"></a>


| Error | HTTP status | Description | 
| --- | --- | --- | 
|  `ValidationException`  | 400 | Invalid request parameters. Check field constraints and naming patterns. | 
|  `ConflictException`  | 409 | A bundle with the same name or client token already exists. | 
|  `ServiceQuotaExceededException`  | 402 | You have reached the maximum number of configuration bundles for your account. | 
|  `AccessDeniedException`  | 403 | Insufficient permissions. Verify IAM policies include `bedrock-agentcore:CreateConfigurationBundle`. | 
|  `ThrottlingException`  | 429 | Request rate exceeded. Retry with exponential backoff. | 
|  `InternalServerException`  | 500 | Service-side error. Retry the request. |