@aws/agentcore 0.15.0 → 0.17.0

package/README.md

@@ -194,6 +194,11 @@ Projects use JSON schema files in the `agentcore/` directory:
 - [Local Development](docs/local-development.md) - Dev server and debugging
 - [Feedback](docs/feedback.md) - Submit feedback from your terminal
 
+## Examples
+
+See the [AgentCore Samples](https://github.com/awslabs/agentcore-samples) repository for end-to-end examples using the
+CLI, including multi-agent workflows, MCP gateway targets, and framework integrations.
+
 ## Feedback & Issues
 
 Have a quick comment or suggestion? Send it from your terminal:

package/dist/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -99,6 +99,42 @@ async function main() {
     throw new Error('No deployment targets configured. Please define targets in agentcore/aws-targets.json');
   }
 
+  // Read harness configs for role creation.
+  const projectRoot = path.resolve(configRoot, '..');
+  const harnessConfigs: {
+    name: string;
+    executionRoleArn?: string;
+    memoryName?: string;
+    containerUri?: string;
+    hasDockerfile?: boolean;
+    dockerfile?: string;
+    codeLocation?: string;
+    tools?: { type: string; name: string }[];
+    apiKeyArn?: string;
+  }[] = [];
+  for (const entry of specAny.harnesses ?? []) {
+    const harnessDir = path.resolve(projectRoot, entry.path);
+    const harnessPath = path.resolve(harnessDir, 'harness.json');
+    try {
+      const harnessSpec = JSON.parse(fs.readFileSync(harnessPath, 'utf-8'));
+      harnessConfigs.push({
+        name: entry.name,
+        executionRoleArn: harnessSpec.executionRoleArn,
+        memoryName: harnessSpec.memory?.name,
+        containerUri: harnessSpec.containerUri,
+        hasDockerfile: !!harnessSpec.dockerfile,
+        dockerfile: harnessSpec.dockerfile,
+        codeLocation: harnessSpec.dockerfile ? harnessDir : undefined,
+        tools: harnessSpec.tools,
+        apiKeyArn: harnessSpec.model?.apiKeyArn,
+      });
+    } catch (err) {
+      throw new Error(
+        \`Could not read harness.json for "\${entry.name}" at \${harnessPath}: \${err instanceof Error ? err.message : err}\`
+      );
+    }
+  }
+
   const app = new App();
 
   for (const target of targets) {
@@ -118,6 +154,7 @@ async function main() {
       spec,
       mcpSpec,
       credentials,
+      harnesses: harnessConfigs.length > 0 ? harnessConfigs : undefined,
       env,
       description: \`AgentCore stack for \${spec.name} deployed to \${target.name} (\${target.region})\`,
       tags: {
@@ -265,6 +302,18 @@ exports[`Assets Directory Snapshots > CDK assets > cdk/cdk/lib/cdk-stack.ts shou
 import { CfnOutput, Stack, type StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 
+export interface HarnessConfig {
+  name: string;
+  executionRoleArn?: string;
+  memoryName?: string;
+  containerUri?: string;
+  hasDockerfile?: boolean;
+  dockerfile?: string;
+  codeLocation?: string;
+  tools?: { type: string; name: string }[];
+  apiKeyArn?: string;
+}
+
 export interface AgentCoreStackProps extends StackProps {
   /**
    * The AgentCore project specification containing agents, memories, and credentials.
@@ -278,6 +327,10 @@ export interface AgentCoreStackProps extends StackProps {
    * Credential provider ARNs from deployed state, keyed by credential name.
    */
   credentials?: Record<string, { credentialProviderArn: string; clientSecretArn?: string }>;
+  /**
+   * Harness role configurations.
+   */
+  harnesses?: HarnessConfig[];
 }
 
 /**
@@ -293,12 +346,15 @@ export class AgentCoreStack extends Stack {
   constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
     super(scope, id, props);
 
-    const { spec, mcpSpec, credentials } = props;
+    const { spec, mcpSpec, credentials, harnesses } = props;
 
-    // Create AgentCoreApplication with all agents
-    this.application = new AgentCoreApplication(this, 'Application', {
-      spec,
-    });
+    // Create AgentCoreApplication with all agents and harness roles
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const appProps: Record<string, unknown> = { spec };
+    if (harnesses?.length) {
+      appProps.harnesses = harnesses;
+    }
+    this.application = new AgentCoreApplication(this, 'Application', appProps as any);
 
     // Create AgentCoreMcp if there are gateways configured
     if (mcpSpec?.agentCoreGateways && mcpSpec.agentCoreGateways.length > 0) {
@@ -454,6 +510,7 @@ exports[`Assets Directory Snapshots > File listing > should match the expected f
   "evaluators/python-lambda/execution-role-policy.json",
   "evaluators/python-lambda/lambda_function.py",
   "evaluators/python-lambda/pyproject.toml",
+  "harness/invoke.py.template",
   "mcp/python-lambda/README.md",
   "mcp/python-lambda/handler.py",
   "mcp/python-lambda/pyproject.toml",
@@ -1185,7 +1242,7 @@ dependencies = [
     "aws-opentelemetry-distro",
     "bedrock-agentcore[a2a] >= 1.0.3",
     "google-adk >= 1.0.0, < 2.0.0",
-    "google-genai >= 1.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
 ]
 
 [tool.hatch.build.targets.wheel]
@@ -1546,6 +1603,7 @@ dependencies = [
     {{#if (eq modelProvider "Anthropic")}}"langchain-anthropic >= 0.3.0",
     {{/if}}{{#if (eq modelProvider "Bedrock")}}"langchain-aws >= 0.2.0",
     {{/if}}{{#if (eq modelProvider "Gemini")}}"langchain-google-genai >= 2.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     {{/if}}{{#if (eq modelProvider "OpenAI")}}"langchain-openai >= 0.2.0",
     {{/if}}"aws-opentelemetry-distro",
     "opentelemetry-instrumentation-langchain >= 0.59.0",
@@ -2133,7 +2191,7 @@ dependencies = [
     "bedrock-agentcore >= 1.0.3",
     "fastapi >= 0.115.12",
     "google-adk >= 1.16.0, < 2.0.0",
-    "google-genai >= 1.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     "opentelemetry-distro",
     "opentelemetry-exporter-otlp",
     "uvicorn >= 0.34.3",
@@ -2442,6 +2500,7 @@ dependencies = [
     {{#if (eq modelProvider "Anthropic")}}"langchain-anthropic >= 0.3.0",
     {{/if}}{{#if (eq modelProvider "Bedrock")}}"langchain-aws >= 0.2.0",
     {{/if}}{{#if (eq modelProvider "Gemini")}}"langchain-google-genai >= 2.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     {{/if}}{{#if (eq modelProvider "OpenAI")}}"langchain-openai >= 0.2.0",
     {{/if}}"aws-opentelemetry-distro",
     "opentelemetry-instrumentation-langchain >= 0.59.0",
@@ -3617,6 +3676,7 @@ dependencies = [
     "opentelemetry-distro",
     "opentelemetry-exporter-otlp",
     "google-adk >= 1.17.0, < 2.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     "bedrock-agentcore >= 1.0.3",
     "botocore[crt] >= 1.35.0",
     {{#if hasGateway}}{{#if (includes gatewayAuthTypes "AWS_IAM")}}"mcp-proxy-for-aws >= 1.1.0",
@@ -4145,6 +4205,7 @@ dependencies = [
 {{/if}}
 {{#if (eq modelProvider "Gemini")}}
     "langchain-google-genai >= 3.0.3",
+    "google-genai >= 1.0.0, < 2.0.0",
 {{/if}}
     {{#if hasGateway}}{{#if (includes gatewayAuthTypes "AWS_IAM")}}"mcp-proxy-for-aws >= 1.1.0",
     {{/if}}{{/if}}

package/dist/assets/__tests__/__snapshots__/dockerfile-render.test.ts.snap

@@ -1,7 +1,7 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
 exports[`Dockerfile enableOtel rendering > renders opentelemetry-instrument CMD when enableOtel is true > Dockerfile-enableOtel-true 1`] = `
-"FROM public.ecr.aws/docker/library/python:3.12-slim-bookworm
+"FROM public.ecr.aws/docker/library/python:3.12-slim-trixie
 
 RUN pip install --no-cache-dir uv
 
@@ -41,7 +41,7 @@ CMD ["opentelemetry-instrument", "python", "-m", "main"]
 `;
 
 exports[`Dockerfile enableOtel rendering > renders plain python CMD when enableOtel is false > Dockerfile-enableOtel-false 1`] = `
-"FROM public.ecr.aws/docker/library/python:3.12-slim-bookworm
+"FROM public.ecr.aws/docker/library/python:3.12-slim-trixie
 
 RUN pip install --no-cache-dir uv
 

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

@@ -54,6 +54,42 @@ async function main() {
     throw new Error('No deployment targets configured. Please define targets in agentcore/aws-targets.json');
   }
 
+  // Read harness configs for role creation.
+  const projectRoot = path.resolve(configRoot, '..');
+  const harnessConfigs: {
+    name: string;
+    executionRoleArn?: string;
+    memoryName?: string;
+    containerUri?: string;
+    hasDockerfile?: boolean;
+    dockerfile?: string;
+    codeLocation?: string;
+    tools?: { type: string; name: string }[];
+    apiKeyArn?: string;
+  }[] = [];
+  for (const entry of specAny.harnesses ?? []) {
+    const harnessDir = path.resolve(projectRoot, entry.path);
+    const harnessPath = path.resolve(harnessDir, 'harness.json');
+    try {
+      const harnessSpec = JSON.parse(fs.readFileSync(harnessPath, 'utf-8'));
+      harnessConfigs.push({
+        name: entry.name,
+        executionRoleArn: harnessSpec.executionRoleArn,
+        memoryName: harnessSpec.memory?.name,
+        containerUri: harnessSpec.containerUri,
+        hasDockerfile: !!harnessSpec.dockerfile,
+        dockerfile: harnessSpec.dockerfile,
+        codeLocation: harnessSpec.dockerfile ? harnessDir : undefined,
+        tools: harnessSpec.tools,
+        apiKeyArn: harnessSpec.model?.apiKeyArn,
+      });
+    } catch (err) {
+      throw new Error(
+        `Could not read harness.json for "${entry.name}" at ${harnessPath}: ${err instanceof Error ? err.message : err}`
+      );
+    }
+  }
+
   const app = new App();
 
   for (const target of targets) {
@@ -73,6 +109,7 @@ async function main() {
       spec,
       mcpSpec,
       credentials,
+      harnesses: harnessConfigs.length > 0 ? harnessConfigs : undefined,
       env,
       description: `AgentCore stack for ${spec.name} deployed to ${target.name} (${target.region})`,
       tags: {

package/dist/assets/cdk/lib/cdk-stack.ts

@@ -7,6 +7,18 @@ import {
 import { CfnOutput, Stack, type StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
 
+export interface HarnessConfig {
+  name: string;
+  executionRoleArn?: string;
+  memoryName?: string;
+  containerUri?: string;
+  hasDockerfile?: boolean;
+  dockerfile?: string;
+  codeLocation?: string;
+  tools?: { type: string; name: string }[];
+  apiKeyArn?: string;
+}
+
 export interface AgentCoreStackProps extends StackProps {
   /**
    * The AgentCore project specification containing agents, memories, and credentials.
@@ -20,6 +32,10 @@ export interface AgentCoreStackProps extends StackProps {
    * Credential provider ARNs from deployed state, keyed by credential name.
    */
   credentials?: Record<string, { credentialProviderArn: string; clientSecretArn?: string }>;
+  /**
+   * Harness role configurations.
+   */
+  harnesses?: HarnessConfig[];
 }
 
 /**
@@ -35,12 +51,15 @@ export class AgentCoreStack extends Stack {
   constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
     super(scope, id, props);
 
-    const { spec, mcpSpec, credentials } = props;
+    const { spec, mcpSpec, credentials, harnesses } = props;
 
-    // Create AgentCoreApplication with all agents
-    this.application = new AgentCoreApplication(this, 'Application', {
-      spec,
-    });
+    // Create AgentCoreApplication with all agents and harness roles
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const appProps: Record<string, unknown> = { spec };
+    if (harnesses?.length) {
+      appProps.harnesses = harnesses;
+    }
+    this.application = new AgentCoreApplication(this, 'Application', appProps as any);
 
     // Create AgentCoreMcp if there are gateways configured
     if (mcpSpec?.agentCoreGateways && mcpSpec.agentCoreGateways.length > 0) {

package/dist/assets/container/python/Dockerfile

@@ -1,4 +1,4 @@
-FROM public.ecr.aws/docker/library/python:3.12-slim-bookworm
+FROM public.ecr.aws/docker/library/python:3.12-slim-trixie
 
 RUN pip install --no-cache-dir uv
 

package/dist/assets/harness/invoke.py.template

@@ -0,0 +1,74 @@
+"""
+Standalone invoke script for AgentCore Harness.
+Generated by: agentcore create --with-invoke-script
+
+Usage:
+  pip install boto3
+  export HARNESS_ARN="arn:aws:bedrock-agentcore:<region>:<account>:harness/<harness-id>"
+  python invoke.py "Hello, what can you do?"
+  python invoke.py --raw-events "Hello"
+"""
+
+import argparse
+import json
+import os
+import sys
+import uuid
+
+import boto3
+
+# --- Configuration ---
+HARNESS_ARN = os.environ.get("HARNESS_ARN", "{{HARNESS_ARN}}")
+REGION = os.environ.get("AWS_REGION", "{{REGION}}")
+SESSION_ID = os.environ.get("SESSION_ID", str(uuid.uuid4()))
+
+parser = argparse.ArgumentParser(description="Invoke an AgentCore Harness")
+parser.add_argument("prompt", nargs="?", default="Hello!", help="Prompt to send to the agent")
+parser.add_argument("--raw-events", action="store_true", help="Print raw streaming events as JSON")
+parser.add_argument("--session-id", default=SESSION_ID, help="Session ID for conversation continuity")
+args = parser.parse_args()
+
+client = boto3.client("bedrock-agentcore", region_name=REGION)
+
+response = client.invoke_harness(
+    harnessArn=HARNESS_ARN,
+    runtimeSessionId=args.session_id,
+    messages=[
+        {
+            "role": "user",
+            "content": [{"text": args.prompt}],
+        }
+    ],
+)
+
+for event in response["stream"]:
+    if args.raw_events:
+        print(json.dumps(event, default=str))
+    else:
+        if "contentBlockStart" in event:
+            start = event["contentBlockStart"].get("start", {})
+            if "toolUse" in start:
+                tool = start["toolUse"]
+                print(f"\n🔧 Tool: {tool.get('name', 'unknown')}", flush=True)
+        elif "contentBlockDelta" in event:
+            delta = event["contentBlockDelta"].get("delta", {})
+            if "text" in delta:
+                print(delta["text"], end="", flush=True)
+        elif "messageStop" in event:
+            stop_reason = event["messageStop"].get("stopReason", "")
+            if stop_reason == "end_turn":
+                print()
+        elif "metadata" in event:
+            usage = event["metadata"].get("usage", {})
+            metrics = event["metadata"].get("metrics", {})
+            latency = metrics.get("latencyMs", 0) / 1000
+            print(
+                f"\n⚡ {usage.get('inputTokens', 0)} in · "
+                f"{usage.get('outputTokens', 0)} out · "
+                f"{latency:.1f}s",
+                file=sys.stderr,
+            )
+        elif "internalServerException" in event:
+            print(f"\nError: {event['internalServerException']}", file=sys.stderr)
+
+print(f"\n🔗 Session: {args.session_id}", file=sys.stderr)

package/dist/assets/python/a2a/googleadk/base/pyproject.toml

@@ -13,7 +13,7 @@ dependencies = [
     "aws-opentelemetry-distro",
     "bedrock-agentcore[a2a] >= 1.0.3",
     "google-adk >= 1.0.0, < 2.0.0",
-    "google-genai >= 1.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
 ]
 
 [tool.hatch.build.targets.wheel]

package/dist/assets/python/a2a/langchain_langgraph/base/pyproject.toml

@@ -13,6 +13,7 @@ dependencies = [
     {{#if (eq modelProvider "Anthropic")}}"langchain-anthropic >= 0.3.0",
     {{/if}}{{#if (eq modelProvider "Bedrock")}}"langchain-aws >= 0.2.0",
     {{/if}}{{#if (eq modelProvider "Gemini")}}"langchain-google-genai >= 2.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     {{/if}}{{#if (eq modelProvider "OpenAI")}}"langchain-openai >= 0.2.0",
     {{/if}}"aws-opentelemetry-distro",
     "opentelemetry-instrumentation-langchain >= 0.59.0",

package/dist/assets/python/agui/googleadk/base/pyproject.toml

@@ -14,7 +14,7 @@ dependencies = [
     "bedrock-agentcore >= 1.0.3",
     "fastapi >= 0.115.12",
     "google-adk >= 1.16.0, < 2.0.0",
-    "google-genai >= 1.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     "opentelemetry-distro",
     "opentelemetry-exporter-otlp",
     "uvicorn >= 0.34.3",

package/dist/assets/python/agui/langchain_langgraph/base/pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     {{#if (eq modelProvider "Anthropic")}}"langchain-anthropic >= 0.3.0",
     {{/if}}{{#if (eq modelProvider "Bedrock")}}"langchain-aws >= 0.2.0",
     {{/if}}{{#if (eq modelProvider "Gemini")}}"langchain-google-genai >= 2.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     {{/if}}{{#if (eq modelProvider "OpenAI")}}"langchain-openai >= 0.2.0",
     {{/if}}"aws-opentelemetry-distro",
     "opentelemetry-instrumentation-langchain >= 0.59.0",

package/dist/assets/python/http/googleadk/base/pyproject.toml

@@ -12,6 +12,7 @@ dependencies = [
     "opentelemetry-distro",
     "opentelemetry-exporter-otlp",
     "google-adk >= 1.17.0, < 2.0.0",
+    "google-genai >= 1.0.0, < 2.0.0",
     "bedrock-agentcore >= 1.0.3",
     "botocore[crt] >= 1.35.0",
     {{#if hasGateway}}{{#if (includes gatewayAuthTypes "AWS_IAM")}}"mcp-proxy-for-aws >= 1.1.0",

package/dist/assets/python/http/langchain_langgraph/base/pyproject.toml

@@ -28,6 +28,7 @@ dependencies = [
 {{/if}}
 {{#if (eq modelProvider "Gemini")}}
     "langchain-google-genai >= 3.0.3",
+    "google-genai >= 1.0.0, < 2.0.0",
 {{/if}}
     {{#if hasGateway}}{{#if (includes gatewayAuthTypes "AWS_IAM")}}"mcp-proxy-for-aws >= 1.1.0",
     {{/if}}{{/if}}