feat: AgentCore CDK construct with built-in agent template

[aakash-cddo]

Summary

• Adds a new AgentCore CDK construct that deploys an Amazon Bedrock AgentCore runtime with short-term memory, IAM permissions, and observability pre-configured
• Ships a built-in agent template so consumers can deploy a working conversational agent without copying any code — just configure via props
• Follows the same patterns as the existing WebApp construct (props dataclass, __init__.py exports, no "Stack" suffix)

What

CDK Construct (agent_core/)

• props.py — AgentCoreProperties dataclass with two typed agent modes and sensible defaults. Only runtime_name is required:
  • BuiltInAgent — use the built-in template; configure via ModelConfig (model ID, token limits, thinking budget) and system prompt
  • CustomAgent — bring your own agent code directory; the construct automatically injects REGION, MODEL_ID, and MEMORY_ID
  • MemoryConfig — typed memory store config (set to None to skip creation)
  • ModelConfig — synth-time validated model config (enforces budget_tokens < max_tokens)
• stack.py — AgentCore construct that provisions:
  • AgentCore Runtime (container-based)
  • Short-term Memory store (optional)
  • Scoped IAM permissions (Bedrock invoke, memory, CloudWatch logs, X-Ray tracing, Application Signals, AgentCore identity)
• __init__.py — exports AgentCore, AgentCoreProperties, BuiltInAgent, CustomAgent, ModelConfig, and MemoryConfig

Agent Template (agent_core/agent_template/)

A complete, runnable agent built into a Docker image by CDK:

• agent.py — Strands-based conversational agent with streaming, extended thinking, and session memory via AgentCore Memory Store
• _config.py — frozen Config dataclass that loads all runtime configuration from environment variables
• _logging.py — structured JSON logging for CloudWatch
• _metrics.py — token usage extraction and OpenTelemetry span recording
• _streaming.py — stream event parsing helpers
• Dockerfile — slim Python 3.13 image with uv, non-root user
• default_system_prompt.md — minimal starting prompt

Tests

• tests/agent_core/test_props.py — unit tests for all props dataclasses and validation logic (including ModelConfig constraint enforcement)
• tests/agent_core/test_stack.py — CDK synth tests covering the full construct, IAM permissions, memory config, and custom agent mode; tests structured as functions (not classes)
• tests/fixtures/fake_agent/Dockerfile — minimal test fixture for the custom agent code path

Other

• README.md — AgentCore section with quick start, full props table, and custom agent code instructions
• pyproject.toml — added aws-cdk-aws-bedrock-agentcore-alpha dependency; excluded agent_template/ from host ruff (it has its own runtime context)

Usage

Zero-config

from gds_idea_cdk_constructs.agent_core import AgentCore, AgentCoreProperties

AgentCore(app, "MyAgent", props=AgentCoreProperties(runtime_name="my-agent"))

Configured (built-in agent)

from gds_idea_cdk_constructs.agent_core import AgentCore, AgentCoreProperties, BuiltInAgent, ModelConfig

AgentCore(
    app, "MyAgent",
    props=AgentCoreProperties(
        runtime_name="my-data-agent",
        agent=BuiltInAgent(
            model=ModelConfig(max_tokens=16000, budget_tokens=8000),
            system_prompt="You are a helpful analyst.",
        ),
        memory=MemoryConfig(name="my-memory"),
    ),
)

Custom agent code

from gds_idea_cdk_constructs.agent_core import AgentCore, AgentCoreProperties, CustomAgent

AgentCore(
    app, "MyAgent",
    props=AgentCoreProperties(
        runtime_name="my-agent",
        agent=CustomAgent(agent_code_directory="my_agent_code/"),
    ),
)