Starting a New Agentic Project

This guide walks you through creating a new agentic project from scratch using ARK’s code generation tools and testing the complete workflow end-to-end.

Important: Project Structure

ARK is the platform, not where you build agents. This guide shows you how to create a new agent project in its own repository, separate from the ARK platform repository.

ARK Repository: Contains the platform code (controllers, APIs, services)
Your Agent Project: A separate repository with agents, teams, queries, and tools

Multiple teams can build their own agent projects, each with their own repository, all using the same ARK platform. This separation allows:

Teams to work independently on their agents
Version control for agent configurations
Different deployment lifecycles for platform vs. agents
Sharing agent projects across teams

Prerequisites

Before starting, ensure you have:

ARK installed and running on your cluster
ARK CLI installed (ark command available)
kubectl configured to access your cluster
At least one model configured in ARK

Verify your setup:


# Check ARK CLI is installed
ark --version
 
# Verify cluster connection
kubectl get pods -n ark-system
 
# Check available models
kubectl get models

Step 1: Generate a New Project

Use the ARK CLI to bootstrap a new project with a structured directory layout:


# Create a new project
ark generate project my-agents
 
# Navigate to the project directory
cd my-agents

Now you can find a defalut model configuration in the models/ directory. Alternatively, you can copy a model configuration template from the samples/models/ directory of the ARK repository.

Then, edit the .env file to add your API keys and other model related variables and make sure to source it.

You can finalize you initial setup through one of the following ways:


# Just apply model config with environment variable substitution
make models-apply
 
# Apply model configurations and also deploy to ARK
make quickstart
 
### Interactive Prompts
 
The generator will ask you several questions to customize your project:
 
**1. Project Type:**
- `Project with samples (recommended for getting started)` - Includes example agents, teams, queries, and tools
- `Empty project (just the structure)` - Creates only the directory structure
 
**2. Namespace:**
- Kubernetes namespace for deployment (default: project name)
 
**3. Model Configuration (optional):**
- Choose which LLM providers to configure:
  - `Default OpenAI` - Standard OpenAI models
  - `AI Gateway` - Custom AI gateway endpoint
  - `All providers` - Configure multiple providers
  - `None` - Skip model configuration
 
**4. Git Setup (optional):**
- Initialize git repository
- Create initial commit
- Configure git user name and email
 
### Non-Interactive Mode
 
To skip prompts and use defaults:
 
```bash
ark generate project my-agents --no-interactive --skip-models --skip-git

This creates a project structure with:


my-agents/
├── agents/          # Agent definitions
├── teams/           # Team configurations
├── queries/         # Query examples
├── models/          # Model configurations
├── tools/           # Tool definitions
├── mcp-servers/     # MCP server configurations
├── scripts/         # Utility scripts
├── templates/       # Component templates
├── tests/           # Test configurations
├── docs/            # Project documentation
├── Chart.yaml       # Helm chart definition
├── values.yaml      # Helm chart values
├── Makefile         # Build and deployment targets
├── .env             # Environment configuration
└── README.md        # Project README

Deploying Your Project to ARK

After generating your project, deploy it to your ARK cluster:

Using Make (Recommended)


# Deploy using Helm with custom resources
make install
 
# Or deploy to a specific namespace
make install NAMESPACE=my-team-agents
 
# Apply only custom resources (agents, teams, queries)
make resources-apply

Using Helm Directly


# Install as a Helm chart
helm install my-agents . --namespace my-team-agents --create-namespace
 
# Upgrade an existing deployment
helm upgrade my-agents . --namespace my-team-agents

Using kubectl


# Apply individual resources
kubectl apply -f agents/
kubectl apply -f teams/
kubectl apply -f queries/
 
# Or apply all YAML files
kubectl apply -f . -R

Verify Deployment


# Check deployed resources
kubectl get agents,teams,queries -n my-team-agents
 
# Check agent status
kubectl get agents -n my-team-agents -o wide
 
# View agent logs
kubectl logs -l app=ark-api -n my-team-agents --tail=100

Step 2: Generate Your First Agent

Now use the generator to create an agent:


# Generate an agent (interactive)
ark generate agent customer-support

Interactive Prompts

The agent generator will ask:

1. Agent Name:

Name for your agent (e.g., customer-support)

2. Generate Test Query:

Option to create a sample query for testing

Non-Interactive Mode


# Skip prompts
ark generate agent customer-support --no-interactive

This creates agents/customer-support-agent.yaml with dummy description and prompt, and the reference to default model. Edit the generated agent configuration: Remember to set the namespace field to match the namespace of the project.


apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: customer-support-agent
  namespace: my-agents
spec:
  description: Handles customer inquiries and support tickets
  modelRef:
    name: default  # Reference to your model
  prompt: |
    You are a helpful customer support assistant.
    Help users with their questions and issues professionally and efficiently.

Apply the agent to your cluster:


kubectl apply -f agents/customer-support-agent.yaml

Verify the agent is ready:


kubectl get agents customer-support-agent
 
# Expected output shows Ready status
kubectl get agents customer-support-agent -o jsonpath='{.status.phase}'
# Should output: ready

Step 3: Generate Additional Resources

Create Tools

Tools extend agent capabilities but there’s no generator for them. Create tools manually:


# Create a tool definition
cat > tools/get-forecast.yaml <<EOF
apiVersion: ark.mckinsey.com/v1alpha1
kind: Tool
metadata:
  name: get-forecast
spec:
  type: http
  inputSchema:
    type: object
    properties:
      office:
        type: string
        description: "Weather office identifier (e.g., TOP)"
      gridX:
        type: integer
        description: "Grid X coordinate"
      gridY:
        type: integer
        description: "Grid Y coordinate"
    required: ["office", "gridX", "gridY"]
  description: "Get weather forecast for a specific location and time period"
  http:
    url: https://api.weather.gov/gridpoints/{office}/{gridX},{gridY}/forecast
EOF

Apply and verify:


kubectl apply -f tools/get-forecast.yaml
kubectl get tools get-forecast

For more details on creating tools, see the Tools guide.

Generate a Team

Create a team of agents:


ark generate team support-team

Prompts:

Team name
Strategy, choose from:
- Round-robin, members take turns
- Sequential, members execute in order
- Graph, custom workflow defined by graph edges. Max turns and graph edges are mandatory.
- Selector, AI-powered member selection (can be combined with graph constraints). Selector agent specification is mandatory.
Select member agents from your project

Edit teams/support-team.yaml:


apiVersion: ark.mckinsey.com/v1alpha1
kind: Team
metadata:
  name: support-team
spec: 
  description: Customer support team
  members:
    - kind: Agent
      name: customer-support
    - kind: Agent
      name: order-tracker
    - kind: Agent
      name: escalation-handler
  # Strategy-related specs:
  strategy: sequential
  [...]
  strategy: round-robin
  maxTurns: 5
  [...]
  strategy: graph
  maxTurns: 5
  [...]
  strategy: selector
  selector:
    agent: planner-agent
    selectorPrompt: "Choose the best agent for: {{.Input}}"
  [...]
  strategy: graph
  maxTurns: 5
  graph:
    edges:
      - from: customer-support
        to: order-tracker
      - from: order-tracker
        to: escalation-handler

Apply and verify:


kubectl apply -f teams/support-team.yaml
kubectl get teams support-team

Generate an MCP Server

Create an MCP (Model Context Protocol) server with Kubernetes deployment:


ark generate mcp-server filesystem-server

Prompts:

Server Name: Name for your MCP server
Technology: Choose the implementation language:
- node - Node.js with NPM packages or local development
- deno - Deno with JSR packages or local development
- go - Go with go install packages or local development
- python - Python with pip packages or local development
Package/Repository: NPM package name, JSR package, Go package path, or pip package (depending on technology)
Authentication: Whether to enable authentication for secured APIs
Custom Configuration: Whether to add custom configuration options
Generate Examples: Whether to create example agent and query files

This creates a complete MCP server project with:

chart/ - Helm chart with Kubernetes manifests (Deployment, Service, MCPServer CRD)
examples/ - Example agent and query YAML files
Dockerfile - Container image with mcp-proxy
Makefile - Build and deployment targets
README.md - Setup and usage documentation
Technology-specific files (package.json, go.mod, requirements.txt, etc.)

For more details, see the MCP Servers guide.

Generate a Marketplace

Create a central repository for sharing reusable ARK components:


ark generate marketplace

Note: The marketplace is always named ark-marketplace (the name argument is ignored).

Prompts:

Destination directory
Git repository initialization

This creates a structured repository with directories for:

agents/ - Reusable agent definitions
teams/ - Multi-agent workflow configurations
models/ - Model configurations by provider
queries/ - Query templates and patterns
tools/ - Tool definitions and implementations
mcp-servers/ - MCP server configurations
projects/ - Complete end-to-end project templates
docs/ - Documentation and guides
.github/ - CI/CD workflows

Perfect for organizations sharing components across teams or building a community marketplace.

Step 4: Test with Queries

Generate a Query

Create a test query:


ark generate query test-support-query

Prompts:

Query name
Input message/text
Target selection (agent or team)
Choose target from available resources

Edit queries/test-support-query.yaml:


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: test-support-query
spec:
  input: "I need help with my order #12345"
  target:
    - kind: Agent
    name: customer-support

Execute and Monitor

Apply the query:


kubectl apply -f queries/test-support-query.yaml

Monitor query execution:


# Watch query status
kubectl get query test-support-query -w
 
# View query details
kubectl describe query test-support-query
 
# Get the response
kubectl get query test-support-query -o jsonpath='{.status.response.content}'

Step 5: End-to-End Testing

Option 1: Manual Test Script (Optional)

You can create a custom test script for manual E2E testing. This is not generated by ARK - it’s an example you can customize.

Create test-workflow.sh in your project root:


#!/bin/bash
set -e
 
echo "=== Testing Complete ARK Workflow ==="
 
# Apply all resources
echo "Applying agents..."
kubectl apply -f agents/
 
echo "Applying tools..."
kubectl apply -f tools/
 
echo "Applying teams..."
kubectl apply -f teams/
 
# Wait for resources to be ready
echo "Waiting for agent to be ready..."
kubectl wait --for=condition=Ready agent/customer-support --timeout=60s
 
echo "Waiting for team to be ready..."
kubectl wait --for=condition=Ready team/support-team --timeout=60s
 
# Run test query
echo "Executing test query..."
kubectl apply -f queries/test-support-query.yaml
 
# Wait for query completion
echo "Waiting for query to complete..."
kubectl wait --for=jsonpath='{.status.phase}'=done query/test-support-query --timeout=120s
 
# Verify response
echo "Verifying query response..."
RESPONSE=$(kubectl get query test-support-query -o jsonpath='{.status.response.content}')
 
if [ -z "$RESPONSE" ]; then
  echo "FAIL Test failed: No response received"
  exit 1
fi
 
echo "PASS Test passed: Response received"
echo "Response: $RESPONSE"
 
# Cleanup
echo "Cleaning up test resources..."
kubectl delete query test-support-query
 
echo "=== Test Complete ==="

Make it executable and run:


chmod +x test-workflow.sh
./test-workflow.sh

Option 2: Chainsaw Tests (Recommended)

For more robust, declarative testing, create Chainsaw test files in your tests/ directory:

Create chainsaw-test.yaml:


apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: customer-support-workflow
spec:
  steps:
    - name: apply-resources
      try:
        - apply:
            file: agents/customer-support.yaml
        - apply:
            file: queries/test-support-query.yaml
 
    - name: wait-for-ready
      try:
        - assert:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Agent
              metadata:
                name: customer-support
              status:
                phase: ready
 
    - name: verify-query-completion
      try:
        - assert:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              metadata:
                name: test-support-query
              status:
                phase: done
                (length(responses) > `0`): true
                (length(responses[0].content) > `10`): true
 
    - name: cleanup
      try:
        - delete:
            ref:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              name: test-support-query

Run the Chainsaw test:


chainsaw test --test-file chainsaw-test.yaml

Step 6: Iterate and Expand

Add More Agents


# Generate specialized agents
ark generate agent order-tracker
ark generate agent product-recommender
ark generate agent escalation-handler

Create Complex Teams


apiVersion: ark.mckinsey.com/v1alpha1
kind: Team
metadata:
  name: full-support-team
spec:
  description: Complete customer support workflow
  strategy: sequential
  maxTurns: 10
  members:
    - kind: Agent
      name: customer-support
    - kind: Agent
      name: order-tracker
    - kind: Agent
      name: escalation-handler

Add Evaluations

Create evaluation queries to measure performance:


apiVersion: ark.mckinsey.com/v1alpha1
kind: Query
metadata:
  name: eval-customer-support
spec:
  input: "Test customer inquiry"
  target:
    - kind: Agent
    name: customer-support
  evaluations:
    - evaluatorRef:
        name: llm-evaluator
      criteria:
        - accuracy
        - helpfulness
        - professionalism

Best Practices

1. Organize by Feature

Structure your project by feature or use case:


my-agents/
├── features/
│   ├── customer-support/
│   │   ├── agents/
│   │   ├── tools/
│   │   ├── queries/
│   │   └── tests/
│   └── order-processing/
│       ├── agents/
│       ├── tools/
│       └── tests/

2. Version Control

Initialize git and commit your project:


git init
git add .
git commit -m "feat: initial ARK project setup"

3. Environment-Specific Configurations

Use Kustomize for different environments:


# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
 
resources:
  - agents/
  - tools/
  - teams/
 
namespace: my-agents-prod

4. Continuous Testing

Set up automated testing in your CI/CD pipeline:


# .github/workflows/test.yml
name: Test ARK Agents
 
on: [push, pull_request]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup K3s
        run: |
          curl -sfL https://get.k3s.io | sh -
      - name: Install ARK
        run: |
          ark install -y
      - name: Run Tests
        run: |
          chainsaw test --test-dir tests/

Troubleshooting

Agent Not Ready


# Check agent status
kubectl describe agent customer-support
 
# Check controller logs
kubectl logs -n ark-system -l app=ark-controller
 
# Verify model is available
kubectl get models

Query Stuck


# Check query status
kubectl get query test-support-query -o yaml
 
# Check for errors
kubectl get query test-support-query -o jsonpath='{.status.error}'
 
# View query events
kubectl get events --field-selector involvedObject.name=test-support-query

Tool Not Working


# Verify tool is ready
kubectl get tool get-forecast
 
# Check tool configuration
kubectl describe tool get-forecast
 
# Test tool endpoint
kubectl run curl-test --image=curlimages/curl:latest --rm -it -- \
  curl http://weather-service/api

Next Steps

ARK Dashboard - Learn to use the dashboard
Creating Models - Configure LLM models
Creating Agents - Deep dive into agent configuration
Creating Teams - Advanced team patterns
End-to-End Testing - Learn comprehensive testing strategies
UI Testing - Test the ARK Dashboard

Complete E2E Test Suite Example

Here’s a complete example combining all concepts:


# e2e-test.yaml
apiVersion: chainsaw.kyverno.io/v1alpha1
kind: Test
metadata:
  name: complete-workflow-test
spec:
  steps:
    # Setup phase
    - name: setup
      try:
        - apply:
            file: agents/
        - apply:
            file: tools/
        - apply:
            file: teams/
 
    # Verify readiness
    - name: verify-ready
      try:
        - assert:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Agent
              metadata:
                name: customer-support
              status:
                phase: ready
        - assert:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Team
              metadata:
                name: support-team
              status:
                phase: ready
 
    # Test agent query
    - name: test-agent
      try:
        - apply:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              metadata:
                name: test-agent-query
              spec:
                input: "Test agent functionality"
                targets:
                  - kind: Agent
                    name: customer-support
        - assert:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              metadata:
                name: test-agent-query
              status:
                phase: done
                (length(responses)): 1
                (length(responses[0].content) > `10`): true
 
    # Test team query
    - name: test-team
      try:
        - apply:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              metadata:
                name: test-team-query
              spec:
                input: "Test team collaboration"
                targets:
                  - kind: Team
                    name: support-team
        - assert:
            resource:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              metadata:
                name: test-team-query
              status:
                phase: done
                (length(responses) > `0`): true
 
    # Cleanup
    - name: cleanup
      try:
        - delete:
            ref:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              name: test-agent-query
        - delete:
            ref:
              apiVersion: ark.mckinsey.com/v1alpha1
              kind: Query
              name: test-team-query

Run this comprehensive test:


chainsaw test --test-file e2e-test.yaml

This guide provides a complete workflow for starting, developing, and testing a new agentic project with ARK!