@aws/agentcore 1.0.0-rc.1 → 1.0.0-rc.3

package/README.md

@@ -62,12 +62,15 @@ agentcore                          # interactive TUI
 │   │   ├── list                   # list API key credential providers
 │   │   ├── update                 # update an API key credential provider
 │   │   └── delete                 # delete an API key credential provider
-│   └── oauth2-credential-provider
-│       ├── create                 # create an OAuth2 credential provider
-│       ├── get                    # get an OAuth2 credential provider
-│       ├── list                   # list OAuth2 credential providers
-│       ├── update                 # update an OAuth2 credential provider
-│       └── delete                 # delete an OAuth2 credential provider
+│   ├── oauth2-credential-provider
+│   │   ├── create                 # create an OAuth2 credential provider
+│   │   ├── get                    # get an OAuth2 credential provider
+│   │   ├── list                   # list OAuth2 credential providers
+│   │   ├── update                 # update an OAuth2 credential provider
+│   │   └── delete                 # delete an OAuth2 credential provider
+│   └── payment-credential-provider
+│       ├── get                    # get a payment credential provider
+│       └── list                   # list payment credential providers
 ├── runtime                        # inspect deployed AgentCore Runtimes
 │   ├── get                        # fetch a Runtime by id
 │   ├── list                       # list Runtimes (server-side paginated)
@@ -107,6 +110,20 @@ agentcore                          # interactive TUI
 │   │   └── list                   # list Rules under a Gateway
 │   └── policy
 │       └── generate               # generate Cedar for a Gateway from a prompt (TUI when run bare)
+├── payment                        # inspect AgentCore Payments (command line only for now)
+│   ├── manager
+│   │   ├── get                    # get a payment manager by id
+│   │   └── list                   # list payment managers (server-side paginated)
+│   ├── connector                  # connectors under a payment manager
+│   │   ├── get                    # get a connector (shows the Quick Create authorization URL while pending)
+│   │   └── list                   # list a manager's connectors
+│   ├── session                    # budget-limited payment contexts (data plane)
+│   │   ├── get
+│   │   └── list
+│   └── instrument                 # embedded crypto wallets (data plane)
+│       ├── get
+│       ├── list
+│       └── balance                # read token balance on an explicit chain (default token: USDC)
 ├── eval                           # evaluate and optimize AgentCore agents
 │   └── evaluator                  # manage AgentCore evaluators
 │       ├── llm-as-a-judge         # LLM-as-a-Judge evaluators
@@ -121,7 +138,9 @@ agentcore                          # interactive TUI
 ├── project                        # manage an AgentCore project (scaffold → deploy)
 │   ├── create                     # create a project: a managed harness by default,
 │   │                              #   or scaffolded runtime code via --template;
-│   │                              #   bare `project create` opens an interactive wizard
+│   │                              #   bare `project create` opens an interactive wizard.
+│   │                              #   agentcore/cdk/ holds a two-file CDK app on
+│   │                              #   @aws/agentcore-cdk (bin/cdk.ts, lib/cdk-stack.ts)
 │   ├── add                        # add a resource to the project (runtime, harness, memory, …)
 │   ├── export
 │   │   └── harness                # convert a harness into an editable Strands runtime agent
@@ -139,7 +158,11 @@ agentcore                          # interactive TUI
 │   │   ├── runtime                # use the existing Runtime invoke experience
 │   │   └── harness                # use the existing Harness invoke experience
 │   ├── status                     # inspect deployed project resources (TUI when run bare)
-│   └── build                      # synthesize the project's CloudFormation templates
+│   ├── build                      # synthesize the project's CloudFormation templates
+│   ├── log
+│   │   └── runtime                # resolve a project Runtime and inspect its logs
+│   └── traces
+│       └── runtime
 └── config                         # read/write global config values
 ```
 
@@ -157,6 +180,60 @@ pre-built container image or a custom Dockerfile, that is reported in
 `EXPORT_NOTES.md` rather than rebuilt. Path-based skills are not supported,
 since the exported agent has no container filesystem to read them from.
 
+### Harness Project Files
+
+`project create` (without `--template`) and `project add harness` share the same
+scaffolding flow. Each harness has `app/<name>/harness.yaml` and
+`app/<name>/system-prompt.md`. YAML is the harness configuration format.
+The YAML contains the supplied settings and
+commented optional examples. Tools are opt-in. Newly scaffolded harnesses
+explicitly use `memory: { mode: managed }` unless another memory configuration
+was supplied. Reading an existing file with no `memory` setting still means
+disabled memory; reading never adds the scaffold default.
+
+```yaml
+name: assistant
+model:
+  provider: bedrock
+  modelId: global.anthropic.claude-sonnet-4-6
+# Instructions come from system-prompt.md unless systemPrompt is set inline.
+# systemPrompt: You are a helpful assistant.
+memory:
+  mode: managed
+```
+
+Both deployment and local export use inline `systemPrompt` text when it is
+provided. Otherwise, instructions come from `system-prompt.md` next to
+`harness.yaml`. Prompt contents are not trimmed, and blank prompts are rejected.
+Prompt settings do not resolve local file references.
+
+```yaml
+systemPrompt: |
+  You are a concise assistant.
+truncation:
+  strategy: summarization
+  config:
+    summarization:
+      summarizationSystemPrompt: Keep decisions and open questions.
+```
+
+`project add harness --system-prompt "Your instructions"` writes the supplied
+text to `system-prompt.md`, leaving `systemPrompt` out of the generated YAML.
+Summary instructions in
+`truncation.config.summarization.summarizationSystemPrompt` are inline text.
+
+Skills are unchanged: skill paths refer to the **runtime/container filesystem**,
+not local files to package. Other fields do not support local includes.
+Malformed YAML, duplicate keys, and existing schema violations fail the read.
+Unknown fields at the harness root and directly inside `model` are stripped
+from the parsed configuration. Nested configurations keep their existing
+validation contracts. Free-form
+maps such as headers, tags, environment variables, `additionalParams`, and
+`inputSchema` still accept arbitrary keys.
+Build, deploy, and export do not rewrite harness YAML or remove its comments.
+`agentcore.json`, deployment targets, JSON CLI flags/output, and service payloads
+are unchanged.
+
 Global flags (declared at the root, available on every command):
 
 | Flag             | Purpose                                                              |
@@ -186,6 +263,111 @@ agentcore project invoke harness \
 Use `--target` to select a deployment target. When a project declares exactly
 one resource of the requested type, `--name` may be omitted.
 
+### Inspect project logs
+
+Project logging resolves a logical resource name through the selected
+deployment target, so physical IDs and deployment regions do not need to be
+supplied:
+
+```bash
+agentcore project log runtime
+agentcore project log runtime --name checkout --target production
+agentcore project log runtime --name checkout --since 1h --level error
+agentcore project log harness
+agentcore project log harness --name support --target production
+agentcore project log harness --name support --since 1h --level error
+```
+
+When the project declares exactly one resource of the requested type, `--name`
+may be omitted. For Harnesses, the CLI also resolves the managed Harness to its
+underlying Runtime before reading CloudWatch. Use the imperative
+`agentcore runtime logs` or `agentcore harness logs` commands when addressing a
+physical resource directly or working outside a project.
+
+### Inspect project traces
+
+Project tracing uses the same logical resource and deployment target
+resolution, then lists or downloads traces from the resolved Runtime's
+deployment region:
+
+```bash
+agentcore project traces runtime list
+agentcore project traces runtime list --name checkout --target production --since 30m
+agentcore project traces runtime get <traceId> --name checkout --output trace.json
+agentcore project traces harness list
+agentcore project traces harness list --name support --target production --since 30m
+agentcore project traces harness get <traceId> --name support --output trace.json
+```
+
+When the project declares exactly one resource of the requested type, `--name`
+may be omitted. For Harnesses, the CLI resolves the underlying Runtime before
+querying its traces. Use the imperative `agentcore runtime traces` or
+`agentcore harness traces` commands when addressing a physical resource
+directly or working outside a project.
+
+### Inspect AgentCore Payments
+
+The `payment` commands call the Payments control and data planes directly, with
+no project involved. This command family currently provides read-only inspection
+of existing managers, connectors, sessions, instruments, and payment credential
+providers. It does not create IAM roles or change provider credentials.
+
+Choose a manager from `manager list` and use its `paymentManagerId` below:
+
+```bash
+agentcore payment manager list --json
+MANAGER_ID='<paymentManagerId from manager list>'
+agentcore payment manager get --id "$MANAGER_ID"
+agentcore payment connector list --manager-id "$MANAGER_ID"
+```
+
+`--user-id` is the application user ID used when the session or instrument was
+created, not an IAM username or AWS profile. Session and instrument reads require
+it with IAM authentication; their lists return that user's resources, not every
+user's resources under the manager.
+
+```bash
+USER_ID='alice' # Use the application user ID associated with the resources.
+agentcore payment session list --manager-id "$MANAGER_ID" --user-id "$USER_ID"
+agentcore payment instrument list --manager-id "$MANAGER_ID" --user-id "$USER_ID"
+
+# Use paymentInstrumentId and paymentConnectorId from the same instrument list item.
+INSTRUMENT_ID='<paymentInstrumentId>'
+CONNECTOR_ID='<paymentConnectorId>'
+agentcore payment instrument get --manager-id "$MANAGER_ID" \
+  --instrument-id "$INSTRUMENT_ID" --user-id "$USER_ID"
+agentcore payment instrument balance --manager-id "$MANAGER_ID" \
+  --connector-id "$CONNECTOR_ID" --instrument-id "$INSTRUMENT_ID" \
+  --user-id "$USER_ID" --chain BASE_SEPOLIA
+```
+
+To inspect connector or credential provider metadata:
+
+```bash
+agentcore payment connector get --manager-id "$MANAGER_ID" --connector-id "$CONNECTOR_ID"
+agentcore identity payment-credential-provider list --json
+agentcore identity payment-credential-provider get --name '<provider name>'
+```
+
+The optional `--agent-name` on session and instrument reads labels the request for
+observability. It does not select an AgentCore agent or filter the results.
+
+`instrument get` returns instrument metadata without querying balances. `balance`
+requires an explicit chain and defaults to `--token USDC`; wallet network families
+such as ETHEREUM do not identify whether to query mainnet or a testnet. The JSON
+response retains the raw atomic amount string and decimals. A service error is
+reported as an error, never converted to a zero balance.
+
+Data-plane commands work against managers that use the `AWS_IAM` authorizer.
+The CLI resolves `--manager-id` through `GetPaymentManager` in the configured
+region, then supplies the returned ARN to the data-plane API. Callers need
+`bedrock-agentcore:GetPaymentManager` as well as the relevant data-plane action.
+Region resolution follows the other imperative commands: `--region`, environment
+variables, the active AWS profile, then the CLI default.
+A `CUSTOM_JWT` manager accepts only bearer tokens on its data plane, which
+these commands do not send yet; the CLI reports that limitation before calling
+the data plane.
+
 ### Examples
 
 ```bash
@@ -251,7 +433,7 @@ agentcore runtime version list --id <runtimeId> --max-results 20
 agentcore runtime endpoint get --id <runtimeId> --qualifier DEFAULT
 agentcore runtime endpoint list --id <runtimeId> --max-results 20
 
-# Follow a Runtime's logs live (Ctrl+C to stop); inside a project --id is optional
+# Follow a Runtime's logs live by resource ID (Ctrl+C to stop)
 agentcore runtime logs --id <runtimeId>
 agentcore runtime logs --id <runtimeId> --level error --query "database"
 
@@ -263,6 +445,13 @@ agentcore runtime logs --id <runtimeId> --since 2026-08-30T12:00:00Z --until now
 agentcore runtime traces list --id <runtimeId> --since 30m
 agentcore runtime traces get <traceId> --id <runtimeId> --output trace.json
 
+# Resolve project resources by logical name and deployment target
+agentcore project log harness --name support --target production --since 1h
+agentcore project traces runtime list --name checkout --target production --since 30m
+agentcore project traces runtime get <traceId> --name checkout --output trace.json
+agentcore project traces harness list --name support --target production --since 30m
+agentcore project traces harness get <traceId> --name support --output trace.json
+
 # Inspect AgentCore Memories without project configuration or deployment
 agentcore memory get --id <memoryId>
 agentcore memory get --id <memoryId> --view without_decryption
@@ -342,6 +531,55 @@ Source-aware values: any field flag documented as such accepts the value inline,
 `file://` convention). A command reads stdin from at most one flag. For example,
 `--instructions file://order-quality.txt` or `--instructions -`.
 
+Project credentials: a `credentials[]` entry in `agentcore.json` is named by its
+spec name and keeps its secret in `agentcore/.env.local` under
+`AGENTCORE_CREDENTIAL_<NAME>` (with a field suffix for OAuth2 and payment
+values). `project deploy` provisions the Identity credential provider before
+synth under the name `<project>_<target>_<credential>`, so two targets in one
+account and region get separate providers, and records its ARN in
+`deployed-state.json` under the spec name. A credential removed from the spec
+has its provider deleted on the next deploy of each target, after the stack
+update. Tearing a target down (deploying a spec with nothing left to deploy,
+which is where `project remove all` leads) deletes every provider the target
+owns: API key, OAuth2 and payment. CLI versions before this change named providers by the bare credential name. Those
+providers stay in the account after an upgrade, untouched by deploys and
+teardowns. Delete them with `agentcore identity api-key-credential-provider
+delete --name <credential>`, the `oauth2-credential-provider` equivalent, or
+`aws bedrock-agentcore-control delete-payment-credential-provider` once nothing
+else uses them.
+
+### Extending the CDK app
+
+`agentcore/cdk/` is a CDK app of two files. `bin/cdk.ts` reads the project once
+(`readAgentCoreProject`), makes one stack per deployment target
+(`resolveTargetStacks`) and turns `agentcore.json` into the application's props
+(`transformAgentCoreJson`) — all three come from `@aws/agentcore-cdk`, so how
+`agentcore.json` is interpreted changes with the library version, not with code
+on your disk. `lib/cdk-stack.ts` instantiates one `AgentCoreApplication`; it is
+the file you edit. Add your own resources after the application and wire them to
+a runtime or harness through the application's accessors: runtimes and harnesses
+implement `iam.IGrantable`, so any AWS L2 grant accepts them, and they expose
+`grantRead` / `grantWrite` / `grantReadWrite` (DynamoDB tables, S3 buckets,
+Secrets Manager secrets) and `addEnvironmentVariable`:
+
+```ts
+import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
+
+const orders = new dynamodb.Table(this, "Orders", {
+  partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
+});
+const checkout = this.application.runtime("checkout"); // or this.application.harness('support')
+checkout.grantReadWrite(orders);
+checkout.addEnvironmentVariable("ORDERS_TABLE", orders.tableName);
+orders.grantReadData(this.application.harness("support")); // any AWS L2 grant works too
+```
+
+Redeploy with `agentcore project deploy`. An unknown name fails at synth and lists
+the names that exist; a runtime or harness configured with an `executionRoleArn`
+warns at synth about every grant CDK could not attach to the imported role. Note
+that `agentcore project status` reports only the resources `agentcore.json`
+declares, not the ones you add in the stack.
+
 ### Invoke a Gateway
 
 Gateway Invoke is a project-independent HTTP request command with headless and
@@ -967,8 +1205,10 @@ npm i -g ./aws-agentcore-0.28.1.tgz
   output while text is selected (the title bar shows `Select`). Press `Esc`.
   Windows Terminal does not do this.
 - **`project create` refuses a long path**: Windows caps paths at 260 characters
-  unless `LongPathsEnabled` is set, and the CDK app's `node_modules` needs about
-  100 of them. Create the project higher in the tree or enable long paths.
+  unless `LongPathsEnabled` is set, and the CDK app's `node_modules` puts its
+  deepest file 155 characters below the project root (aws-cdk-lib's own shipped
+  fixtures), so the project root must be at most 104 characters. Create the
+  project higher in the tree or enable long paths.
 
 # Build
 

package/dist/assets/cdk/README.md

@@ -1,29 +1,52 @@
-# AgentCore CDK Project
+# AgentCore CDK app
 
-This CDK project is managed by the AgentCore CLI. It deploys your agent infrastructure into AWS using the `@aws/agentcore-cdk` L3 constructs.
+This CDK app is managed by the AgentCore CLI. It deploys everything declared in `agentcore/agentcore.json` into AWS
+through the `@aws/agentcore-cdk` constructs. It is two files:
 
-## Structure
+- `bin/cdk.ts` — the entry point. It reads the project once (`readAgentCoreProject`), creates one stack per deployment
+  target (`resolveTargetStacks`), and turns `agentcore.json` into the application's props (`transformAgentCoreJson`).
+  Everything about how `agentcore.json` is interpreted lives in the library, so it changes with the library version, not
+  with this file.
+- `lib/cdk-stack.ts` — `AgentCoreStack`, which instantiates one `AgentCoreApplication`. This is the file you edit.
 
-- `bin/cdk.ts` — Entry point. Reads project configuration from `agentcore/` and creates a stack per deployment target.
-- `lib/cdk-stack.ts` — Defines `AgentCoreStack`, which wraps the `AgentCoreApplication` L3 construct.
-- `test/cdk.test.ts` — Unit tests for stack synthesis.
+Harness settings are read from `harness.yaml`. Inline `systemPrompt` text overrides
+the conventional `system-prompt.md` file in the harness directory.
 
-## Useful commands
+## The CLI runs it for you
 
-- `npm run build` compile TypeScript to JavaScript
-- `npm run test` run unit tests
-- `npx cdk synth` emit the synthesized CloudFormation template
-- `npx cdk deploy` deploy this stack to your default AWS account/region
-- `npx cdk diff` compare deployed stack with current state
+You normally do not run this app directly:
 
-## Usage
+```bash
+agentcore project build    # synthesizes the CloudFormation templates into agentcore/cdk/cdk.out
+agentcore project deploy   # synthesizes, then deploys the stack for the selected target
+agentcore project status   # reports the resources agentcore.json declares
+```
 
-You typically don't need to interact with this directory directly. The AgentCore CLI handles synthesis and deployment:
+`npm run build` compiles the app, and `npx cdk synth` / `npx cdk diff` work from this directory too.
 
-<!-- TODO: revisit these commands once the project CLI surface is final —
-     they may need a project prefix (e.g. --project / cwd) to disambiguate. -->
+## Extending the stack
 
-```bash
-agentcore deploy    # synthesizes and deploys via CDK
-agentcore status    # checks deployment status
+Add your own AWS resources in `lib/cdk-stack.ts` after the application and wire them to a runtime or harness through the
+application's accessors. Runtimes and harnesses implement `iam.IGrantable`, so any AWS L2 grant accepts them, and they
+expose `grantRead` / `grantWrite` / `grantReadWrite` for DynamoDB tables, S3 buckets and Secrets Manager secrets plus
+`addEnvironmentVariable`:
+
+```ts
+import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
+
+const orders = new dynamodb.Table(this, 'Orders', {
+  partitionKey: { name: 'pk', type: dynamodb.AttributeType.STRING },
+});
+const checkout = this.application.runtime('checkout'); // or this.application.harness('support')
+checkout.grantReadWrite(orders); // updates the runtime's execution role
+checkout.addEnvironmentVariable('ORDERS_TABLE', orders.tableName);
+orders.grantReadData(this.application.harness('support')); // any AWS L2 grant works too
 ```
+
+Then run `agentcore project deploy` again. An unknown name fails at synth and lists the names that exist.
+
+If a runtime or harness is configured with an `executionRoleArn`, CDK cannot modify that imported role: every grant
+emits a synth-time warning listing the permissions that were not attached, and the role must already carry them.
+
+`agentcore project status` reports only the resources `agentcore.json` declares; resources you add here are visible
+through CloudFormation (`aws cloudformation describe-stack-resources`).

package/dist/assets/cdk/bin/cdk.ts

@@ -1,181 +1,30 @@
 #!/usr/bin/env node
-import { AgentCoreStack, type HarnessConfig } from '../lib/cdk-stack';
-import { ConfigIO, HarnessSpecSchema, type AwsDeploymentTarget } from '@aws/agentcore-cdk';
-import { App, type Environment } from 'aws-cdk-lib';
-import * as path from 'path';
-import * as fs from 'fs';
-
-function toEnvironment(target: AwsDeploymentTarget): Environment {
-  return {
-    account: target.account,
-    region: target.region,
-  };
-}
-
-function sanitize(name: string): string {
-  return name.replace(/_/g, '-');
-}
-
-function toStackName(projectName: string, targetName: string): string {
-  return `AgentCore-${sanitize(projectName)}-${sanitize(targetName)}`;
-}
-
-// The vended CDK project compiles against the published @aws/agentcore-cdk schema
-// type, which may lag the CLI's own AgentCoreProjectSpec (e.g. payments, harnesses,
-// gateway fields). This alias documents each read of those not-yet-published fields.
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type SpecWithLatestFields = any;
-
-// Extract MCP configuration from the project spec. Gateway fields are stored in
-// agentcore.json but may not yet be on the published spec type, so they are read
-// off the loosened alias.
-function resolveMcpSpec(spec: SpecWithLatestFields) {
-  return spec.agentCoreGateways?.length
-    ? {
-        agentCoreGateways: spec.agentCoreGateways,
-        mcpRuntimeTools: spec.mcpRuntimeTools,
-        unassignedTargets: spec.unassignedTargets,
-      }
-    : undefined;
-}
-
-// Read non-S3 KB connector-config files and return their parsed contents keyed by
-// the data source's connectorConfigFile path. The L3 does not read files; it
-// expects these parsed connectorParameters verbatim.
-function resolveConnectorParametersByFile(
-  spec: SpecWithLatestFields,
-  projectRoot: string
-): Record<string, Record<string, unknown>> {
-  const connectorParametersByFile: Record<string, Record<string, unknown>> = {};
-  for (const kb of spec.knowledgeBases ?? []) {
-    for (const ds of kb.dataSources ?? []) {
-      if (ds.type !== 'S3' && ds.connectorConfigFile) {
-        const abs = path.resolve(projectRoot, ds.connectorConfigFile);
-        try {
-          connectorParametersByFile[ds.connectorConfigFile] = JSON.parse(fs.readFileSync(abs, 'utf-8'));
-        } catch (err) {
-          throw new Error(
-            `Could not read connector config '${ds.connectorConfigFile}' for knowledge base '${kb.name}' at ${abs}: ${err instanceof Error ? err.message : err}`
-          );
-        }
-      }
-    }
-  }
-  return connectorParametersByFile;
-}
-
-// Synthesize a HarnessConfig for each harness entry in the spec. The full validated
-// spec drives the AWS::BedrockAgentCore::Harness CFN resource; the role-scoped
-// fields drive the IAM role + container build.
-function resolveHarnessConfigs(spec: SpecWithLatestFields, projectRoot: string): HarnessConfig[] {
-  const harnessConfigs: HarnessConfig[] = [];
-  for (const entry of spec.harnesses ?? []) {
-    const harnessDir = path.resolve(projectRoot, entry.path);
-    const harnessPath = path.resolve(harnessDir, 'harness.json');
-    try {
-      const harnessSpec = HarnessSpecSchema.parse(JSON.parse(fs.readFileSync(harnessPath, 'utf-8')));
-      harnessConfigs.push({
-        name: entry.name,
-        executionRoleArn: harnessSpec.executionRoleArn,
-        // Only an `existing` memory ref carries a name to wire IAM against; managed memory is
-        // owned by the harness (no sibling) and disabled has none — both resolve to undefined.
-        memoryName: harnessSpec.memory?.mode === 'existing' ? harnessSpec.memory.name : undefined,
-        containerUri: harnessSpec.containerUri,
-        hasDockerfile: !!harnessSpec.dockerfile,
-        dockerfile: harnessSpec.dockerfile,
-        codeLocation: harnessSpec.dockerfile ? harnessDir : undefined,
-        tools: harnessSpec.tools,
-        skills: harnessSpec.skills,
-        apiKeyArn: harnessSpec.model?.apiKeyArn,
-        efsAccessPoints: harnessSpec.efsAccessPoints,
-        s3AccessPoints: harnessSpec.s3AccessPoints,
-        apiFormat: harnessSpec.model?.apiFormat,
-        // Full spec + dir drive the AWS::BedrockAgentCore::Harness CFN resource.
-        spec: harnessSpec,
-        harnessDir,
-      });
-    } catch (err) {
-      throw new Error(
-        `Could not read harness.json for "${entry.name}" at ${harnessPath}: ${err instanceof Error ? err.message : err}`
-      );
-    }
-  }
-  return harnessConfigs;
-}
-
-async function main() {
-  // Config root is parent of cdk/ directory. The CLI sets process.cwd() to agentcore/cdk/.
-  const configRoot = path.resolve(process.cwd(), '..');
-  const configIO = new ConfigIO({ baseDir: configRoot });
-
-  const spec = await configIO.readProjectSpec();
-  const targets = await configIO.readAWSDeploymentTargets();
-
-  // `project build` runs before a project has anywhere to deploy, so an empty target
-  // list is not an error: it synthesizes a single environment-agnostic stack, which is
-  // enough to typecheck the app and produce a template. Only a stack synthesized for a
-  // real target is a deploy candidate; the target tag below is what marks one.
-  const stackTargets: (AwsDeploymentTarget | undefined)[] = targets.length > 0 ? targets : [undefined];
-
-  const specAny: SpecWithLatestFields = spec;
-  const projectRoot = path.resolve(configRoot, '..');
-
-  const mcpSpec = resolveMcpSpec(specAny);
-  const connectorParametersByFile = resolveConnectorParametersByFile(specAny, projectRoot);
-  const harnessConfigs = resolveHarnessConfigs(specAny, projectRoot);
-
-  // Read deployed state for credential ARNs (populated by pre-deploy identity setup).
-  // Under agentcore/.cli/ to match the released CLI's location.
-  let deployedState: Record<string, unknown> | undefined;
-  try {
-    deployedState = JSON.parse(fs.readFileSync(path.join(configRoot, '.cli', 'deployed-state.json'), 'utf8'));
-  } catch (err) {
-    // A missing file is the normal first-deploy case. A malformed one is not:
-    // surface it rather than silently synthesizing without the credential ARNs
-    // it holds (which would drop them from the stack).
-    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
-  }
+import { App } from 'aws-cdk-lib';
+import { readAgentCoreProject, resolveTargetStacks, transformAgentCoreJson } from '@aws/agentcore-cdk';
+import { AgentCoreStack } from '../lib/cdk-stack';
 
+try {
+  // The AgentCore CLI runs this app from agentcore/cdk/; readAgentCoreProject walks up to agentcore/.
+  const project = readAgentCoreProject();
   const app = new App();
-
-  for (const target of stackTargets) {
-    // An environment-agnostic stack resolves its account and region from CloudFormation
-    // pseudo-parameters at deploy time instead of pinning them at synth time.
-    const env = target ? toEnvironment(target) : undefined;
-    const stackName = target ? toStackName(spec.name, target.name) : `AgentCore-${sanitize(spec.name)}`;
-
-    // Extract credentials from deployed state for this target
-    const targetState = (deployedState as Record<string, unknown>)?.targets as
-      Record<string, Record<string, unknown>> | undefined;
-    const targetResources = target
-      ? (targetState?.[target.name]?.resources as Record<string, unknown> | undefined)
-      : undefined;
-    const credentials = targetResources?.credentials as
-      Record<string, { credentialProviderArn: string; clientSecretArn?: string }> | undefined;
-
-    new AgentCoreStack(app, stackName, {
-      spec,
-      mcpSpec,
-      credentials,
-      connectorParametersByFile,
-      harnesses: harnessConfigs.length > 0 ? harnessConfigs : undefined,
-      env,
-      description: target
-        ? `AgentCore stack for ${spec.name} deployed to ${target.name} (${target.region})`
-        : `AgentCore stack for ${spec.name} (no deployment target configured)`,
-      // Only a stack synthesized for a real target carries the target tag, which is
-      // how deploy selects the stack to ship.
-      tags: {
-        'agentcore:project-name': spec.name,
-        ...(target ? { 'agentcore:target-name': target.name } : {}),
-      },
+  for (const stack of resolveTargetStacks({
+    projectName: project.projectName,
+    targets: project.targets,
+    deployedState: project.deployedState,
+  })) {
+    new AgentCoreStack(app, stack.stackName, {
+      env: stack.env,
+      tags: stack.tags,
+      description: stack.description,
+      application: transformAgentCoreJson(project.agentCoreJson, {
+        projectRoot: project.projectRoot,
+        credentials: stack.credentials,
+        target: stack.target,
+      }),
     });
   }
-
   app.synth();
-}
-
-main().catch((error: unknown) => {
+} catch (error) {
   console.error('AgentCore CDK synthesis failed:', error instanceof Error ? error.message : error);
   process.exit(1);
-});
+}