### Install ARK with Quickstart

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/walkthrough/index.mdx

Installs tools, sets up the cluster, chainsaw, and deploys the controller for ARK.

```bash
# Quick installation (installs tools, sets up cluster, chainsaw, deploys controller)
devspace dev
```

--------------------------------

### Example: Get a Deployment

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example of how to retrieve a specific Deployment resource from the 'apps' API group.

```bash
# Get a Deployment
curl http://ark-api:8000/v1/resources/apis/apps/v1/Deployment/my-deployment
```

--------------------------------

### Local Development Setup

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/operations-guide/deploying-ark.mdx

Clones the Ark repository and starts the local development server with live-reload using Devspace. Ensure Devspace is installed prior to running.

```bash
# Clone the repo, move to the project.
git clone https://github.com/mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark

# Run with live-reload for local development.
devspace dev
```

--------------------------------

### ARK Dashboard Quickstart Commands

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/services/ark-dashboard/README.md

Run these commands from the repository root to set up dependencies and start the development server.

```bash
make help                    # Show available commands
make ark-dashboard-install   # Setup dependencies
make ark-dashboard-dev       # Run development server
```

--------------------------------

### Install and Run Ark CLI

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/quickstart.mdx

Install the Ark CLI globally, then run the default installation and optionally create a default model and start the dashboard.

```bash
npm install -g @agents-at-scale/ark

ark install

ark models create default

ark dashboard
```

--------------------------------

### Quick Start: Deploy Complete Workflow

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/walkthrough/index.mdx

Install the MCP filesystem server and deploy a complete workflow using kustomization.yaml and apply a research query.

```bash
# 1. Install MCP filesystem server from marketplace
ark install marketplace/mcps/filesystem-mcp-server
```

```bash
# 2. Deploy complete workflow using kustomization.yaml
kubectl apply -k samples/walkthrough/
```

```bash
# 3. Execute research query
kubectl apply -f samples/walkthrough/research-query.yaml
```

--------------------------------

### Step-by-Step Local Setup Commands

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/services/ark-landing-page/README.md

Individual make commands for building images, setting up the demo environment, starting port-forwards, and running the dev server.

```bash
make build-images       # Build Docker images and load into Minikube
```

```bash
make setup-demo         # Create namespace, deploy dashboard + API
```

```bash
make port-forwards      # Start port-forwards
```

```bash
make dev                # Run landing page dev server on http://localhost:3002
```

--------------------------------

### Start ARK Platform

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/samples/rag-external-vectordb/README.md

Options to start the ARK platform. Use `devspace dev` for development or `ark install` for production.

```bash
# Option 1: Development (from project root)
devspace dev

# Option 2: Production
ark install
```

--------------------------------

### Example: Get a Pod

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example of how to retrieve a specific Pod resource using the Resources API.

```bash
# Get a Pod
curl http://ark-api:8000/v1/resources/api/v1/Pod/my-pod
```

--------------------------------

### Ark CLI (Node.js) and Fark CLI (Go) Setup

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/CLAUDE.md

Commands for navigating to, installing dependencies for, building, and testing the Ark CLI (Node.js) and Fark CLI (Go). Includes installation for Fark.

```bash
cd tools/ark-cli/  # Ark CLI (Node.js)
npm install        # Install dependencies
npm run build      # Build TypeScript
npm test           # Run tests

cd tools/fark/     # Fark CLI (Go)
make build-binary  # Build binary
make test          # Run tests
make install       # Install to ~/.local/bin
```

--------------------------------

### Build and Deploy Landing Page (Local)

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/services/ark-landing-page/README.md

Builds Docker images, deploys to Minikube, and starts the landing page dev server. Use this for a quick local setup.

```bash
cd services/ark-landing-page
make demo-page
```

--------------------------------

### Local Development Setup and Run

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/samples/rag-external-vectordb/retrieval-service/README.md

Installs dependencies, sets environment variables for pgvector and Azure OpenAI, and runs the retrieval service locally.

```bash
# Install dependencies
pip install -r requirements.txt
# OR using uv:
uv sync

# Set environment variables
export PGVECTOR_HOST=localhost
export PGVECTOR_DB=vectors
export PGVECTOR_USER=postgres
export PGVECTOR_PASSWORD=your-password
export AZURE_OPENAI_API_KEY=your-key
export AZURE_OPENAI_ENDPOINT=your-endpoint
export AZURE_OPENAI_API_VERSION=2024-04-01-preview
export AZURE_EMBEDDING_MODEL=text-embedding-ada-002

# Run server
python -m src.rest_server
```

--------------------------------

### Example: List all Services

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example of how to list all Service resources within the default namespace.

```bash
# List all Services
curl http://ark-api:8000/v1/resources/api/v1/Service
```

--------------------------------

### Query: Get File Information

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/mcp-servers.mdx

Example query to create a file and then retrieve its information. This demonstrates file creation followed by an information retrieval operation.

```bash
# Get file information
ark query agent/filesystem "Create data.txt with content 'important data', then get the file info for data.txt"
```

--------------------------------

### Example: Get an Argo WorkflowTemplate

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example of how to retrieve a specific WorkflowTemplate resource from the 'argoproj.io' API group.

```bash
# Get an Argo WorkflowTemplate
curl http://ark-api:8000/v1/resources/apis/argoproj.io/v1alpha1/WorkflowTemplate/my-workflow
```

--------------------------------

### MCP Server Startup Output

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/mcp-servers.mdx

Example output indicating a Streamable HTTP MCP server has started successfully using Uvicorn.

```shell
INFO:     Started server process [62149]
INFO:     Waiting for application startup.
[07/15/25 10:49:06] INFO     StreamableHTTP       streamable_http_manager.py:109
                             session manager                                    
                             started                                            
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
```

--------------------------------

### Setup Mock LLM with Helm

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/tests/CLAUDE.md

Install the mock-llm Helm release using a shared script. This setup includes waiting for the 'ModelAvailable' condition on the created Model CR.

```yaml
- name: setup-mock-llm
  try:
  - script:
      timeout: 180s
      content: |
        bash ../shared/install-mock-llm.sh
      env:
      - name: NAMESPACE
        value: ($namespace)

- name: wait-for-model-ready
  try:
  - wait:
      apiVersion: ark.mckinsey.com/v1alpha1
      kind: Model
      name: test-model-mock
      timeout: 90s
      for:
        condition:
          name: ModelAvailable
          value: 'True'
```

--------------------------------

### Example A2AServer Configuration

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/building-a2a-servers.mdx

This YAML example shows how to configure an A2AServer with an address, description, and a 10-minute timeout.

```yaml
apiVersion: ark.mckinsey.com/v1prealpha1
kind: A2AServer
metadata:
  name: my-agent
spec:
  address:
    value: "http://my-agent.default.svc.cluster.local:80"
  description: "My A2A agent"
  timeout: "10m"
```

--------------------------------

### Example: List all Jobs

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example of how to list all Job resources from the 'batch' API group.

```bash
# List all Jobs
curl http://ark-api:8000/v1/resources/apis/batch/v1/Job
```

--------------------------------

### Deploy Example Agent and Query

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/templates/mcp-server/README.md

Deploys an example agent and query that utilize the MCP server. This is an optional step for testing.

```bash
# Deploy the example agent and query that use the MCP server
kubectl apply -f examples/{{ .Values.mcpServerName }}-agent.yaml
```

--------------------------------

### Install Ark SDK

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/building-execution-engines.mdx

Install the Ark SDK using pip. This is the first step to building custom execution engines.

```bash
pip install ark-sdk
```

--------------------------------

### ARK Production Monitoring Example

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/cli-tools.mdx

Illustrates common production monitoring tasks: checking system health with `ark status`, listing resources with `fark get`, and querying agents with structured JSON output.

```bash
# Check system health
ark status

# Monitor specific resources
fark get agent
fark get team

# Query agents with structured output
fark agent weather "What's the weather?" --json
```

--------------------------------

### Install Ark CLI and Ark

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/README.md

Installs the Ark command-line interface globally and then installs Ark into a Kubernetes cluster. Ensure Node.js and Helm are installed prior to running these commands.

```bash
# Install the 'ark' CLI:
npm install -g @agents-at-scale/ark

# Install Ark:
ark install

# Optionally configure a 'default' model to use for agents:
ark models create default

# Run the dashboard:
ark dashboard
```

--------------------------------

### Install ark CLI from Source

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/cli-tools.mdx

Installs the `ark` CLI tool by building it from the repository. This command should be run from the repository root.

```bash
# Build and install from repository root
make ark-cli-install

# Verify installation
ark --help
```

--------------------------------

### Verify ARK Setup

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/starting-new-project.mdx

Check if the ARK CLI is installed, verify cluster connection, and list available models. Ensure `kubectl` is configured to access your cluster.

```bash
# Check ARK CLI is installed
ark --version

# Verify cluster connection
kubectl get pods -n ark-system

# Check available models
kubectl get models
```

--------------------------------

### Install and Manage ARK

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/ark-cli.mdx

Installs ARK, optionally skipping prompts and waiting for it to be ready. Also shows the current status of ARK.

```bash
ark install
```

```bash
ark install -y --wait-for-ready=5m  # chooses 'yes' for each option
```

```bash
ark status
```

--------------------------------

### Install ARK SDK with pip

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/ark-sdk.mdx

Install the ARK SDK using pip, providing the direct wheel URL.

```bash
# or pip:
pip install https://github.com/mckinsey/agents-at-scale-ark/releases/download/v0.1.31/ark_sdk-0.1.31-py3-none-any.whl
```

--------------------------------

### ARK Test Structure Example

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/tests/README.md

Illustrates the standard directory structure for an ARK test case, including the test definition file, documentation, and Kubernetes manifests for resource setup.

```yaml
test-name/
├── chainsaw-test.yaml    # Test definition
├── README.md            # Test documentation
└── manifests/           # Kubernetes resources
    ├── a00-rbac.yaml    # RBAC configuration
    ├── a01-secret.yaml  # Secrets
    └── ...              # Other resources
```

--------------------------------

### Install ARK Services

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/services.mdx

Run this command to install and configure additional service capabilities. It scans for services with manifest files and allows selection for installation, development, or uninstallation.

```bash
make services
```

--------------------------------

### Install ARK SDK with uv

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/ark-sdk.mdx

Install the ARK SDK using the uv package manager, specifying the direct wheel URL.

```bash
# Install via uv:
uv add "ark-sdk @ https://github.com/mckinsey/agents-at-scale-ark/releases/download/v0.1.31/ark_sdk-0.1.31-py3-none-any.whl"
```

--------------------------------

### Install Fark CLI from Source

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/tools/fark/README.md

Clone the repository and build the Fark CLI tool locally. The installation process places the executable in `~/.local/bin`.

```bash
git clone https://github.com/mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark
make fark-install  # Builds and installs to ~/.local/bin
```

--------------------------------

### Install kubectl on Windows

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/cli-tools.mdx

Install the kubectl command-line tool on Windows using Chocolatey.

```bash
# Windows
choco install kubernetes-cli
```

--------------------------------

### Install Ark Plugin from Marketplace

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/claude.mdx

Use this command to add the Ark plugin from the Claude Code Marketplace. This is the standard method for installing the plugin.

```bash
claude plugin marketplace add mckinsey/agents-at-scale-ark
claude plugin install ark@agents-at-scale-ark
```

--------------------------------

### Install DevSpace and uv

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/local-development.mdx

Installs the DevSpace CLI and uv package manager using Homebrew. Ensure Homebrew is set up before running.

```bash
# Install DevSpace
brew install devspace uv
```

--------------------------------

### Install Filesystem MCP Server

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/mcp-servers.mdx

Installs the Filesystem MCP Server from the Ark Marketplace. Verify the deployment by checking the status of the pods and MCPServer resource.

```bash
ark install marketplace/mcps/filesystem-mcp-server

# Verify deployment
kubectl get pods -l app.kubernetes.io/name=mcp-filesystem
kubectl get mcpserver mcp-filesystem
```

--------------------------------

### Quick Start: Create and Deploy an ARK Project

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/tools/ark-cli/src/commands/generate/README.md

Use these commands to quickly create a new ARK project, navigate into its directory, set up environment variables, and deploy it using the provided Makefile.

```bash
# Create a new project
ark generate project my-ai-project

# Navigate and deploy
cd my-ai-project
source .env  # Edit first to add your API keys
make quickstart

# Check your deployment
kubectl get agents,teams,queries
```

--------------------------------

### Start MCP Server for Local Development

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/templates/mcp-server/README.md

Starts the MCP server locally. This command is used after installing dependencies.

```bash
{{ .Values.packageManager }} start
```

--------------------------------

### Use Case: Access Deployments

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example for listing all Deployment resources.

```bash
# Deployments
curl http://ark-api:8000/v1/resources/apis/apps/v1/Deployment
```

--------------------------------

### Install fark CLI from Source

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/cli-tools.mdx

Installs the `fark` CLI by cloning the repository and building it from source. This method requires `git` and `make`.

```bash
# Clone and build from repository
git clone https://github.com/mckinsey/agents-at-scale-ark.git
cd agents-at-scale-ark
make fark-install

# Verify installation
fark --help
```

--------------------------------

### Ark MCP Server Quickstart Commands

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/services/ark-mcp/README.md

Use these make commands to set up dependencies and run the Ark MCP server in development mode. 'make help' shows all available commands.

```bash
make help             # Show available commands
```

```bash
make ark-mcp-install  # Setup dependencies  
```

```bash
make ark-mcp-dev      # Run in development mode
```

--------------------------------

### Install mock-llm with A2A enabled

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/queries/a2a-queries.mdx

Install the mock-llm Helm chart with A2A agents enabled. Ensure A2A agents are available before proceeding.

```bash
helm install mock-llm oci://ghcr.io/dwmkerr/charts/mock-llm \
  --set ark.a2a.enabled=true

# Wait for the A2A agents to become available.
kubectl get agents
# NAME                    MODEL   AVAILABLE   AGE
# echo-agent                      True        10s
# countdown-agent                 True        10s
# message-counter-agent           True        10s
```

--------------------------------

### Install Two Tenants with Cross-Access Setup

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/operations-guide/tenant-namespace-management.mdx

Installs two separate Ark tenants, tenant-a and tenant-b, into their respective Kubernetes namespaces. This is a prerequisite for configuring cross-tenant access.

```bash
kubectl create namespace tenant-a
kubectl config set-context --current --namespace=tenant-a
ark install ark-tenant
ark install ark-api
ark install ark-dashboard

kubectl create namespace tenant-b
kubectl config set-context --current --namespace=tenant-b
ark install ark-tenant
ark install ark-api
ark install ark-dashboard
```

--------------------------------

### Query: Create Multiple Files and List

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/mcp-servers.mdx

Example query to create multiple files with different content and then list them. This demonstrates bulk file creation and subsequent listing.

```bash
# Create multiple files and list them
ark query agent/filesystem "Create test1.md with content 'markdown file', test2.txt with content 'text file', and readme.md with content 'readme', then list all files"
```

--------------------------------

### Install Ark Tenant Helm Chart

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/operations-guide/deploying-ark.mdx

Install the `ark-tenant` Helm chart to provision namespaces, service accounts, and roles for Ark workloads.

```bash
helm install ark-tenant oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-tenant \
  -n tenant-1 \
  --create-namespace \
  --set serviceAccount.name=ark-tenant
```

--------------------------------

### Use Case: Get Specific Argo WorkflowTemplate

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example for retrieving a specific Argo WorkflowTemplate by name.

```bash
# Get specific template
curl http://ark-api:8000/v1/resources/apis/argoproj.io/v1alpha1/WorkflowTemplate/my-workflow
```

--------------------------------

### Install Ark API with Helm

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/services/ark-api.mdx

Install the Ark API service using Helm. Ensure you are in the correct namespace and create it if it doesn't exist.

```bash
helm install ark-api \
    ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-api \
    --namespace default \
    --create-namespace
```

--------------------------------

### Query: Create File and Show Directory Tree

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/mcp-servers.mdx

Example query to create a file and then display the directory tree. This combines file creation with a visual representation of the directory structure.

```bash
# Create file and show directory tree
ark query agent/filesystem "Create file hello.txt with content 'Hello World' and show me the directory tree"
```

--------------------------------

### List All Agents HTTP Request

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/tools/fark/docs/API.md

Example of how to list all available agents using a GET request to the /agents endpoint.

```bash
curl -X GET http://localhost:8080/agents
```

--------------------------------

### Get Document Stats API Response

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/samples/rag-external-vectordb/retrieval-service/README.md

Example JSON response from the /get_document_stats endpoint, providing statistics about the vector database.

```json
{
  "total_documents": 12,
  "documents_with_embeddings": 12,
  "available_metadata_keys": ["category", "source", "topic"]
}
```

--------------------------------

### Memory API: Get Conversation Response

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources/memory.mdx

Example JSON response when retrieving conversation details and messages from the Memory API.

```json
{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "messages": [
    {
      "timestamp": "2024-01-01T12:00:00Z",
      "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
      "query_id": "query-uuid",
      "message": { "role": "user", "content": "Hello" },
      "sequence": 1
    }
  ]
}
```

--------------------------------

### Disable Cert-Manager with DevSpace

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/local-development.mdx

Starts the DevSpace development environment while disabling the cert-manager. Use this if cert-manager is not required for your current development setup.

```bash
ENABLE_CERT_MANAGER=false devspace dev
```

--------------------------------

### ARK Development Workflow Example

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/cli-tools.mdx

Demonstrates a typical development cycle: creating an agent, testing it with queries, updating its prompt, retesting, and finally cleaning up by deleting the agent.

```bash
# Create and test an agent
fark create agent test-math --prompt "You are a helpful math assistant"
fark agent test-math "What is 2 + 2?"

# Update and retest
fark update agent test-math --prompt "You are an advanced mathematical assistant"
fark agent test-math "Calculate the square root of 16"

# Clean up
fark delete agent test-math
```

--------------------------------

### Deploy Sample Resources using kubectl

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/samples/README.md

These bash commands demonstrate the deployment of various sample resources within the Agents at Scale Ark project. They cover deploying a model, a simple agent, and more complex tools and workflows.

```bash
kubectl apply -f samples/quickstart/azure-openai-model.yaml
```

```bash
kubectl apply -f samples/agents/simple-agent-with-query.yaml
```

```bash
kubectl apply -f samples/tools/weather-api-tool.yaml
```

```bash
kubectl apply -f samples/workflows/weather-forecast-workflow.yaml
```

--------------------------------

### Service build.mk Example

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/build.mdx

Each service has a `build.mk` file defining its specific build configuration. This example for `ark-api` shows how to set service names, directories, output paths, stamp file locations, and define phony targets for building and testing.

```makefile
# ark-api service build configuration

ARK_API_SERVICE_NAME := ark-api
ARK_API_SERVICE_DIR := services/$(ARK_API_SERVICE_NAME)
ARK_API_OUT := $(OUT)/$(ARK_API_SERVICE_NAME)

# Pre-calculate stamp paths
ARK_API_STAMP_DEPS := $(ARK_API_OUT)/stamp-deps
ARK_API_STAMP_TEST := $(ARK_API_OUT)/stamp-test
ARK_API_STAMP_BUILD := $(ARK_API_OUT)/stamp-build

# Register for cleanup
$(eval $(call ADD_CLEAN_TARGET,$(ARK_API_OUT)))

# Define phony targets
.PHONY: $(ARK_API_SERVICE_NAME)-build $(ARK_API_SERVICE_NAME)-test

# Test target with help annotation
$(ARK_API_SERVICE_NAME)-test: $(ARK_API_STAMP_TEST) # HELP: Run ARK API server tests
$(ARK_API_STAMP_TEST): $(ARK_API_STAMP_DEPS)
	cd $(ARK_API_SERVICE_DIR) && uv run python -m pytest
	@touch $@

```

--------------------------------

### Agent Description for Selector Guidance

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/teams/team-selector-strategy.mdx

Define an agent with a description that guides the selector agent's decision-making process. This example shows a 'research-analyst' agent.

```yaml
apiVersion: ark.mckinsey.com/v1alpha1
kind: Agent
metadata:
  name: research-analyst
spec:
  description: "Research and data analysis specialist"
```

--------------------------------

### Query: Create Directory and List Contents

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/mcp-servers.mdx

Example query to create a directory and then list its contents. This showcases directory creation and listing operations.

```bash
# Create directory structure and list contents in one query
ark query agent/filesystem "Create a directory called projects, then list all files and directories"
```

--------------------------------

### Use Case: Access Jobs

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example for listing all Job resources.

```bash
# Jobs
curl http://ark-api:8000/v1/resources/apis/batch/v1/Job
```

--------------------------------

### Research Team Configuration with Custom Prompt

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/samples/teams/team-selector-strategy.mdx

Example configuration for a research team using a custom selector prompt that guides the selection process with specific workflow instructions.

```yaml
spec:
  strategy: selector
  members:
    - name: researcher
      type: agent
    - name: analyst
      type: agent
    - name: reviewer
      type: agent
  selector:
    agent: coordinator
    selectorPrompt: |
      Research workflow coordinator. Select next participant:

      Roles: {{.Roles}}
      History: {{.History}}
      Options: {{.Participants}}

      Start with researcher, follow with analyst, end with reviewer.
      Use the select-next-speaker tool to make your selection.
```

--------------------------------

### Quick Start Deployment Commands

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/templates/project/README.md

Commands to quickly set up and deploy your agents to an ARK cluster. Ensure your .env file is configured with API keys before running.

```bash
cd {{ .Values.projectName }}

source .env  # Edit this file first with your API keys

devspace dev

kubectl get agents,teams,queries --namespace {{ .Values.namespace }}
```

--------------------------------

### Dashboard Icon URI Examples

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/ark-dashboard.mdx

Icons can be specified as external URIs, data URIs, or local paths when running within the dashboard environment. Local paths typically start with `/icons/`.

```bash
# Example external URI:
https://example.com/icon.svg
```

```bash
# Or data URI:
data:image/svg+xml;base64,...
```

```bash
# Bundled icon, only available when running in the dashboard:
/icons/aws.png
```

--------------------------------

### Enable Argo Workflows with DevSpace

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/local-development.mdx

Starts the DevSpace development environment with Argo Workflows enabled. Set the ENABLE_ARGO environment variable to true to include Argo Workflows in your development setup.

```bash
ENABLE_ARGO=true devspace dev
```

--------------------------------

### Ark CLI Platform Management Commands

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/ark-cli.mdx

Examples of global Ark CLI commands for platform management, including installation, status checks, and dashboard access. Supports interactive and non-interactive modes.

```bash
ark install                  # Install platform (interactive)
```

```bash
ark install --yes            # Non-interactive (for scripts)
```

```bash
ark status                   # Check system health
```

```bash
ark dashboard                # Open dashboard
```

```bash
ark completion               # Shell completion
```

--------------------------------

### Team Configuration YAML Examples

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/starting-new-project.mdx

Examples of team configuration files demonstrating different strategies: sequential, round-robin, graph, and selector. Note the specific parameters required for each strategy.

```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
```

--------------------------------

### Initialize and Use Event Recorders

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/logging-and-events.mdx

Initialize event recorders in the controller setup and use operation recorders within the reconciler to track query execution lifecycle. This includes starting, completing, and failing operations, with automatic metadata and timing.

```go
import (
    "mckinsey.com/ark/internal/eventing)

// In controller setup
r.Eventing = eventing.NewRecorders(eventEmitter)

// In reconciler - use operation recorders with Start/Complete/Fail pattern
ctx = r.Eventing.QueryRecorder().Start(ctx, "QueryExecution", "Executing query", nil)

// On success
r.Eventing.QueryRecorder().Complete(ctx, "QueryExecution", "Query execution completed", operationData)

// On failure
r.Eventing.QueryRecorder().Fail(ctx, "QueryExecution", "Query execution failed", err, nil)
```

--------------------------------

### Build Go Services

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/CLAUDE.md

Standard commands for building and testing Go services. Navigate to the specific service directory first.

```bash
cd services/{service-name}/
make build-binary  # Build Go binary locally
make test          # Run tests
make build         # Build Docker image
```

--------------------------------

### Kubernetes Liveness Probe Configuration

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/tools.mdx

Configure a liveness probe for a Kubernetes deployment. This example sets up an HTTP GET request to the root path on port 8080, with specific timings for checks and failure thresholds. Note the comment regarding the Playwright MCP server's available endpoints.

```yaml
livenessProbe:
  httpGet:
    path: /
    port: 8080
  periodSeconds: 30          # Check every 30s (less frequent than readiness)
  timeoutSeconds: 10         # Timeout each check after 10s
  failureThreshold: 6        # HIGHER than readiness - pod marked not-ready before restart
```

--------------------------------

### Start Ark API Development Server

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/ark-apis.mdx

These commands show how to start the Ark API service for development. One uses `make` and the other uses `docker run`.

```bash
make ark-api-dev
```

```bash
docker run -p 8000:8000 ark-api:latest
```

--------------------------------

### Automated Setup for RAG Demo

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/samples/rag-external-vectordb/README.md

Run this command from the `samples/rag-external-vectordb/` directory to perform a complete automated setup of the RAG demo. It verifies ARK, deploys pgvector and the retrieval service, ingests documents, and deploys tools and the RAG agent.

```bash
# Navigate to this directory
cd samples/rag-external-vectordb

# 1. Edit Azure OpenAI credentials in the secret file
#    Open retrieval-service/deployment/azure-openai-secret.yaml
#    Replace placeholder values with your actual credentials:
#      - api-key: Your Azure OpenAI API key
#      - endpoint: Your Azure OpenAI endpoint URL
#      - api-version: API version (default: 2024-04-01-preview)
#      - embedding-model: Model name (default: text-embedding-ada-002)

# 2. Run complete setup
make rag-demo

# 3. Open ARK dashboard to query the agent
make rag-open-dashboard
```

--------------------------------

### Install Chainsaw CLI

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/testing/index.mdx

Installs the Chainsaw CLI using Homebrew or Go. Ensure you have the necessary package managers installed.

```bash
# Install with Homebrew:
brew tap kyverno/chainsaw https://github.com/kyverno/chainsaw
brew install kyverno/chainsaw/chainsaw

# Or with Go:
go install github.com/kyverno/chainsaw@latest
```

--------------------------------

### Install Ark CLI

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/operations-guide/deploying-ark.mdx

Installs the Ark CLI globally. This command initiates an interactive installation process for the core Ark controller and its dependencies.

```bash
npm install -g @agents-at-scale/ark
ark install
```

--------------------------------

### Configure UI Testing Environment

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/testing/ui-testing.mdx

Sets up the environment for UI tests. Copy the example environment file and edit it with your API keys. Ensure the dashboard is accessible, either via port-forwarding or 'devspace dev'.

```bash
cd tests/pytest/ui-tests
cp env.example .env
# Edit .env with your API keys

# Start dashboard (pick one):
kubectl port-forward svc/ark-dashboard 8080:3000 -n default
# OR
devspace dev
```

--------------------------------

### Use Case: Access ConfigMaps

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources-api.mdx

Example for listing all ConfigMap resources.

```bash
# ConfigMaps
curl http://ark-api:8000/v1/resources/api/v1/ConfigMap
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/tests/pytest/README.md

Installs the necessary browser binaries for Playwright to run UI tests. 'chromium' is sufficient for most tests, but 'all' installs all supported browsers.

```bash
playwright install chromium
# Or for all browsers:
playwright install
```

--------------------------------

### Install Chocolatey and Core Dependencies on Windows

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/troubleshooting.mdx

Installs Chocolatey package manager, Docker, and Helm on Windows using PowerShell. It also includes instructions for installing Minikube.

```powershell
# Install Chocolatey first (requires PowerShell as Administrator)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

# Install the core dependencies.
choco install docker
choco install helm

# Install minikube if you want to use this as your cluster - this'll also install
# the kubectl binary.
choco install minikube

# Other cluster options are Kind and so on.
```

--------------------------------

### Install Argo Workflows with Minio Artifact Storage

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/services/argo-workflows/README.md

Installs or upgrades Argo Workflows with Minio artifact storage enabled. This command assumes the Minio Operator is already installed.

```bash
cd chart && helm dependency update
helm upgrade --install argo-workflows ./chart -n argo-workflows --create-namespace \
  --set minio.enabled=true
```

--------------------------------

### Complete Query Example with Python

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/ark-apis.mdx

A comprehensive example demonstrating query creation, polling, authentication (basic and bearer token), and error handling using the Python requests library.

```python
import requests
from requests.auth import HTTPBasicAuth

base_url = "http://localhost:8000"

response = requests.post(
    f"{base_url}/v1/queries/",
    # Uncomment to use auth with key pair
    # auth=HTTPBasicAuth("pk-ark-xxxxx", "sk-ark-xxxxx"),
    headers={
        "Content-Type": "application/json",
        # Uncomment to use auth with bearer token
        # "Authorization": "Bearer YOUR_TOKEN_HERE",
    },
    json={
        "name": "python-query",
        "type": "user",
        "input": "Summarize the latest updates",
        "target": {"type": "agent", "name": "my-agent"},
        # Optional: continue a conversation
        # "conversationId": "previous-conversation-id",
        # Optional: session tracking
        # "sessionId": "my-session-id",
        # Optional: query timeout
        # "timeout": "5m",
    }
)

response.raise_for_status()
query = response.json()
print(query["status"]["response"]["content"])
```

--------------------------------

### Install Ark Controller via Helm

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/operations-guide/postgres-storage-backend.mdx

Install the Ark controller chart using Helm, specifying PostgreSQL as the storage backend. This command also disables CRD installation.

```bash
helm upgrade --install ark-controller \
  oci://ghcr.io/mckinsey/agents-at-scale-ark/charts/ark-controller \
  --namespace ark-system --create-namespace \
  --set rbac.enable=true \
  --set storage.backend=postgresql
```

--------------------------------

### Install Ark via CLI

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/operations-guide/postgres-storage-backend.mdx

Use the Ark CLI to install the controller and API server with PostgreSQL as the storage backend. This command configures the backend and disables CRD installation.

```bash
ark install
```

--------------------------------

### Install Ark with PostgreSQL Backend

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/core-architecture.mdx

Install Ark using Helm, overriding default values to enable the PostgreSQL backend and specify connection parameters.

```bash
helm install ark ./ark/dist/chart -n ark-system \
  --set storage.backend=postgresql \
  --set storage.postgresql.host=postgresql \
  --set storage.postgresql.user=postgres \
  --set storage.postgresql.passwordSecretName=postgresql-credentials

```

--------------------------------

### Install Cert-Manager via Helm

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/operations-guide/deploying-ark.mdx

Installs cert-manager, a prerequisite for Ark, using Helm. This command adds the Jetstack Helm repository and upgrades or installs cert-manager in the cert-manager namespace.

```bash
# Install cert-manager
helm repo add jetstack https://charts.jetstack.io --force-update  
helm repo update
helm upgrade --install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true
```

--------------------------------

### Query Input with Template Syntax Example

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/resources/query.mdx

Shows how to use Go template syntax within the 'input' field of a Query to dynamically insert parameter values like environment, database host, port, and user.

```yaml
input: |
  Environment: {{.environment}}
  Database: {{.db_host}}:{{.db_port}}
  User: {{.db_user}}

```

--------------------------------

### Install Core Dependencies on macOS

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/reference/troubleshooting.mdx

Installs Node.js, kubectl, and Helm using Homebrew. Also provides commented-out commands for installing local Kubernetes clusters like Minikube, Kind, or Orbstack.

```bash
brew install node kubectl helm

# Install a cluster such as:
# brew install minikube
# brew install kind
# brew install orbstack
```

--------------------------------

### Install fark CLI from GitHub Release

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/cli-tools.mdx

Installs the `fark` CLI by downloading the latest release archive from GitHub. Ensure you have `curl` and `tar` installed. For Windows, download the zip file manually.

```bash
# Download latest release for your platform
# Linux/macOS
curl -L "https://github.com/mckinsey/agents-at-scale-ark/releases/latest/download/fark_$(uname)_$(uname -m | sed 's/aarch64/arm64/').tar.gz" | tar xz
sudo mv fark /usr/local/bin/

# Windows: Download fark_Windows_x86_64.zip from releases page

# Verify installation
fark --help
```

--------------------------------

### Deploy Individual Samples

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/samples/README.md

Use these commands to deploy individual QBAF samples. Ensure you have kubectl configured to your Kubernetes cluster.

```bash
kubectl apply -f samples/quickstart/azure-openai-model.yaml
```

```bash
kubectl apply -f samples/agents/simple-agent-with-query.yaml
```

```bash
kubectl apply -f samples/agents/templated.yaml -f samples/agents/shared.yaml
```

```bash
kubectl apply -f samples/workflows/weather-forecast-workflow.yaml
```

--------------------------------

### API Parameter Substitution Examples

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/tools/fark/docs/WORKFLOW.md

Demonstrates various ways to configure URL parameters for HTTP tools, including path parameters, query parameters, and how to use them within the 'url' field. It also shows how to set authentication headers using Kubernetes secrets.

```yaml
# REST API with path parameters
fetcher:
  url: "https://api.example.com/users/{userId}/posts/{postId}"

# REST API with query parameters  
fetcher:
  url: "https://api.example.com/search?q={query}&limit={limit}"

# API with authentication headers using secrets
fetcher:
  url: "https://api.example.com/data"
  headers:
    - name: "Authorization"
      value:
        valueFrom:
          secretKeyRef:
            name: api-secret
            key: bearer-token
    - name: "X-API-Key"
      value:
        valueFrom:
          secretKeyRef:
            name: api-secret
            key: api-key

# POST requests with form data
fetcher:
  method: POST
  headers:
    - name: "Content-Type"
      value:
        value: "application/x-www-form-urlencoded"
```

--------------------------------

### Build Ark Controller (Go)

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/CLAUDE.md

Commands to build, test, and deploy the Ark Controller written in Go. Ensure you are in the 'ark/' directory.

```bash
cd ark/
make build         # Build manager binary
make test          # Run tests with coverage
make docker-build  # Build Docker image
make deploy        # Deploy to K8s cluster
make dev           # Run in development mode
```

--------------------------------

### Install kubectl on macOS

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/developer-guide/cli-tools.mdx

Install the kubectl command-line tool on macOS using Homebrew.

```bash
# macOS
brew install kubectl
```

--------------------------------

### Create a Query File

Source: https://github.com/mckinsey/agents-at-scale-ark/blob/main/docs/content/user-guide/starting-new-project-example.mdx

Define a query to interact with an agent. This example sets up a query for the 'support-agent' to ask about subscription upgrades.

```bash
cat > queries/test-billing.yaml <<'EOF' \
apiVersion: ark.mckinsey.com/v1alpha1 \
kind: Query \
metadata: \
  name: test-billing \
spec: \
  target: \
    agent: \
    name: support-agent \
  input: \
    type: message \
    message: "How can I upgrade my subscription plan?" \
EOF
```