@agents-at-scale/ark 0.1.37 → 0.1.39

package/templates/project/README.md

@@ -0,0 +1,377 @@
+# {{projectName}}
+
+Agents at Scale project for building AI agents and teams.
+
+## Quick Start (5 minutes)
+
+```bash
+# 1. Navigate to your project
+cd {{ .Values.projectName }}
+
+# 2. Set your API keys
+source .env  # Edit this file first with your API keys
+
+# 3. Deploy to your ARK cluster
+make quickstart
+
+# 4. Check your deployment
+kubectl get agents,teams,queries --namespace {{ .Values.namespace }}
+```
+
+That's it! Your agents, teams, and queries are all running on Agents at Scale.
+
+## What You Get
+
+### Core Examples
+
+- **`agents/sample-agent.yaml`** - Basic AI agent
+- **`teams/sample-team.yaml`** - Simple team (single agent)
+- **`queries/sample-query.yaml`** - Query to test your agent
+- **`models/azure-model.yaml`** - Model and secret configuration
+
+### Production Ready
+
+- **Helm chart** that deploys agents, teams, queries, models, and tools
+- **CI/CD pipeline** with GitHub Actions
+- **Security** best practices and RBAC
+- **Makefile** with all necessary commands
+
+## Project Structure
+
+```
+{{ .Values.projectName }}/
+├── agents/                 # Agent definitions
+├── teams/                  # Team definitions
+├── queries/                # Queries
+├── models/                 # Model configurations
+├── mcp-servers/            # MCP servers
+├── tools/                  # Custom tools deployed as part of this project
+├── scripts/                # Setup and utility scripts
+├── docs/                   # Additional documentation
+└── .github/                # CI/CD workflows
+```
+
+## Core Concepts
+
+### Agents
+
+Individual AI assistants with specific roles:
+
+```yaml
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Agent
+metadata:
+  name: sample-agent
+spec:
+  description: Sample agent demonstrating basic functionality
+  prompt: 'You are a helpful AI assistant...'
+  modelRef:
+    name: azure-gpt4
+```
+
+### Teams
+
+Groups of agents that collaborate:
+
+```yaml
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Team
+metadata:
+  name: sample-team
+spec:
+  members:
+    - name: sample-agent
+      type: agent
+  strategy: 'sequential'
+```
+
+### Queries
+
+Inputs to agents or teams:
+
+```yaml
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Query
+metadata:
+  name: sample-query
+spec:
+  input: 'Hello! Can you help me understand what you can do?'
+  targets:
+    - type: agent
+      name: sample-agent
+```
+
+## Prerequisites
+
+- Kubernetes cluster with ARK installed
+- kubectl configured
+- API key for OpenAI/Azure/Anthropic
+
+## Commands
+
+```bash
+# Quick commands
+make help          # Show all available commands
+make quickstart   # 5-minute setup and deploy
+make status        # Check deployment status
+
+# Development
+make dev           # Run in development mode
+make test          # Run tests
+make build         # Build all components
+
+# Deployment
+make install       # Deploy to ARK cluster
+make upgrade       # Upgrade deployment
+make uninstall     # Remove from cluster
+
+# Utilities
+make logs          # View logs
+make debug         # Show debugging info
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required: At least one API key
+export OPENAI_API_KEY="your-key"
+# OR
+export AZURE_OPENAI_API_KEY="your-azure-key"
+# OR
+export ANTHROPIC_API_KEY="your-anthropic-key"
+
+# Optional: Customize deployment
+export NAMESPACE="your-namespace"
+export PROJECT_NAME="your-project"
+```
+
+### Customize Values
+
+Edit `chart/values.yaml` to configure:
+
+- Model providers and API keys
+- Resource limits and scaling
+- Security policies
+- Ingress settings
+
+## Adding More
+
+### More Agents
+
+Create additional agents in `agents/`:
+
+```yaml
+# agents/my-agent.yaml
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Agent
+metadata:
+  name: my-agent
+spec:
+  description: My custom agent
+  prompt: 'You are a specialist in...'
+  modelRef:
+    name: azure-gpt4
+```
+
+### More Teams
+
+Create teams in `teams/` that reference your agents:
+
+```yaml
+# teams/my-team.yaml
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Team
+metadata:
+  name: my-team
+spec:
+  members:
+    - name: sample-agent
+      type: agent
+    - name: my-agent
+      type: agent
+  strategy: 'round-robin'
+```
+
+### MCP Servers
+
+Create production-ready MCP servers using the ark CLI generator:
+
+```bash
+# Generate a new MCP server with full Kubernetes deployment
+ark generate mcp-server my-server
+
+# Choose from Node.js, Deno, Go, or Python
+# Includes Dockerfile, Helm chart, and deployment scripts
+# Creates example agents and queries for testing
+```
+
+This creates a complete MCP server in `mcp-servers/my-server/` with:
+
+- Multi-technology support (Node.js, Deno, Go, Python)
+- Production-ready Kubernetes deployment
+- Authentication and configuration options
+- Comprehensive documentation and examples
+
+### Custom Tools
+
+Create tools as Kubernetes YAML files in `tools/my-tool.yaml`:
+
+```yaml
+# tools/my-tool.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "{{ .Values.projectName }}.fullname" . }}-my-tool
+  labels:
+    {{- include "{{ .Values.projectName }}.labels" . | nindent 4 }}
+    component: tool
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      {{- include "{{ .Values.projectName }}.selectorLabels" . | nindent 6 }}
+      component: tool
+  template:
+    spec:
+      containers:
+      - name: my-tool
+        image: "{{ .Values.image.registry }}/{{ .Values.project.name }}-my-tool:{{ .Values.image.tag }}"
+        ports:
+        - containerPort: 8000
+          name: http
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "{{ .Values.projectName }}.fullname" . }}-my-tool
+spec:
+  ports:
+  - port: 8000
+    targetPort: http
+  selector:
+    {{- include "{{ .Values.projectName }}.selectorLabels" . | nindent 4 }}
+    component: tool
+---
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: MCPServer
+metadata:
+  name: my-tool
+spec:
+  address:
+    valueFrom:
+      serviceRef:
+        name: {{ include "{{ .Values.projectName }}.fullname" . }}-my-tool
+        port: 8000
+        path: /mcp
+  transport: sse
+```
+
+See `tools/example-tool.yaml.disabled` for a complete example.
+
+**Tools vs MCP Servers:**
+
+- **Tools** = Simple Kubernetes resources deployed as part of this project (YAML files in `tools/`)
+- **MCP Servers** = Independent services with their own Helm charts, more complex deployments (generated in `mcp-servers/`)
+
+## Different Model Providers
+
+### Azure OpenAI
+
+```bash
+export AZURE_OPENAI_API_KEY="your-key"
+# Model files are copied from samples/models/ during project creation
+# Edit the copied files and set API keys in .env
+```
+
+### OpenAI
+
+```bash
+export OPENAI_API_KEY="your-key"
+# Copy from samples: cp ../samples/models/openai.yaml models/
+```
+
+### AWS Bedrock
+
+```bash
+export AWS_ACCESS_KEY_ID="your-key"
+export AWS_SECRET_ACCESS_KEY="your-secret"
+# Copy from samples: cp ../samples/models/claude.yaml models/
+```
+
+## Testing
+
+```bash
+# Validate configurations
+make test
+
+# Test specific components
+make test-manifests  # Validate YAML files
+make test-tools      # Test custom tools
+
+# Manual testing
+kubectl apply -f queries/sample-query.yaml
+kubectl get query sample-query -o yaml
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Agent not responding**: Check model configuration and API keys
+
+```bash
+kubectl get models
+kubectl describe agent sample-agent
+```
+
+**Tool not available**: Verify MCP server deployment
+
+```bash
+kubectl get mcpservers
+kubectl logs -l component=tool
+```
+
+**Team issues**: Check agent references and team strategy
+
+```bash
+kubectl describe team sample-team
+```
+
+### Debug Commands
+
+```bash
+make debug         # Show debugging information
+make logs          # View all logs
+make status        # Check deployment status
+```
+
+## CI/CD
+
+The template includes GitHub Actions for:
+
+- **Linting** YAML and code
+- **Building** container images
+- **Testing** manifests and tools
+- **Security scanning** with Trivy
+- **Deploying** to staging/production
+
+## Next Steps
+
+1. **Customize the sample agent** in `agents/sample-agent.yaml`
+2. **Add more agents** as separate YAML files
+3. **Create teams** to coordinate multiple agents
+4. **Build custom tools** when you need specialized functionality
+5. **Set up CI/CD** for automated deployment
+
+## Resources
+
+- [ARK Documentation](https://mckinsey.github.io/agents-at-scale-ark/)
+- [Model Context Protocol](https://github.com/modelcontextprotocol)
+- [FastMCP Framework](https://github.com/jlowin/fastmcp)
+- [ARK Samples](../../samples/)
+
+---
+
+**Need help?** Check the troubleshooting section above or create an issue.

package/templates/project/agents/.keep

@@ -0,0 +1,11 @@
+# Additional Agents
+
+Add your custom agents here alongside the provided sample-agent.yaml example.
+
+Each agent should be a separate YAML file:
+```
+agents/
+├── sample-agent.yaml     # Example provided
+├── my-agent.yaml         # Your custom agent
+└── another-agent.yaml    # Another custom agent
+```

package/templates/project/docs/.keep

@@ -0,0 +1,14 @@
+# Documentation
+
+Add detailed documentation here as your project grows.
+
+The main README.md covers all essentials for getting started.
+
+Example structure:
+```
+docs/
+├── architecture.md      # System architecture
+├── deployment.md        # Advanced deployment guide  
+├── development.md       # Development workflows
+└── troubleshooting.md   # Detailed troubleshooting
+```

package/templates/project/mcp-servers/.keep

@@ -0,0 +1,34 @@
+# MCP Servers Directory
+
+Add your MCP servers here using the ark CLI generator.
+
+Each MCP server should be in its own subdirectory generated with:
+```bash
+ark generate mcp-server <server-name>
+```
+
+This will create a complete MCP server with:
+- Dockerfile with multi-technology support
+- Helm chart for Kubernetes deployment  
+- Build and deployment scripts
+- Example agent and query configurations
+
+Example structure:
+```
+mcp-servers/
+├── weather-api/
+│   ├── Dockerfile
+│   ├── Makefile
+│   ├── build.sh
+│   ├── chart/
+│   │   ├── Chart.yaml
+│   │   ├── values.yaml
+│   │   └── templates/
+│   └── examples/
+└── github-tools/
+    ├── Dockerfile
+    ├── chart/
+    └── ...
+```
+
+The deployment system will automatically detect and deploy any MCP servers you add here.

package/templates/project/models/.keep

@@ -0,0 +1,17 @@
+# Models Directory
+#
+# This directory contains AI model configurations that will be automatically 
+# deployed when you run `make quickstart`.
+#
+# Model files are copied from samples/models/ during project creation.
+# You can add more models by copying from the samples directory:
+#
+#   cp ../samples/models/claude.yaml .
+#   cp ../samples/models/gemini.yaml .
+#
+# Each model file typically includes:
+# - Secret for API key storage
+# - Model resource configuration
+#
+# Set your API keys in the .env file - they will be substituted into the
+# model YAML files using environment variable substitution.

package/templates/project/queries/.keep

@@ -0,0 +1,11 @@
+# Additional Queries
+
+Add your custom queries here alongside the provided sample-query.yaml example.
+
+Each query should be a separate YAML file:
+```
+queries/
+├── sample-query.yaml     # Example provided
+├── my-query.yaml         # Your custom query
+└── another-query.yaml    # Another custom query
+```

package/templates/project/scripts/setup.sh

@@ -0,0 +1,108 @@
+#!/bin/bash
+# Simple setup script for Agents at Scale project template
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+PROJECT_NAME="${PROJECT_NAME:-{{ .Values.projectName }}}"
+NAMESPACE="${NAMESPACE:-default}"
+
+echo -e "${BLUE}🚀 Setting up Agents at Scale Project${NC}"
+echo "Project: $PROJECT_NAME | Namespace: $NAMESPACE"
+echo ""
+
+# Check prerequisites
+echo -e "${YELLOW}📋 Checking prerequisites...${NC}"
+if ! command -v kubectl >/dev/null 2>&1; then
+    echo -e "${RED}❌ kubectl not found. Please install kubectl.${NC}"
+    exit 1
+fi
+
+if ! command -v helm >/dev/null 2>&1; then
+    echo -e "${RED}❌ helm not found. Please install helm.${NC}"
+    exit 1
+fi
+
+# Check cluster connection
+if ! kubectl cluster-info >/dev/null 2>&1; then
+    echo -e "${RED}❌ Cannot connect to Kubernetes cluster${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Prerequisites check passed${NC}"
+
+# Check for API keys
+echo ""
+echo -e "${YELLOW}🔐 Checking API keys...${NC}"
+if [ -z "$OPENAI_API_KEY" ] && [ -z "$AZURE_OPENAI_API_KEY" ] && [ -z "$ANTHROPIC_API_KEY" ]; then
+    echo -e "${YELLOW}⚠️  No API keys found in environment.${NC}"
+    echo "Please set at least one of:"
+    echo "  export OPENAI_API_KEY='your-key'"
+    echo "  export AZURE_OPENAI_API_KEY='your-key'"
+    echo "  export ANTHROPIC_API_KEY='your-key'"
+    echo ""
+    read -p "Continue anyway? (y/n): " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+else
+    echo -e "${GREEN}✅ API key(s) found${NC}"
+fi
+
+# Create namespace
+echo ""
+echo -e "${YELLOW}🏗️  Setting up namespace...${NC}"
+kubectl create namespace "$NAMESPACE" 2>/dev/null || echo "Namespace $NAMESPACE already exists"
+
+# Create secrets if API keys exist
+if [ -n "$OPENAI_API_KEY" ]; then
+    kubectl create secret generic openai-secret \
+        --from-literal=api-key="$OPENAI_API_KEY" \
+        --namespace="$NAMESPACE" \
+        --dry-run=client -o yaml | kubectl apply -f -
+    echo -e "${GREEN}✅ Created OpenAI secret${NC}"
+fi
+
+if [ -n "$AZURE_OPENAI_API_KEY" ]; then
+    kubectl create secret generic azure-openai-secret \
+        --from-literal=api-key="$AZURE_OPENAI_API_KEY" \
+        --namespace="$NAMESPACE" \
+        --dry-run=client -o yaml | kubectl apply -f -
+    echo -e "${GREEN}✅ Created Azure OpenAI secret${NC}"
+fi
+
+if [ -n "$ANTHROPIC_API_KEY" ]; then
+    kubectl create secret generic anthropic-secret \
+        --from-literal=api-key="$ANTHROPIC_API_KEY" \
+        --namespace="$NAMESPACE" \
+        --dry-run=client -o yaml | kubectl apply -f -
+    echo -e "${GREEN}✅ Created Anthropic secret${NC}"
+fi
+
+# Create local config
+cat > .env <<EOF
+PROJECT_NAME=$PROJECT_NAME
+NAMESPACE=$NAMESPACE
+EOF
+
+cat > values.local.yaml <<EOF
+project:
+  name: $PROJECT_NAME
+  namespace: $NAMESPACE
+EOF
+
+echo ""
+echo -e "${GREEN}🎉 Setup complete!${NC}"
+echo ""
+echo -e "${BLUE}Next steps:${NC}"
+echo "  make install       # Deploy to Kubernetes"
+echo "  make status        # Check deployment"
+echo ""
+echo "Or use the quick start:"
+echo "  make quickstart   # One-command deploy"

package/templates/project/teams/.keep

@@ -0,0 +1,11 @@
+# Additional Teams
+
+Add your custom teams here alongside the provided sample-team.yaml example.
+
+Each team should be a separate YAML file:
+```
+teams/
+├── sample-team.yaml      # Example provided
+├── my-team.yaml          # Your custom team
+└── another-team.yaml     # Another custom team
+```