aws-bedrockagentcore: CfnHarness HarnessBedrockModelConfigProperty is missing AdditionalParams (present in CloudFormation schema)

[hspoon-aws]

Describe the bug

CfnHarness.HarnessBedrockModelConfigProperty (module aws-bedrockagentcore) is missing the AdditionalParams property that the live CloudFormation registry schema for AWS::BedrockAgentCore::Harness already exposes on HarnessBedrockModelConfig.

AdditionalParams is the documented mechanism for attaching Amazon Bedrock Guardrails (and other provider-specific Converse parameters) to a harness: https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/harness-models.html ("Apply Amazon Bedrock Guardrails" — "add a guardrailConfig object to bedrockModelConfig.additionalParams"). Without it there is no typed way to configure guardrails on a harness at deploy time.

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

No response

Expected Behavior

HarnessBedrockModelConfigProperty exposes additionalParams?: any so this compiles:

new agentcore.CfnHarness(this, 'Harness', {
  harnessName: 'planner',
  executionRoleArn: role.roleArn,
  model: {
    bedrockModelConfig: {
      modelId: 'us.anthropic.claude-sonnet-5',
      additionalParams: {
        guardrailConfig: {
          guardrailIdentifier: guardrailArn,
          guardrailVersion: '1',
          trace: 'enabled',
        },
      },
    },
  },
});

Current Behavior

TypeScript rejects the property:

Object literal may only specify known properties, and 'additionalParams' does not exist in type 'HarnessBedrockModelConfigProperty'.

In aws-cdk-lib 2.266.0 and the latest 2.268.0, aws-bedrockagentcore/lib/bedrockagentcore.generated.d.ts defines the property with only:

interface HarnessBedrockModelConfigProperty {
  readonly apiFormat?: string;
  readonly maxTokens?: number;
  readonly modelId: string;
  readonly temperature?: number;
  readonly topP?: number;
}

The Python API reference shows the same shape (model_id, api_format, max_tokens, temperature, top_p), so all jsii languages are affected.

The CloudFormation registry schema does have the property:

$ aws cloudformation describe-type --type RESOURCE --type-name AWS::BedrockAgentCore::Harness \
    --query Schema --output text | jq '.definitions.HarnessBedrockModelConfig.properties | keys'
[
  "AdditionalParams",
  "ApiFormat",
  "MaxTokens",
  "ModelId",
  "Temperature",
  "TopP"
]

The latest published @aws-cdk/aws-service-spec (0.1.210) db.json contains zero occurrences of AdditionalParams, so the gap appears to be in the service-spec snapshot rather than in CloudFormation.

Reproduction Steps

1. npm i aws-cdk-lib@2.268.0
2. Add additionalParams to model.bedrockModelConfig in a CfnHarness as shown under Expected Behavior.
3. tsc / cdk synth fails with the type error above.
4. Compare with aws cloudformation describe-type --type RESOURCE --type-name AWS::BedrockAgentCore::Harness (us-west-2), which lists AdditionalParams under HarnessBedrockModelConfig.

Possible Solution

Refresh the AWS::BedrockAgentCore::Harness schema in @aws-cdk/aws-service-spec so the L1 generator emits additionalParams on HarnessBedrockModelConfigProperty (type any / JSON document, matching the data-plane SDK's HarnessBedrockModelConfig.additionalParams?: DocumentType).

Workaround in the meantime:

harness.addPropertyOverride('Model.BedrockModelConfig.AdditionalParams', {
  guardrailConfig: { guardrailIdentifier: guardrailArn, guardrailVersion: '1', trace: 'enabled' },
});

Additional Information/Context

The data-plane SDK already models the field: @aws-sdk/client-bedrock-agentcore 3.1119.0 HarnessBedrockModelConfig.additionalParams?: __DocumentType, and a per-invocation InvokeHarness override with additionalParams.guardrailConfig was verified live to return stopReason: guardrail_intervened when the guardrail triggers. The deploy-time CDK path is the only piece missing.

AWS CDK Library version (aws-cdk-lib)

2.266.0 (also reproduced against the 2.268.0 generated typings)

AWS CDK CLI version

2.1139.0

Node.js Version

v24.11.1

OS

macOS 26.6.2

Language

TypeScript

Language Version

TypeScript 5.6

Other information

No response

[hspoon-aws]

Update after digging into the pipeline: this is not a stale spec snapshot, it's an importer bug in cdklabs/awscdk-service-spec.

The source schema already has the property. sources/CloudFormationSchema/us-east-1/aws-bedrockagentcore-harness.json (and the us-west-2 copy) on main contains AdditionalParams under HarnessBedrockModelConfig, HarnessOpenAiModelConfig, and HarnessLiteLlmModelConfig, and has since commit 3997e7cc (2026-06-23, "feat(sources): update cfn-schema (#2775)").

The importer drops it. Running importCloudFormationRegistryResource from @aws-cdk/service-spec-importers 0.0.139 against that schema file reproduces the gap. The problem report contains, for all three model configs:

AWS::BedrockAgentCore::Harness: property Model: typedef HarnessModelConfiguration: property BedrockModelConfig: typedef HarnessBedrockModelConfig: property AdditionalParams: Error: Cannot read properties of undefined (reading 'filter')
TypeError: Cannot read properties of undefined (reading 'filter')
    at simplifyUnion (.../schema-manipulation/unify-schemas.js:117:9)
    at unionSchemas (.../schema-manipulation/unify-schemas.js:15:12)
    at mapLikeSchemaToModelType (.../importers/import-cloudformation-registry.js:219:133)
    at schemaObjectToModelType (.../importers/import-cloudformation-registry.js:206:20)
    ...

and the resulting HarnessBedrockModelConfig type definition has only ModelId, MaxTokens, Temperature, TopP, ApiFormat.

Trigger. The property is declared as a map with an empty (any) value schema:

"AdditionalParams": {
  "type": "object",
  "additionalProperties": false,
  "patternProperties": { "^[\\s\\S]{1,256}$": {} }
}

mapLikeSchemaToModelType calls unionSchemas(...Object.values(schema.patternProperties)), i.e. unionSchemas({}). simplifyUnion wraps this as { anyOf: [{}] } and calls jsonschema.innerSchemas(x). But isAnyOf returns false when every element is an any-type (isAnyType(elem) short-circuits the check), so innerSchemas falls through to return x.allOf, which is undefined, and .filter(Boolean) throws. The failure is caught by tryCatch, reported, and the property is omitted.

Other harness properties with loose typing (e.g. HarnessInlineFunctionConfig.InputSchema, a bare {"type":"object"}) take the isAnyType → json path directly and survive, which is why only AdditionalParams is affected.

Suggested fix (in awscdk-service-spec). Either short-circuit in unionSchemas/simplifyUnion when all inputs are any-types (return true/{} → json element, yielding Map<string, any>), or make innerSchemas tolerate a union whose members are all any-types. Expected L1 output: additionalParams?: any on the three model config property types.

Happy to open a corresponding issue on cdklabs/awscdk-service-spec if that's the preferred place to track the importer fix.

[pahud]

Hi @hspoon-aws,

┌────────────────────────────────────────────────────────────┐
│ 🔴 Reported State                                          │
│ CfnHarness L1 lacks AdditionalParams; no typed way to set  │
│ guardrailConfig at deploy time                             │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│ 🔍 Root Cause                                              │
│ Importer crash on map schema with empty value schema;      │
│ property silently dropped (unify-schemas.ts simplifyUnion) │
└─────────────────────────────┬──────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────┐
│ 🟢 Suggested Fix                                           │
│ Patch cdklabs/awscdk-service-spec importer to treat        │
│ all-any-type unions as `json` → additionalParams?: any     │
└────────────────────────────────────────────────────────────┘

Thanks for the exceptionally thorough report — the follow-up comment tracing this into the importer saved a lot of digging. I was able to reproduce every step of your analysis locally on macOS:

• Confirmed additionalParams is absent from the generated typings in the latest aws-cdk-lib (2.269.0) — zero occurrences.
• Confirmed the schema source in cdklabs/awscdk-service-spec does declare AdditionalParams (as a map with an empty patternProperties value schema) on all three model config types.
• Reproduced the crash with @aws-cdk/service-spec-importers@0.0.139: unionSchemas({}) throws TypeError: Cannot read properties of undefined (reading 'filter') in simplifyUnion, exactly as you described.

The mechanism checks out in the source: isAnyOf returns false when every anyOf element is an any-type, so innerSchemas falls through to return x.allOf (undefined) and the .filter(Boolean) in simplifyUnion throws. The error is caught, reported, and the property is silently omitted.

https://github.com/cdklabs/awscdk-service-spec/blob/31bf8f55ddec6fddf107efaeb065fe1561f0bdd1/packages/%40aws-cdk/service-spec-importers/src/types/registry-schema/JsonSchema.ts#L110-L116

https://github.com/cdklabs/awscdk-service-spec/blob/31bf8f55ddec6fddf107efaeb065fe1561f0bdd1/packages/%40aws-cdk/service-spec-importers/src/schema-manipulation/unify-schemas.ts#L133-L138

In my opinion your suggested fix direction is right: short-circuiting unionSchemas/simplifyUnion when all inputs are any-types (yielding the json type → Map<string, any>) is the minimal, safe change, and it would restore additionalParams?: any on all three model config property types on the next spec release + L1 regeneration — no manual change needed in this repo.

Yes, please do open the issue on cdklabs/awscdk-service-spec — that's the right place to track the importer fix, and feel free to link it back here. Since you've already isolated the failing function, a PR there would be very welcome if you're up for it (the contributing guide is in that repo's README).

In the meantime your addPropertyOverride('Model.BedrockModelConfig.AdditionalParams', ...) workaround is the correct escape hatch — CloudFormation accepts the property today, so deploys with the override work fine.

[hspoon-aws]

Thanks @pahud. Opened the importer issue on cdklabs/awscdk-service-spec with the repro, root cause, and the short-circuit fix direction: cdklabs/awscdk-service-spec#2894

I'll follow up with a PR there.