@chandshantanu/agentbuilder-mcp-server 0.2.0

package/AGENT_DEPLOYMENT_GUIDE.md

@@ -0,0 +1,509 @@
+# AgentBuilder MCP - Agent Deployment Guide
+
+**Version**: 0.2.0
+**Date**: 2026-01-27
+**Status**: Production Ready
+
+---
+
+## 📋 Overview
+
+The AgentBuilder MCP server now supports deploying marketplace agents directly to Kubernetes production environment via the `deploy_agent` tool. Deployed agents automatically appear in the seller/admin/creator dashboard and use the configuration created during agent setup.
+
+---
+
+## 🚀 Agent Deployment Workflow
+
+### Complete Flow
+
+```
+1. Create/Configure Agent in Dashboard
+   ↓
+2. Deploy via MCP (uses stored configuration)
+   ↓
+3. Agent deploys to Kubernetes (AKS)
+   ↓
+4. Deployment appears in Seller/Admin Dashboard
+   ↓
+5. Monitor deployment status
+   ↓
+6. Access deployed agent endpoint
+```
+
+### Architecture
+
+- **Agent Creation**: Agents are created via web dashboard with full configuration
+- **Configuration Storage**: Agent configuration is stored in MongoDB during creation
+- **MCP Deployment**: MCP `deploy_agent` tool triggers deployment using stored config
+- **Kubernetes**: Agent deployed as pods on Azure Kubernetes Service (AKS)
+- **Dashboard Visibility**: Deployed agents visible in seller/admin/creator dashboard
+- **Access Control**: Only agent owner or admin/seller can deploy and manage
+
+---
+
+## 🔧 Using the deploy_agent Tool
+
+### Basic Deployment
+
+```typescript
+// In Claude Code, ask:
+"Deploy agent <agent_id>"
+
+// Or more specifically:
+"Deploy agent 65abc123def456789 to production"
+```
+
+### With Custom Configuration
+
+```typescript
+// Deploy with specific resource allocation
+"Deploy agent 65abc123def456789 with 3 replicas and 1GB memory"
+
+// Deploy with full configuration
+Deploy agent 65abc123def456789 with configuration:
+{
+  "replicas": 2,
+  "cpu_request": "500m",
+  "cpu_limit": "1000m",
+  "memory_request": "512Mi",
+  "memory_limit": "1Gi"
+}
+```
+
+### MCP Tool Parameters
+
+```typescript
+deploy_agent({
+  agent_id: string,              // Required: Agent ID to deploy
+  deployment_config?: {          // Optional: Deployment configuration
+    replicas?: number,           // Number of pod replicas (default: 1)
+    cpu_request?: string,        // CPU request per pod (default: "100m")
+    cpu_limit?: string,          // CPU limit per pod (default: "500m")
+    memory_request?: string,     // Memory request per pod (default: "128Mi")
+    memory_limit?: string,       // Memory limit per pod (default: "512Mi")
+    image?: string               // Container image (auto-selected if not provided)
+  }
+})
+```
+
+---
+
+## 🔐 Permissions & Access Control
+
+### Who Can Deploy Agents?
+
+- **Agent Owner**: The user who created the agent
+- **Sellers**: Users with SELLER or CREATOR_ADMIN role
+- **Admins**: Users with ADMIN or SUPER_ADMIN role
+
+### Required Permissions
+
+- Agent must exist and be owned by user OR user must have seller/admin role
+- User must be authenticated via OAuth 2.0 (production) or JWT (dev/test)
+- Agent configuration must be valid and complete
+
+---
+
+## 📊 Deployment Response
+
+### Successful Deployment
+
+```json
+{
+  "success": true,
+  "deployment_id": "agent-65abc123-a1b2c3d4",
+  "agent_id": "65abc123def456789",
+  "agent_name": "Instagram DM Sales Agent",
+  "status": "pending",
+  "namespace": "agent-deployments",
+  "replicas": 1,
+  "endpoint_url": null,
+  "created_at": "2026-01-27T01:15:30Z",
+  "message": "Agent deployment initiated successfully. Deployment will be ready in 2-3 minutes."
+}
+```
+
+### MCP Tool Response (Formatted)
+
+```
+✅ Agent Deployment Initiated
+
+📋 Deployment Details:
+   Agent: Instagram DM Sales Agent
+   Deployment ID: agent-65abc123-a1b2c3d4
+   Status: pending
+   Namespace: agent-deployments
+   Replicas: 1
+   Created: 2026-01-27T01:15:30Z
+
+⏱️  Agent deployment initiated successfully. Deployment will be ready in 2-3 minutes.
+
+📊 Next Steps:
+   1. Monitor deployment status in seller/admin dashboard
+   2. Wait 2-3 minutes for pods to become ready
+   3. Check endpoint health once deployed
+   4. Configure custom domain (optional)
+
+💡 View deployment in dashboard:
+   https://agents.chatslytics.com/seller/instances
+```
+
+---
+
+## 🎯 Dashboard Integration
+
+### Where Deployed Agents Appear
+
+**For Sellers/Creators:**
+```
+Dashboard → Seller Area → Deployed Instances
+URL: https://agents.chatslytics.com/seller/instances
+```
+
+**For Admins:**
+```
+Dashboard → Admin Panel → Agent Deployments
+URL: https://agents.chatslytics.com/admin/deployments
+```
+
+### Dashboard Features
+
+- **Deployment List**: View all your deployed agent instances
+- **Status Monitoring**: Real-time deployment status (pending, running, failed)
+- **Resource Metrics**: CPU, memory, replica count
+- **Endpoint Access**: Direct link to agent API endpoint
+- **Management Actions**:
+  - Scale replicas up/down
+  - View logs
+  - Restart deployment
+  - Terminate deployment
+
+---
+
+## 🐳 Container Images
+
+### Available Agent Images
+
+Agents are automatically deployed with the appropriate container image based on agent type:
+
+| Agent Type | Container Image | Registry |
+|-----------|----------------|----------|
+| Instagram DM | `instagram-dm-agent:latest` | acragentbuilder.azurecr.io |
+| Patient Follow-up | `patient-followup-agent:latest` | acragentbuilder.azurecr.io |
+| Custom Agent | `agent-base:latest` | acragentbuilder.azurecr.io |
+
+### Image Selection Logic
+
+```typescript
+// Auto-selection based on agent type
+agent_type === "instagram_dm" → instagram-dm-agent:latest
+agent_type === "patient_followup" → patient-followup-agent:latest
+agent_type === "custom" → agent-base:latest
+```
+
+### Using Custom Images
+
+```typescript
+// Override with specific image
+Deploy agent 65abc123def456789 with configuration:
+{
+  "image": "acragentbuilder.azurecr.io/my-custom-agent:v2.0.0"
+}
+```
+
+---
+
+## 🔄 Deployment Lifecycle
+
+### Status Flow
+
+```
+PENDING → CREATING → RUNNING
+                   ↓
+                 FAILED
+```
+
+### Status Descriptions
+
+- **PENDING**: Deployment request received, queued for processing
+- **CREATING**: Kubernetes resources being created (pods, services, ingress)
+- **RUNNING**: Agent pods running and healthy, endpoint accessible
+- **FAILED**: Deployment failed (check logs for details)
+
+### Typical Timeline
+
+```
+0:00 - Deployment initiated (status: PENDING)
+0:10 - Namespace & resources created (status: CREATING)
+0:30 - Pods starting up
+1:00 - Health checks passing
+2:00 - Deployment ready (status: RUNNING)
+```
+
+---
+
+## 🏗️ Infrastructure Details
+
+### Kubernetes Resources Created
+
+For each agent deployment:
+
+1. **ConfigMap**: Agent configuration (`agent-config-{deployment-id}`)
+2. **Secret**: API credentials (`agent-secret-{deployment-id}`)
+3. **Deployment**: Pod orchestration (`agent-deployment-{deployment-id}`)
+4. **Service**: Internal networking (`agent-service-{deployment-id}`)
+5. **Ingress**: External access (`agent-ingress-{deployment-id}`)
+
+### Default Resource Allocation
+
+```yaml
+Resources per Pod:
+  CPU Request: 100m (0.1 cores)
+  CPU Limit: 500m (0.5 cores)
+  Memory Request: 128Mi
+  Memory Limit: 512Mi
+
+Replicas: 1 (scalable)
+
+Namespace: agent-deployments
+```
+
+### Scaling
+
+```typescript
+// Scale via dashboard or API
+Scale to 3 replicas for high availability
+Scale to 5 replicas for peak traffic
+Scale down to 1 replica for cost savings
+```
+
+---
+
+## 🌐 Accessing Deployed Agents
+
+### Endpoint Format
+
+```
+https://agent-{deployment-id}.agents.agentbuilder.ai
+```
+
+### Example Endpoint
+
+```bash
+# Deployment ID: agent-65abc123-a1b2c3d4
+# Endpoint: https://agent-agent-65abc123-a1b2c3d4.agents.agentbuilder.ai
+
+# Health check
+curl https://agent-agent-65abc123-a1b2c3d4.agents.agentbuilder.ai/health
+
+# Execute agent
+curl -X POST https://agent-agent-65abc123-a1b2c3d4.agents.agentbuilder.ai/execute \
+  -H "Content-Type: application/json" \
+  -d '{"input": {"message": "Hello"}}'
+```
+
+---
+
+## 🔍 Monitoring Deployments
+
+### Via MCP (Future Enhancement)
+
+```typescript
+// Check deployment status
+Get deployment status for agent-65abc123-a1b2c3d4
+
+// View deployment logs
+Get logs for deployment agent-65abc123-a1b2c3d4
+
+// List all deployments
+List all my agent deployments
+```
+
+### Via Dashboard
+
+1. Navigate to Seller/Admin area
+2. Click on deployment to view details
+3. View real-time metrics:
+   - Pod status (running/pending/failed)
+   - CPU & memory usage
+   - Request count
+   - Error rate
+   - Uptime
+
+### Via kubectl (For Admins)
+
+```bash
+# Get all agent deployments
+kubectl get deployments -n agent-deployments -l app=agentbuilder
+
+# Get specific deployment
+kubectl get deployment agent-deployment-{deployment-id} -n agent-deployments
+
+# View pod status
+kubectl get pods -n agent-deployments -l deployment-id={deployment-id}
+
+# View logs
+kubectl logs -f deployment/agent-deployment-{deployment-id} -n agent-deployments
+
+# Describe deployment
+kubectl describe deployment agent-deployment-{deployment-id} -n agent-deployments
+```
+
+---
+
+## ⚠️ Troubleshooting
+
+### Deployment Stuck in PENDING
+
+**Symptoms**: Deployment status remains "pending" for >5 minutes
+
+**Possible Causes**:
+- Kubernetes cluster at capacity
+- Image pull issues
+- Invalid configuration
+
+**Solutions**:
+```bash
+# Check pod events
+kubectl describe pod -n agent-deployments -l deployment-id={deployment-id}
+
+# Check image pull status
+kubectl get events -n agent-deployments --sort-by='.lastTimestamp'
+
+# View pod logs
+kubectl logs -n agent-deployments -l deployment-id={deployment-id}
+```
+
+### Deployment FAILED
+
+**Symptoms**: Deployment status shows "failed"
+
+**Possible Causes**:
+- Invalid agent configuration
+- Missing API credentials
+- Resource quota exceeded
+- Image not found
+
+**Solutions**:
+1. Check deployment logs in dashboard
+2. Verify agent configuration is valid
+3. Ensure API credentials are correct
+4. Check cluster resource availability
+5. Re-deploy with corrected configuration
+
+### Endpoint Not Accessible
+
+**Symptoms**: Deployment shows "running" but endpoint returns errors
+
+**Possible Causes**:
+- Pods not healthy yet (wait 2-3 minutes)
+- Health checks failing
+- Ingress configuration issues
+- DNS not propagated
+
+**Solutions**:
+```bash
+# Check pod health
+kubectl get pods -n agent-deployments -l deployment-id={deployment-id}
+
+# Check service
+kubectl get service agent-service-{deployment-id} -n agent-deployments
+
+# Check ingress
+kubectl get ingress agent-ingress-{deployment-id} -n agent-deployments
+
+# Test internal service
+kubectl port-forward -n agent-deployments service/agent-service-{deployment-id} 8080:80
+curl http://localhost:8080/health
+```
+
+---
+
+## 🎓 Examples
+
+### Example 1: Deploy Instagram DM Agent
+
+```typescript
+// In Claude Code:
+"List my agents and deploy the Instagram DM Sales Agent"
+
+// Claude will:
+1. List available agents
+2. Find Instagram DM agent (ID: 65abc123def456789)
+3. Deploy with default configuration
+4. Return deployment details
+```
+
+### Example 2: Deploy with High Availability
+
+```typescript
+// In Claude Code:
+"Deploy agent 65abc123def456789 with 3 replicas for high availability"
+
+// Deployment config:
+{
+  "replicas": 3,
+  "cpu_request": "500m",
+  "cpu_limit": "1000m",
+  "memory_request": "512Mi",
+  "memory_limit": "1Gi"
+}
+```
+
+### Example 3: Deploy Custom Agent with Specific Image
+
+```typescript
+// In Claude Code:
+"Deploy custom agent 65abc987xyz with image acragentbuilder.azurecr.io/my-custom-agent:v2.1.0"
+
+// Deployment config:
+{
+  "image": "acragentbuilder.azurecr.io/my-custom-agent:v2.1.0",
+  "replicas": 2
+}
+```
+
+---
+
+## 📚 Related Documentation
+
+- **MCP Production Setup**: [MCP_PRODUCTION_SETUP_COMPLETE.md](../MCP_PRODUCTION_SETUP_COMPLETE.md)
+- **Agent Deployment Gap Analysis**: [AGENT_DEPLOYMENT_GAP_ANALYSIS.md](../AGENT_DEPLOYMENT_GAP_ANALYSIS.md)
+- **Build & Push Script**: [scripts/build-and-push-agents.sh](../scripts/build-and-push-agents.sh)
+- **Kubernetes Manifests**: [infrastructure/agent-memory/](../infrastructure/agent-memory/)
+
+---
+
+## 🔄 Next Steps
+
+After deploying an agent:
+
+1. ✅ **Monitor Status**: Watch deployment progress in dashboard
+2. ✅ **Test Endpoint**: Send test requests to agent endpoint
+3. ✅ **Configure Domain** (Optional): Set up custom domain
+4. ✅ **Enable Monitoring**: Set up alerts for deployment health
+5. ✅ **Scale as Needed**: Adjust replicas based on traffic
+6. ✅ **Generate API Keys**: Create customer API keys if needed
+7. ✅ **Update Documentation**: Add agent-specific usage docs
+
+---
+
+## 🎉 Success Criteria
+
+Your agent deployment is successful when:
+
+- ✅ Deployment status shows "RUNNING"
+- ✅ All pods are healthy (ready_replicas matches desired replicas)
+- ✅ Endpoint URL is accessible
+- ✅ Health check returns 200 OK
+- ✅ Deployment visible in dashboard
+- ✅ Test execution succeeds
+- ✅ Logs show no errors
+
+---
+
+**Deployment Guide Version**: 1.0.0
+**Last Updated**: 2026-01-27
+**Maintainer**: AgentBuilder Platform Team
+
+**🎊 Happy Deploying!**