agentkit-aws-cdk

README

AgentKit for AWS CDK

AWS CDK constructs for deploying agentkit-based agents to AWS Bedrock AgentCore.

Features

• 🚀 AgentCore Runtime creation - Full AWS::BedrockAgentCore::Runtime resource support
• 🔗 Runtime Endpoint creation - Automatic AWS::BedrockAgentCore::RuntimeEndpoint for each agent
• 📡 Protocol configuration - HTTP, MCP, and A2A protocol support
• 🌐 Gateway support - Optional AWS::BedrockAgentCore::Gateway for external tool integration
• 📊 Enhanced outputs - Runtime ARNs, IDs, Endpoint ARNs per agent
• 🛠️ CLI tools - One-command deployment and secrets management
• 🏗️ CDK constructs - AgentCoreStack, AgentBuilder, StackBuilder fluent APIs
• 📁 Config-driven - Load stacks from JSON/YAML configuration files
• 🔒 VPC & Security - Automatic VPC creation with security groups and VPC endpoints
• 👁️ Observability - Opik, Langfuse, Phoenix, and CloudWatch integration
• 🔄 Four deployment approaches - CDK Go, CDK+JSON, CfnInclude, Pure CloudFormation

Scope

This module provides AWS CDK constructs only. For other IaC tools:

IaC Tool	Module	Dependencies
AWS CDK	agentkit-aws-cdk (this module)	21
Pulumi	agentkit-aws-pulumi	340
CloudFormation	agentkit (core)	0 extra

All modules share the same YAML/JSON configuration schema from agentkit/platforms/agentcore/iac/.

Architecture

agentkit/                              # Core library (no CDK deps)
├── platforms/agentcore/iac/
│   ├── config.go                      # Shared config structs
│   ├── loader.go                      # JSON/YAML loading
│   └── cloudformation.go              # Pure CloudFormation generator

agentkit-aws-cdk/                          # AWS CDK constructs (this module)
├── agentcore/
│   ├── stack.go                       # CDK constructs
│   ├── builder.go                     # Fluent builders
│   ├── cfninclude.go                  # CfnInclude wrapper
│   └── loader.go                      # CDK stack loaders

Why two modules?

• agentkit stays lean - no CDK runtime dependencies
• agentkit-aws-cdk adds CDK tooling for those who want it
• Pure CloudFormation (approach 4) works with just agentkit

Four Deployment Approaches

Approach	Module Required	Best For
1. CDK Go Constructs	agentkit-aws-cdk	Type safety, IDE support, complex logic
2. CDK + JSON/YAML	agentkit-aws-cdk	Configuration-driven deployments
3. CfnInclude	agentkit-aws-cdk	Existing CloudFormation templates
4. Pure CloudFormation	agentkit only	No CDK runtime, AWS CLI only

Installation

For CDK approaches (1-3):

go get github.com/plexusone/agentkit-aws-cdk

For Pure CloudFormation (4):

go get github.com/plexusone/agentkit

---

1. CDK Go Constructs

Type-safe Go code with full IDE support and compile-time validation.

package main

import "github.com/plexusone/agentkit-aws-cdk/agentcore"

func main() {
    app := agentcore.NewApp()

    // Build agents with fluent API
    research := agentcore.NewAgentBuilder("research", "ghcr.io/example/research:latest").
        WithMemory(512).
        WithTimeout(30).
        Build()

    orchestration := agentcore.NewAgentBuilder("orchestration", "ghcr.io/example/orchestration:latest").
        WithMemory(1024).
        WithTimeout(300).
        AsDefault().
        Build()

    // Build stack
    agentcore.NewStackBuilder("my-agents").
        WithAgents(research, orchestration).
        WithOpik("my-project", "arn:aws:secretsmanager:us-east-1:123456789:secret:opik-key").
        WithTags(map[string]string{"Environment": "production"}).
        Build(app)

    agentcore.Synth(app)
}

Deploy:

cdk deploy

See examples/1-cdk-go for complete example.

---

2. CDK + JSON/YAML Config

Minimal Go wrapper that loads configuration from JSON or YAML files. Perfect for teams who prefer configuration over code.

main.go (never changes):

package main

import "github.com/plexusone/agentkit-aws-cdk/agentcore"

func main() {
    app := agentcore.NewApp()
    agentcore.MustNewStackFromFile(app, "config.yaml")
    agentcore.Synth(app)
}

config.yaml:

stackName: my-agents
description: My AgentCore deployment

agents:
  - name: research
    containerImage: ghcr.io/example/research:latest
    memoryMB: 512
    timeoutSeconds: 30
    protocol: HTTP  # HTTP (default), MCP, or A2A

  - name: orchestration
    containerImage: ghcr.io/example/orchestration:latest
    memoryMB: 1024
    timeoutSeconds: 300
    protocol: HTTP
    isDefault: true

vpc:
  createVPC: true
  enableVPCEndpoints: true

observability:
  provider: opik
  project: my-project
  enableCloudWatchLogs: true

tags:
  Environment: production

Deploy:

cdk deploy

See examples/2-cdk-json for complete example.

---

3. CfnInclude

Import existing CloudFormation templates into CDK. Use CDK deployment tooling while keeping your existing templates.

main.go:

package main

import "github.com/plexusone/agentkit-aws-cdk/agentcore"

func main() {
    app := agentcore.NewApp()

    agentcore.NewCfnIncludeBuilder("my-agents", "template.yaml").
        WithParameter("Environment", "production").
        Build(app)

    agentcore.Synth(app)
}

Deploy:

cdk deploy

See examples/3-cfn-include for complete example.

---

4. Pure CloudFormation

Generate CloudFormation templates from configuration files. No CDK runtime needed - deploy with AWS CLI. Uses only agentkit (not agentkit-aws-cdk).

generate.go:

package main

import (
    "fmt"
    "os"

    "github.com/plexusone/agentkit/platforms/agentcore/iac"
)

func main() {
    config, err := iac.LoadStackConfigFromFile("config.yaml")
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        os.Exit(1)
    }

    if err := iac.GenerateCloudFormationFile(config, "template.yaml"); err != nil {
        fmt.Fprintf(os.Stderr, "Error: %v\n", err)
        os.Exit(1)
    }

    fmt.Println("Generated template.yaml")
}

Deploy with AWS CLI:

go run generate.go
aws cloudformation deploy \
  --template-file template.yaml \
  --stack-name my-agents \
  --capabilities CAPABILITY_IAM CAPABILITY_NAMED_IAM

See examples/4-pure-cloudformation for complete example.

---

Configuration Reference

StackConfig

Field	Type	Required	Description
stackName	string	Yes	CloudFormation stack name
description	string	No	Stack description
agents	[]AgentConfig	Yes	List of agents to deploy
vpc	VPCConfig	No	VPC configuration
observability	ObservabilityConfig	No	Monitoring configuration
gateway	GatewayConfig	No	Gateway for external tools
iam	IAMConfig	No	IAM configuration
tags	map[string]string	No	Resource tags
removalPolicy	string	No	"destroy" or "retain"

AgentConfig

Field	Type	Required	Description
name	string	Yes	Agent identifier
containerImage	string	Yes	ECR image URI
description	string	No	Human-readable description
memoryMB	int	No	Memory: 512, 1024, 2048, 4096, 8192, 16384
timeoutSeconds	int	No	Timeout: 1-900 seconds
protocol	string	No	Communication protocol: HTTP (default), MCP, A2A
environment	map[string]string	No	Environment variables
secretsARNs	[]string	No	Secret ARNs to inject
isDefault	bool	No	Mark as default agent

GatewayConfig

Field	Type	Required	Description
enabled	bool	No	Enable Gateway creation
name	string	No	Gateway name
description	string	No	Gateway description

Note: Gateway is for exposing external tools to agents via MCP, not for agent-to-agent communication. Agents communicate directly via A2A protocol.

VPCConfig

Field	Type	Default	Description
createVPC	bool	true	Create new VPC
vpcCidr	string	10.0.0.0/16	VPC CIDR block
maxAZs	int	2	Number of availability zones
enableVPCEndpoints	bool	true	Create VPC endpoints
vpcId	string	-	Existing VPC ID
subnetIds	[]string	-	Existing subnet IDs

ObservabilityConfig

Field	Type	Default	Description
provider	string	opik	opik, langfuse, phoenix, cloudwatch
project	string	stackName	Project name for traces
apiKeySecretARN	string	-	Secret ARN for API key
enableCloudWatchLogs	bool	true	Enable CloudWatch Logs
logRetentionDays	int	30	Log retention period
enableXRay	bool	false	Enable X-Ray tracing

---

Stack Outputs

After deployment, the stack outputs:

Output	Description
VPCID	VPC identifier
SecurityGroupID	Security group for agents
ExecutionRoleARN	IAM role for agent execution
Agent-{name}-RuntimeArn	Runtime ARN for IAM policies
Agent-{name}-RuntimeId	Runtime ID for API calls
Agent-{name}-EndpointArn	Endpoint ARN for invocation
Agent-{name}-Image	Container image reference
GatewayArn	Gateway ARN (if gateway enabled)
GatewayId	Gateway ID (if gateway enabled)
GatewayUrl	Gateway URL (if gateway enabled)

---

Prerequisites

1. Install AWS CDK CLI (for approaches 1-3):

   npm install -g aws-cdk
   

2. Configure AWS credentials:

   aws configure
   

3. Bootstrap CDK (first time only, for approaches 1-3):

   cdk bootstrap aws://ACCOUNT-ID/REGION
   

---

Project Structure

my-project/
├── infrastructure/
│   └── cdk/
│       ├── go.mod
│       ├── main.go          # CDK app (approaches 1-3)
│       ├── config.yaml      # Configuration (approaches 2, 4)
│       └── cdk.json         # CDK config
├── agents/
│   ├── research/
│   ├── synthesis/
│   └── orchestration/
└── go.mod

---

License

MIT