@aws/agentcore 1.0.0-preview.9 → 1.0.0-rc.1

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

@@ -1,77 +0,0 @@
-// 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 ghcr.io/astral-sh/uv:python3.12-bookworm-slim
-
-ARG UV_DEFAULT_INDEX
-ARG UV_INDEX
-
-WORKDIR /app
-
-ENV UV_SYSTEM_PYTHON=1 \\
-    UV_COMPILE_BYTECODE=1 \\
-    UV_NO_PROGRESS=1 \\
-    PYTHONUNBUFFERED=1 \\
-    DOCKER_CONTAINER=1 \\
-    UV_DEFAULT_INDEX=\${UV_DEFAULT_INDEX} \\
-    UV_INDEX=\${UV_INDEX} \\
-    PATH="/app/.venv/bin:$PATH"
-
-RUN useradd -m -u 1000 bedrock_agentcore
-
-COPY pyproject.toml uv.lock ./
-RUN uv sync --frozen --no-dev --no-install-project
-
-COPY --chown=bedrock_agentcore:bedrock_agentcore . .
-RUN uv sync --frozen --no-dev
-
-USER bedrock_agentcore
-
-# AgentCore Runtime service contract ports
-# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html
-# 8080: HTTP Mode
-# 8000: MCP Mode
-# 9000: A2A Mode
-EXPOSE 8080 8000 9000
-
-CMD ["opentelemetry-instrument", "python", "-m", "main"]
-"
-`;
-
-exports[`Dockerfile enableOtel rendering > renders plain python CMD when enableOtel is false > Dockerfile-enableOtel-false 1`] = `
-"FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
-
-ARG UV_DEFAULT_INDEX
-ARG UV_INDEX
-
-WORKDIR /app
-
-ENV UV_SYSTEM_PYTHON=1 \\
-    UV_COMPILE_BYTECODE=1 \\
-    UV_NO_PROGRESS=1 \\
-    PYTHONUNBUFFERED=1 \\
-    DOCKER_CONTAINER=1 \\
-    UV_DEFAULT_INDEX=\${UV_DEFAULT_INDEX} \\
-    UV_INDEX=\${UV_INDEX} \\
-    PATH="/app/.venv/bin:$PATH"
-
-RUN useradd -m -u 1000 bedrock_agentcore
-
-COPY pyproject.toml uv.lock ./
-RUN uv sync --frozen --no-dev --no-install-project
-
-COPY --chown=bedrock_agentcore:bedrock_agentcore . .
-RUN uv sync --frozen --no-dev
-
-USER bedrock_agentcore
-
-# AgentCore Runtime service contract ports
-# https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html
-# 8080: HTTP Mode
-# 8000: MCP Mode
-# 9000: A2A Mode
-EXPOSE 8080 8000 9000
-
-CMD ["python", "-m", "main"]
-"
-`;

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

@@ -1,125 +0,0 @@
-/**
- * Snapshot tests for the assets directory.
- *
- * These tests ensure that template files vended to users don't change unexpectedly.
- * If you intentionally change an asset file, update snapshots with:
- *
- *   npm run test:snapshots:update
- *
- * See docs/TESTING.md for more information.
- */
-import * as fs from 'fs';
-import * as path from 'path';
-import { describe, expect, it } from 'vitest';
-
-const ASSETS_DIR = path.resolve(__dirname, '..');
-
-/**
- * Recursively get all files in a directory
- */
-function getAllFiles(dir: string, baseDir: string = dir): string[] {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  const files: string[] = [];
-
-  for (const entry of entries) {
-    const fullPath = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      // Skip __tests__ directory to avoid circular snapshots
-      if (entry.name === '__tests__' || entry.name === '__snapshots__') {
-        continue;
-      }
-      files.push(...getAllFiles(fullPath, baseDir));
-    } else {
-      // Get relative path from assets dir for cleaner snapshot names
-      const relativePath = path.relative(baseDir, fullPath);
-      files.push(relativePath);
-    }
-  }
-
-  return files.sort();
-}
-
-/**
- * Read file content, handling binary files gracefully
- */
-function readFileContent(filePath: string): string {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  return content;
-}
-
-describe('Assets Directory Snapshots', () => {
-  const assetFiles = getAllFiles(ASSETS_DIR);
-
-  it('should have asset files to test', () => {
-    expect(assetFiles.length).toBeGreaterThan(0);
-  });
-
-  describe('File listing', () => {
-    it('should match the expected file structure', () => {
-      expect(assetFiles).toMatchSnapshot('asset-file-listing');
-    });
-  });
-
-  describe('CDK assets', () => {
-    const cdkFiles = assetFiles.filter(f => f.startsWith('cdk/'));
-
-    it.each(cdkFiles)('cdk/%s should match snapshot', file => {
-      const content = readFileContent(path.join(ASSETS_DIR, file));
-      expect(content).toMatchSnapshot();
-    });
-  });
-
-  describe('Python framework assets', () => {
-    const pythonFiles = assetFiles.filter(f => f.startsWith('python/'));
-
-    it.each(pythonFiles)('python/%s should match snapshot', file => {
-      const content = readFileContent(path.join(ASSETS_DIR, file));
-      expect(content).toMatchSnapshot();
-    });
-  });
-
-  describe('MCP assets', () => {
-    const mcpFiles = assetFiles.filter(f => f.startsWith('mcp/'));
-
-    it.each(mcpFiles)('mcp/%s should match snapshot', file => {
-      const content = readFileContent(path.join(ASSETS_DIR, file));
-      expect(content).toMatchSnapshot();
-    });
-  });
-
-  describe.skipIf(assetFiles.filter(f => f.startsWith('static/')).length === 0)('Static assets', () => {
-    const staticFiles = assetFiles.filter(f => f.startsWith('static/'));
-
-    it.each(staticFiles)('static/%s should match snapshot', file => {
-      const content = readFileContent(path.join(ASSETS_DIR, file));
-      expect(content).toMatchSnapshot();
-    });
-  });
-
-  describe.skipIf(assetFiles.filter(f => f.startsWith('typescript/')).length === 0)('TypeScript assets', () => {
-    const tsFiles = assetFiles.filter(f => f.startsWith('typescript/'));
-
-    it.each(tsFiles)('typescript/%s should match snapshot', file => {
-      const content = readFileContent(path.join(ASSETS_DIR, file));
-      expect(content).toMatchSnapshot();
-    });
-  });
-
-  describe('Root-level assets', () => {
-    const rootFiles = assetFiles.filter(
-      f =>
-        !f.includes('/') ||
-        (f.startsWith('agents/') &&
-          !f.startsWith('cdk/') &&
-          !f.startsWith('python/') &&
-          !f.startsWith('mcp/') &&
-          !f.startsWith('static/') &&
-          !f.startsWith('typescript/'))
-    );
-
-    it.each(rootFiles)('%s should match snapshot', file => {
-      const content = readFileContent(path.join(ASSETS_DIR, file));
-      expect(content).toMatchSnapshot();
-    });
-  });
-});

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

@@ -1,24 +0,0 @@
-import * as fs from 'fs';
-import Handlebars from 'handlebars';
-import * as path from 'path';
-import { describe, expect, it } from 'vitest';
-
-const DOCKERFILE_PATH = path.resolve(__dirname, '..', 'container', 'python', 'Dockerfile');
-
-describe('Dockerfile enableOtel rendering', () => {
-  const template = Handlebars.compile(fs.readFileSync(DOCKERFILE_PATH, 'utf-8'));
-
-  it('renders opentelemetry-instrument CMD when enableOtel is true', () => {
-    const rendered = template({ entrypoint: 'main', enableOtel: true });
-    expect(rendered).toMatchSnapshot('Dockerfile-enableOtel-true');
-    expect(rendered).toContain('opentelemetry-instrument');
-    expect(rendered).not.toContain('CMD ["python", "-m"');
-  });
-
-  it('renders plain python CMD when enableOtel is false', () => {
-    const rendered = template({ entrypoint: 'main', enableOtel: false });
-    expect(rendered).toMatchSnapshot('Dockerfile-enableOtel-false');
-    expect(rendered).toContain('CMD ["python", "-m"');
-    expect(rendered).not.toContain('opentelemetry-instrument');
-  });
-});

package/dist/assets/agents/AGENTS.md

@@ -1,141 +0,0 @@
-# AgentCore Project
-
-This project contains configuration and infrastructure for an Amazon Bedrock AgentCore application.
-
-The `agentcore/` directory is a declarative model of the project. The `agentcore/cdk/` subdirectory uses the
-`@aws/agentcore-cdk` L3 constructs to deploy the configuration to AWS.
-
-## Mental Model
-
-The project uses a **flat resource model**. Agents, memories, credentials, gateways, evaluators, and policies are
-independent top-level arrays in `agentcore.json`. There is no binding between resources in the schema — each resource is
-provisioned independently. Agents discover memories and credentials at runtime via environment variables or SDK calls.
-Tags defined in `agentcore.json` flow through to deployed CloudFormation resources.
-
-## Critical Invariants
-
-1. **Schema-First Authority:** The `.json` files are the source of truth. Do not modify agent behavior by editing
-   generated CDK code in `cdk/`.
-2. **Resource Identity:** The `name` field determines the CloudFormation Logical ID.
-   - **Renaming** a resource will **destroy and recreate** it.
-   - **Modifying** other fields will update the resource **in-place**.
-3. **Schema Validation:** If your JSON conforms to the types in `.llm-context/`, it will deploy successfully. Run
-   `agentcore validate` to check.
-4. **Resource Removal:** Use `agentcore remove` to remove resources. Run `agentcore deploy` after removal to tear down
-   deployed infrastructure.
-
-## Directory Structure
-
-```
-myProject/
-├── AGENTS.md               # This file — AI coding assistant context
-├── agentcore/
-│   ├── agentcore.json      # Main project config (AgentCoreProjectSpec)
-│   ├── aws-targets.json    # Deployment targets (account + region)
-│   ├── .env.local          # Secrets — API keys (gitignored)
-│   ├── .llm-context/       # TypeScript type definitions for AI assistants
-│   │   ├── README.md       # Guide to using schema files
-│   │   ├── agentcore.ts    # AgentCoreProjectSpec types
-│   │   ├── aws-targets.ts  # AWS deployment target types
-│   │   └── mcp.ts          # Gateway and MCP tool types
-│   └── cdk/                # AWS CDK project (@aws/agentcore-cdk L3 constructs)
-├── app/                    # Agent application code
-└── evaluators/             # Custom evaluator code (if any)
-```
-
-## Schema Reference
-
-The `agentcore/.llm-context/` directory contains TypeScript type definitions optimized for AI coding assistants. Each
-file maps to a JSON config file and includes validation constraints as comments (`@regex`, `@min`, `@max`).
-
-| JSON Config | Schema File | Root Type |
-| --- | --- | --- |
-| `agentcore/agentcore.json` | `agentcore/.llm-context/agentcore.ts` | `AgentCoreProjectSpec` |
-| `agentcore/agentcore.json` (gateways) | `agentcore/.llm-context/mcp.ts` | `AgentCoreMcpSpec` |
-| `agentcore/aws-targets.json` | `agentcore/.llm-context/aws-targets.ts` | `AwsDeploymentTarget[]` |
-
-### Key Types
-
-- **AgentCoreProjectSpec**: Root config with `runtimes`, `memories`, `credentials`, `agentCoreGateways`, `evaluators`, `onlineEvalConfigs`, `policyEngines` arrays
-- **AgentEnvSpec**: Agent configuration (build type, entrypoint, code location, runtime version, network mode)
-- **Memory**: Memory resource with strategies (SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC) and expiry
-- **Credential**: API key or OAuth credential provider
-- **AgentCoreGateway**: MCP gateway with targets (Lambda, MCP server, OpenAPI, Smithy, API Gateway)
-- **Evaluator**: LLM-as-a-Judge or code-based evaluator
-- **OnlineEvalConfig**: Continuous evaluation pipeline bound to an agent
-
-### Common Enum Values
-
-- **BuildType**: `'CodeZip'` | `'Container'`
-- **NetworkMode**: `'PUBLIC'` | `'VPC'`
-- **RuntimeVersion**: `'PYTHON_3_10'` | `'PYTHON_3_11'` | `'PYTHON_3_12'` | `'PYTHON_3_13'` | `'PYTHON_3_14'` | `'NODE_18'` | `'NODE_20'` | `'NODE_22'`
-- **MemoryStrategyType**: `'SEMANTIC'` | `'SUMMARIZATION'` | `'USER_PREFERENCE'` | `'EPISODIC'`
-- **GatewayTargetType**: `'lambda'` | `'mcpServer'` | `'openApiSchema'` | `'smithyModel'` | `'apiGateway'` | `'lambdaFunctionArn'`
-- **ModelProvider**: `'Bedrock'` | `'Gemini'` | `'OpenAI'` | `'Anthropic'`
-
-### Build Types
-
-- **CodeZip**: Python source packaged as a zip and deployed directly to AgentCore Runtime.
-- **Container**: Docker image built in CodeBuild (ARM64), pushed to a per-agent ECR repository. Requires a `Dockerfile`
-  in the agent's `codeLocation` directory. For local development (`agentcore dev`), the container is built and run
-  locally with volume-mounted hot-reload.
-
-### Supported Frameworks (for template agents)
-
-- **Strands** — Bedrock, Anthropic, OpenAI, Gemini
-- **LangChain/LangGraph** — Bedrock, Anthropic, OpenAI, Gemini
-- **GoogleADK** — Gemini
-- **OpenAI Agents** — OpenAI
-- **Autogen** — Bedrock, Anthropic, OpenAI, Gemini
-
-### Protocols
-
-- **HTTP** — Standard HTTP agent endpoint
-- **MCP** — Model Context Protocol server
-- **A2A** — Agent-to-Agent protocol (Google A2A)
-
-## Deployment
-
-Deployments are orchestrated through the CLI:
-
-```bash
-agentcore deploy    # Synthesizes CDK and deploys to AWS
-agentcore status    # Shows deployment status
-```
-
-Alternatively, deploy directly via CDK:
-
-```bash
-cd agentcore/cdk
-npm install
-npx cdk synth
-npx cdk deploy
-```
-
-## Editing Schemas
-
-When modifying JSON config files:
-
-1. Read the corresponding `agentcore/.llm-context/*.ts` file for type definitions
-2. Check validation constraint comments (`@regex`, `@min`, `@max`)
-3. Use exact enum values as string literals
-4. Use CloudFormation-safe names (alphanumeric, start with letter)
-5. Run `agentcore validate` to verify changes
-
-## CLI Commands
-
-| Command | Description |
-| --- | --- |
-| `agentcore create` | Create a new project |
-| `agentcore add <resource>` | Add agent, memory, credential, gateway, evaluator, policy |
-| `agentcore remove <resource>` | Remove a resource |
-| `agentcore dev` | Run agent locally with hot-reload |
-| `agentcore deploy` | Deploy to AWS |
-| `agentcore status` | Show deployment status |
-| `agentcore invoke` | Invoke agent (local or deployed) |
-| `agentcore logs` | View agent logs |
-| `agentcore traces` | View agent traces |
-| `agentcore eval` | Run evaluations against an agent |
-| `agentcore package` | Package agent artifacts |
-| `agentcore validate` | Validate configuration |
-| `agentcore pause` / `resume` | Pause or resume a deployed agent |

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

@@ -1,74 +0,0 @@
-"""
-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/mcp/python/README.md

@@ -1,27 +0,0 @@
-# {{ name }}
-
-This is a template MCP server generated by the AgentCore CLI.
-
-Demonstrates HTTP tool patterns with proper error handling and retry logic.
-
-## Quick Start
-
-```bash
-# Create and activate virtual environment
-uv venv
-source .venv/bin/activate  # or .venv\Scripts\activate on Windows
-
-# Install dependencies
-uv sync
-
-# Run the server
-uv run server.py
-```
-
-## Available Tools
-
-| Tool              | Description                                            |
-| ----------------- | ------------------------------------------------------ |
-| `lookup_ip`       | Look up geolocation and network info for an IP address |
-| `get_random_user` | Generate a random user profile for testing             |
-| `fetch_post`      | Fetch a post by ID from JSONPlaceholder API            |

package/dist/assets/mcp/python/pyproject.toml

@@ -1,22 +0,0 @@
-[build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[project]
-name = "{{ name }}"
-version = "0.1.0"
-description = "MCP Server demonstrating HTTP tool patterns"
-readme = "README.md"
-requires-python = ">=3.10"
-dependencies = [
-    "mcp[cli] >= 1.2.0",
-    "httpx >= 0.27.0",
-    "opentelemetry-distro",
-    "opentelemetry-exporter-otlp",
-]
-
-[project.scripts]
-server = "server:main"
-
-[tool.hatch.build.targets.wheel]
-packages = ["."]

package/dist/assets/mcp/python/server.py

@@ -1,117 +0,0 @@
-"""
-MCP Server demonstrating HTTP tool patterns.
-
-This template shows:
-- Async HTTP boundaries with proper error handling
-- Retry logic and partial failure
-- Response parsing and validation
-
-Run with: uv run server.py
-"""
-
-import logging
-from typing import Any
-
-import httpx
-from mcp.server.fastmcp import FastMCP
-
-logging.basicConfig(level=logging.INFO, format="%(levelname)s - %(message)s")
-logger = logging.getLogger(__name__)
-
-mcp = FastMCP("tools")
-
-HTTP_TIMEOUT = 10.0
-MAX_RETRIES = 2
-
-
-async def fetch_json(url: str, headers: dict[str, str] | None = None) -> dict[str, Any] | None:
-    """Make an HTTP GET request with retry logic."""
-    async with httpx.AsyncClient() as client:
-        for attempt in range(MAX_RETRIES):
-            try:
-                response = await client.get(url, headers=headers, timeout=HTTP_TIMEOUT)
-                response.raise_for_status()
-                return response.json()
-            except httpx.TimeoutException:
-                logger.warning(f"Timeout on attempt {attempt + 1} for {url}")
-            except httpx.HTTPStatusError as e:
-                logger.error(f"HTTP {e.response.status_code} for {url}")
-                return None
-            except httpx.RequestError as e:
-                logger.error(f"Request failed: {e}")
-                return None
-    return None
-
-
-@mcp.tool()
-async def lookup_ip(ip_address: str) -> str:
-    """Look up geolocation and network info for an IP address.
-
-    Args:
-        ip_address: IPv4 or IPv6 address to look up
-    """
-    data = await fetch_json(f"http://ip-api.com/json/{ip_address}")
-
-    if not data:
-        return f"Failed to look up IP: {ip_address}"
-
-    if data.get("status") == "fail":
-        return f"Lookup failed: {data.get('message', 'unknown error')}"
-
-    return (
-        f"IP: {data['query']}\n"
-        f"Location: {data['city']}, {data['regionName']}, {data['country']}\n"
-        f"ISP: {data['isp']}\n"
-        f"Organization: {data['org']}\n"
-        f"Timezone: {data['timezone']}"
-    )
-
-
-@mcp.tool()
-async def get_random_user() -> str:
-    """Generate a random user profile for testing or mock data."""
-    data = await fetch_json("https://randomuser.me/api/")
-
-    if not data or "results" not in data:
-        return "Failed to generate random user."
-
-    user = data["results"][0]
-    name = user["name"]
-    location = user["location"]
-
-    return (
-        f"Name: {name['first']} {name['last']}\n"
-        f"Email: {user['email']}\n"
-        f"Location: {location['city']}, {location['country']}\n"
-        f"Phone: {user['phone']}"
-    )
-
-
-@mcp.tool()
-async def fetch_post(post_id: int) -> str:
-    """Fetch a post by ID from JSONPlaceholder API.
-
-    Args:
-        post_id: The post ID (1-100)
-    """
-    if not 1 <= post_id <= 100:
-        return "Post ID must be between 1 and 100."
-
-    data = await fetch_json(f"https://jsonplaceholder.typicode.com/posts/{post_id}")
-
-    if not data:
-        return f"Failed to fetch post {post_id}."
-
-    return (
-        f"Post #{data['id']}\n"
-        f"Title: {data['title']}\n\n"
-        f"{data['body']}"
-    )
-
-
-def main():
-    mcp.run(transport="stdio")
-
-
-if __name__ == "__main__":
-    main()

package/dist/assets/mcp/python-lambda/README.md

@@ -1,22 +0,0 @@
-# {{ Name }}
-
-Lambda-based tools for AgentCore Gateway.
-
-## Tools
-
-- `lookup_ip` - Look up geolocation for an IP address
-- `get_random_user` - Generate random user profile
-- `fetch_post` - Fetch a post by ID
-
-## Gateway Integration
-
-Tools are invoked via AgentCore Gateway. The tool name is passed in:
-`context.client_context.custom["bedrockAgentCoreToolName"]`
-
-Format: `{target_name}___{tool_name}`
-
-## Adding New Tools
-
-1. Define the tool function with the `@tool("tool_name")` decorator
-2. Add the tool definition to `mcp-defs.json` in your agentcore project
-3. The tool will be automatically routed by the handler