@agents-at-scale/ark 0.1.37 → 0.1.38

package/templates/team/team.template.yaml

@@ -0,0 +1,17 @@
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Team
+metadata:
+  name: {{ .Values.teamName }}-team
+  labels:
+    project: {{ .Values.projectName }}
+    strategy: collaborative
+    tier: basic
+spec:
+  description: {{ .Values.teamName }} team for {{ .Values.projectName }} project
+
+  members:
+    - name: {{ .Values.agentName }}-agent
+      type: agent
+
+  # Sequential strategy for single-agent teams
+  strategy: "sequential"

package/templates/tool/.python-version

@@ -0,0 +1 @@
+3.12

package/templates/tool/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN pip install uv && \
+    mkdir -p /home/appuser/.cache/uv && \
+    groupadd -r appuser && \
+    useradd -r -g appuser appuser
+
+COPY pyproject.toml uv.lock ./
+
+RUN uv sync --frozen
+
+COPY src/ ./src/
+
+RUN chown -R appuser:appuser /app /home/appuser/.cache
+
+USER appuser
+
+EXPOSE 8000
+
+
+CMD ["uv", "run", "python", "-m", "src.main"]

package/templates/tool/README.md

@@ -0,0 +1,238 @@
+# Tool Service
+
+FastMCP-based tool service for creating custom tools that can be used by agents in the Ark framework.
+
+## How to Define New Tools
+
+### Step 1: Basic Tool Structure
+
+All tools follow this pattern in `main.py`:
+
+```python
+@mcp.tool
+def tool_name(
+    param: Annotated[type, "Parameter description"]
+) -> return_type:
+    """Tool description for the agent"""
+    # Implementation
+    return result
+```
+
+### Step 2: Add Your Tool Function
+
+Edit `main.py` and add your tool after the existing ones:
+
+```python
+@mcp.tool
+def your_new_tool(
+    param1: Annotated[str, "Description of first parameter"],
+    param2: Annotated[int, "Description of second parameter"] 
+) -> dict:
+    """What this tool does - agents will see this description"""
+    # Your logic here
+    result = {"output": f"Processed {param1} with {param2}"}
+    return result
+```
+
+### Step 3: Parameter Types and Annotations
+
+Use these common patterns:
+
+```python
+# String input
+text: Annotated[str, "Text to process"]
+
+# Numbers
+count: Annotated[int, "Number of items"]
+value: Annotated[float, "Decimal value"]
+
+# Optional parameters
+optional_param: Annotated[str | None, "Optional parameter"] = None
+
+# Lists
+items: Annotated[list[str], "List of items to process"]
+```
+
+### Step 4: Return Types
+
+Return structured data that agents can understand:
+
+```python
+# Simple values
+return "result string"
+return 42
+return 3.14
+
+# Dictionaries for complex data
+return {
+    "status": "success",
+    "data": result,
+    "count": len(items)
+}
+
+# Lists
+return ["item1", "item2", "item3"]
+```
+
+
+### Example: Complete New Tool
+
+Here's a complete example of adding a URL checker tool:
+
+```python
+import requests
+from typing import Annotated
+
+@mcp.tool
+def check_url(
+    url: Annotated[str, "URL to check"],
+    timeout: Annotated[int, "Timeout in seconds"] = 5
+) -> dict:
+    """Check if a URL is accessible and return status information"""
+    try:
+        response = requests.get(url, timeout=timeout)
+        return {
+            "url": url,
+            "status_code": response.status_code,
+            "accessible": response.status_code == 200,
+            "response_time_ms": int(response.elapsed.total_seconds() * 1000)
+        }
+    except Exception as e:
+        return {
+            "url": url,
+            "accessible": False,
+            "error": str(e)
+        }
+```
+
+## Build and Deploy
+
+### Option 1: Quick Deploy
+
+```bash
+./deploy.sh
+```
+
+### Option 2: Manual Steps
+
+```bash
+# Build Docker image
+docker build -t tool:latest .
+
+# Load into local cluster (check your cluster documentation)
+# For kind: kind load docker-image tool:latest
+# For minikube: use minikube docker-env or image loading commands
+
+# Deploy to Kubernetes
+kubectl apply -k deployment/
+```
+
+## Test Your Tools
+
+### Step 1: Create Test Agent
+
+Create `test-agent.yaml`:
+
+```yaml
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Agent
+metadata:
+  name: tool-test-agent
+spec:
+  prompt: You are helpful agent that uses tools to assist users.
+  modelRef:
+    name: gpt-4-model
+  mcpServers:
+    - name: tool
+      url: http://tool:8000/mcp
+```
+
+Apply it:
+```bash
+kubectl apply -f test-agent.yaml
+```
+
+### Step 2: Test with Ark Binary
+
+```bash
+# Test basic math
+fark agent tool-test-agent "Add 15 and 27"
+
+# Test text analysis  
+fark agent tool-test-agent "Count words in: hello world this is a test"
+
+# Test multiplication
+fark agent tool-test-agent "What is 8.5 times 12.3?"
+```
+
+### Step 3: Direct Tool Testing
+
+```bash
+# Port forward to test tools directly
+kubectl port-forward service/tool 8000:8000
+
+# Test MCP endpoint
+curl http://localhost:8000/mcp
+```
+
+## Common Tool Patterns
+
+### File Processing Tool
+```python
+@mcp.tool
+def process_file_content(
+    content: Annotated[str, "File content to process"],
+    operation: Annotated[str, "Operation: upper, lower, reverse"]
+) -> str:
+    """Process text content with specified operation"""
+    if operation == "upper":
+        return content.upper()
+    elif operation == "lower":
+        return content.lower()
+    elif operation == "reverse":
+        return content[::-1]
+    else:
+        return f"Unknown operation: {operation}"
+```
+
+### Data Analysis Tool
+```python
+@mcp.tool
+def analyze_numbers(
+    numbers: Annotated[list[float], "List of numbers to analyze"]
+) -> dict:
+    """Analyze a list of numbers and return statistics"""
+    if not numbers:
+        return {"error": "Empty list provided"}
+    
+    return {
+        "count": len(numbers),
+        "sum": sum(numbers),
+        "average": sum(numbers) / len(numbers),
+        "min": min(numbers),
+        "max": max(numbers)
+    }
+```
+
+### External API Tool
+```python
+@mcp.tool
+def get_weather(
+    city: Annotated[str, "City name for weather lookup"]
+) -> dict:
+    """Get weather information for a city"""
+    # Replace with actual weather API
+    return {
+        "city": city,
+        "temperature": "22°C",
+        "condition": "Sunny",
+        "humidity": "45%"
+    }
+```
+
+## Resources
+
+- **Deployment**: Tool pod with FastMCP server on port 8000
+- **Service**: Exposes tools internally at `http://tool:8000/mcp`
+- **MCPServer**: Configured for agent integration
+- **Agent Integration**: Reference tools via `mcpServers` in agent specs

package/templates/tool/agent.yaml

@@ -0,0 +1,19 @@
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Agent
+metadata:
+  name: sample-agent
+spec:
+  prompt: You're helpful agent. Always add amazing to the output. Use tools available to help the user.
+  tools:
+    - type: custom
+      name: tool-add
+---
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: Query
+metadata:
+  name: sample-query
+spec:
+  targets:
+    - name: sample-agent
+      type: agent
+  input: Calculate 3+2.

package/templates/tool/deploy.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -e
+
+cd "$(dirname "$0")"
+
+docker build -t tool:latest .
+# Load image into cluster - adjust command based on your cluster type
+# kind load docker-image tool:latest --name cluster-name
+# eval $(minikube docker-env) && docker build -t tool:latest .
+kubectl apply -k deployment/

package/templates/tool/deployment/deployment.yaml

@@ -0,0 +1,31 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: tool
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: tool
+  template:
+    metadata:
+      labels:
+        app: tool
+    spec:
+      serviceAccountName: {{ .Values.serviceAccount.name }}
+      containers:
+      - name: tool
+        image: tool:latest
+        imagePullPolicy: IfNotPresent
+        ports:
+        - containerPort: 8000
+        env:
+        - name: PORT
+          value: "8000"
+        resources:
+          requests:
+            memory: "128Mi"
+            cpu: "100m"
+          limits:
+            memory: "1024Mi"
+            cpu: "1000m"

package/templates/tool/deployment/kustomization.yaml

@@ -0,0 +1,7 @@
+apiVersion: kustomize.config.k8s.io/v1beta1
+kind: Kustomization
+
+resources:
+  - deployment.yaml
+  - service.yaml
+  - mcpserver.yaml

package/templates/tool/deployment/mcpserver.yaml

@@ -0,0 +1,12 @@
+apiVersion: ark.mckinsey.com/v1alpha1
+kind: MCPServer
+metadata:
+  name: tool
+spec:
+  address:
+    valueFrom:
+      serviceRef:
+        name: tool
+  transport: http
+  timeout: 30s
+  description: "Tool service MCP server"

package/templates/tool/deployment/service.yaml

@@ -0,0 +1,12 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: tool
+spec:
+  selector:
+    app: tool
+  ports:
+  - port: 8000
+    targetPort: 8000
+    protocol: TCP
+  type: ClusterIP

package/templates/tool/deployment/serviceaccount.yaml

@@ -0,0 +1,8 @@
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ .Values.serviceAccount.name }}
+  namespace: {{ .Release.Namespace }}
+  labels:
+    app: tool
+automountServiceAccountToken: false

package/templates/tool/deployment/values.yaml

@@ -0,0 +1,3 @@
+serviceAccount:
+  create: true
+  name: tool-sa

package/templates/tool/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "tool"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastmcp>=2.9.0",
+]

package/templates/tool/src/main.py

@@ -0,0 +1,36 @@
+from typing import Annotated
+from fastmcp import FastMCP
+
+mcp = FastMCP("Demo 🚀")
+
+
+@mcp.tool
+def add(
+    a: Annotated[int, "First number to add"], b: Annotated[int, "Second number to add"]
+) -> int:
+    """Add two integers and return the sum"""
+    return a + b
+
+
+@mcp.tool
+def multiply(
+    a: Annotated[float, "First number to multiply"],
+    b: Annotated[float, "Second number to multiply"],
+) -> float:
+    """Multiply two numbers and return the product"""
+    return a * b
+
+
+@mcp.tool
+def word_count(text: Annotated[str, "Text to analyze for word count"]) -> dict:
+    """Count words, characters, and unique words in the given text"""
+    words = text.split()
+    return {
+        "word_count": len(words),
+        "char_count": len(text),
+        "unique_words": len(set(word.lower() for word in words)),
+    }
+
+
+if __name__ == "__main__":
+    mcp.run(transport="http", host="0.0.0.0", port=8000, path="/")