[jariy17]

Description

Documents the project-specific customJwtAuthorizer shape in agentcore add harness --help and explains that the generated harness.yaml uses the service API spelling customJWTAuthorizer. This does not alter the imperative agentcore harness create or agentcore harness update service API help.

Related Issue

Closes #2743

Documentation PR

Related skill guidance: aws/agent-toolkit-for-aws#502

Type of Change

• Bug fix
• Documentation update

Testing

• Rendered agentcore add harness --help and verified the new guidance
• bun test (4702 passed, 6 skipped)
• bun run typecheck
• bun run lint:check
• bun run format:check
• bun run build
• End-to-end AWS testing is not applicable to this help-only change

No new regression test was added for this help-text-only change.

Checklist

• I have read the contributing guidelines
• Documentation and examples describe both project configuration and generated service configuration casing
• Existing tests and validation checks pass
• No new warnings are introduced
• Related skill PR is merged

[github-actions]

Package Tarball

aws-agentcore-1.0.1.tgz

How to install

gh release download pr-2744-tarball --repo aws/agentcore-cli --pattern "*.tgz" --dir /tmp/pr-tarball
npm install -g /tmp/pr-tarball/aws-agentcore-1.0.1.tgz

[agentcore-devx-automation]

Claude Security Review: no high-confidence findings. (run)

[agentcore-devx-automation]

AgentCore Harness Review

Verdict: Changes requested

The core of the change is right: HarnessSpecSchema → AuthorizerConfigSchema (src/projectSchemas/auth.ts:205) only accepts customJwtAuthorizer, while encodeHarnessYaml (src/projectSchemas/harness.ts:890) emits customJWTAuthorizer, so documenting the project-vs-service casing split on agentcore add harness is accurate, and it correctly leaves the imperative harness create/harness update help (src/handlers/harness/parameterHelp.tsx:300) alone. Rendering through formatParameterDetails also matches the existing convention (type annotation on line 1, body indented).

One issue worth fixing before merge:

The copy‑pasteable example is rejected by validation

src/handlers/project/add/harness/index.ts:41-42 (the Example: block in AUTHORIZER_CONFIGURATION_HELP):

Example:
  --authorizer-configuration '{"customJwtAuthorizer":{...}}'

HarnessSpecSchema's refinement at src/projectSchemas/harness.ts:623-629 rejects authorizerConfiguration unless authorizerType === "CUSTOM_JWT", and authorizerType has no default (src/projectSchemas/harness.ts:544). The existing test case "authorizer config without matching type" (src/handlers/project/add/harness/index.test.ts:721-729) asserts exactly this failure. So pasting the documented example as-is fails with authorizerConfiguration is only allowed when authorizerType is CUSTOM_JWT — the same class of confusing rejection #2743 is trying to eliminate.

Options:

• Include the companion flag in the example, e.g. --authorizer-type CUSTOM_JWT --authorizer-configuration '{"customJwtAuthorizer":{...}}'.
• Keep the example as is but add a sentence stating that --authorizer-type CUSTOM_JWT must be supplied alongside this flag (and that the flag is rejected for AWS_IAM).

Optional (non-blocking)

The project schema also accepts allowedClients, allowedScopes, customClaims, privateEndpoint, and privateEndpointOverrides under customJwtAuthorizer, and requires at least one of audience/clients/scopes/claims (src/projectSchemas/auth.ts:147-167). The imperative help documents the sibling keys; adding a short "JSON syntax" block here would give parity, and the same project-casing note applies to agentcore add runtime --authorizer-configuration (src/handlers/project/add/runtime/index.ts:157) if you want to cover that in the same pass.

[jariy17]

Closing because no CLI change is needed for this behavior.