@chandshantanu/agentbuilder-mcp-server 0.2.0

package/AGENT_CREATION_GUIDE.md

@@ -0,0 +1,724 @@
+# Agent Creation Guide - MCP Server
+
+## Overview
+
+The AgentBuilder MCP server now supports complete agent creation and configuration workflow. Sellers can create, configure, and publish agents directly through Claude Code without needing to access the web dashboard.
+
+**New Capabilities**:
+- ✅ Create new agents from scratch
+- ✅ Define wizard configuration for user onboarding
+- ✅ Set LangGraph workflow definitions
+- ✅ Validate agent before publishing
+- ✅ Publish to marketplace
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+1. **Seller Account**: You need a seller account
+   - Email: `shantanu.chandra@banxwayglobal.com`
+   - Password: See CLAUDE.md for credentials
+
+2. **MCP Connection**: Establish connection to AgentBuilder
+   ```
+   Use tool: set_connection
+   Connection ID: mcp_conn_xxx (from dashboard)
+   ```
+
+3. **Claude Code**: Ensure you're using Claude Code with MCP server configured
+
+---
+
+## Complete Workflow
+
+### Step 1: Create Agent
+
+Create a new agent with basic information:
+
+```json
+{
+  "name": "Instagram DM Sales Agent",
+  "description": "AI-powered sales agent that responds to Instagram DMs with product recommendations",
+  "detailed_description": "This agent connects to your Instagram Business account and e-commerce platform to automatically respond to customer inquiries with personalized product recommendations using RAG and GPT-4.",
+  "type": "conversational",
+  "category": "Sales",
+  "tags": ["instagram", "sales", "e-commerce", "ai"],
+  "is_public": false,
+  "pricing": {
+    "model": "subscription",
+    "monthly_price": 2999,
+    "currency": "INR",
+    "trial_enabled": true,
+    "trial_duration_days": 30
+  }
+}
+```
+
+**Tool**: `create_agent`
+
+**Response**:
+```json
+{
+  "id": "65f1a2b3c4d5e6f7a8b9c0d1",
+  "name": "Instagram DM Sales Agent",
+  "slug": "instagram-dm-sales-agent",
+  "status": "draft",
+  "created_at": "2026-02-06T..."
+}
+```
+
+**Save the `id` for next steps!**
+
+---
+
+### Step 2: Set Wizard Configuration
+
+Define the onboarding wizard for users who subscribe to your agent:
+
+```json
+{
+  "agent_id": "65f1a2b3c4d5e6f7a8b9c0d1",
+  "wizard_configuration": {
+    "required_oauth_providers": [
+      "facebook"
+    ],
+    "required_credentials": [
+      {
+        "key": "openrouter_api_key",
+        "label": "OpenRouter API Key",
+        "type": "api_key",
+        "required": true,
+        "placeholder": "sk-or-v1-...",
+        "help_text": "Get your API key from openrouter.ai",
+        "validation_regex": "^sk-or-v1-",
+        "secure": true,
+        "setup_guide": {
+          "title": "How to get OpenRouter API key",
+          "steps": [
+            "1. Go to openrouter.ai",
+            "2. Sign up or log in",
+            "3. Navigate to Keys section",
+            "4. Generate new API key"
+          ],
+          "documentation_url": "https://openrouter.ai/docs/quick-start"
+        }
+      }
+    ],
+    "required_platform_config": [
+      {
+        "key": "platform_type",
+        "label": "E-Commerce Platform",
+        "type": "select",
+        "options": ["shopify", "woocommerce", "custom"],
+        "required": true,
+        "help_text": "Select your e-commerce platform"
+      },
+      {
+        "key": "shopify_store_url",
+        "label": "Shopify Store URL",
+        "type": "url",
+        "required": true,
+        "depends_on": "platform_type=shopify",
+        "placeholder": "https://yourstore.myshopify.com",
+        "help_text": "Your Shopify store URL"
+      },
+      {
+        "key": "shopify_api_key",
+        "label": "Shopify API Key",
+        "type": "api_key",
+        "required": true,
+        "depends_on": "platform_type=shopify",
+        "secure": true
+      }
+    ],
+    "custom_wizard_steps": [
+      {
+        "step_id": "instagram_page_selection",
+        "title": "Select Instagram Page",
+        "description": "Choose which Instagram Business account to connect",
+        "component_name": "InstagramPageSelector",
+        "after_step": "oauth",
+        "required": true
+      },
+      {
+        "step_id": "product_catalog_sync",
+        "title": "Sync Product Catalog",
+        "description": "Configure product synchronization settings",
+        "component_name": "ProductCatalogSync",
+        "after_step": "instagram_page_selection",
+        "required": true
+      }
+    ],
+    "configuration_defaults": {
+      "sync_frequency": "realtime",
+      "product_fields": ["name", "price", "description", "images", "inventory"],
+      "response_tone": "friendly",
+      "max_products_per_response": 3
+    }
+  }
+}
+```
+
+**Tool**: `set_agent_wizard_config`
+
+**What gets validated**:
+- ✅ OAuth providers are valid (facebook, instagram, google, etc.)
+- ✅ Credential fields have required properties (key, label, type)
+- ✅ Platform config types are valid (select, text, url, etc.)
+- ✅ Conditional logic (depends_on) references existing fields
+- ✅ Custom steps have required properties
+
+---
+
+### Step 3: Set Agent Graph
+
+Define the LangGraph workflow that executes when the agent runs:
+
+```json
+{
+  "agent_id": "65f1a2b3c4d5e6f7a8b9c0d1",
+  "graph": {
+    "nodes": [
+      {
+        "id": "webhook_receiver",
+        "type": "webhook",
+        "config": {
+          "path": "/webhook/instagram",
+          "method": "POST"
+        }
+      },
+      {
+        "id": "extract_message",
+        "type": "transformer",
+        "config": {
+          "extract": ["message_text", "sender_id", "conversation_id"]
+        }
+      },
+      {
+        "id": "classify_intent",
+        "type": "llm_classifier",
+        "config": {
+          "model": "openai/gpt-4o-mini",
+          "categories": [
+            "product_inquiry",
+            "pricing_question",
+            "availability_check",
+            "order_status",
+            "general_support"
+          ],
+          "system_prompt": "Classify customer intent based on Instagram DM"
+        }
+      },
+      {
+        "id": "search_products",
+        "type": "vector_search",
+        "config": {
+          "embedding_model": "text-embedding-3-small",
+          "index_name": "products",
+          "top_k": 5,
+          "similarity_threshold": 0.7
+        }
+      },
+      {
+        "id": "generate_response",
+        "type": "llm_chat",
+        "config": {
+          "model": "openai/gpt-4o",
+          "system_prompt": "You are a helpful sales assistant for {business_name}. Respond to customer inquiries about products with relevant recommendations.",
+          "max_tokens": 500,
+          "temperature": 0.7
+        }
+      },
+      {
+        "id": "send_instagram_reply",
+        "type": "api_call",
+        "config": {
+          "method": "POST",
+          "url": "https://graph.facebook.com/v18.0/{page_id}/messages",
+          "headers": {
+            "Authorization": "Bearer {instagram_access_token}"
+          },
+          "body": {
+            "recipient": {"id": "{sender_id}"},
+            "message": {"text": "{generated_response}"}
+          }
+        }
+      },
+      {
+        "id": "log_conversation",
+        "type": "database_insert",
+        "config": {
+          "collection": "conversations",
+          "fields": ["sender_id", "message_text", "response", "intent", "timestamp"]
+        }
+      }
+    ],
+    "edges": [
+      {
+        "from": "webhook_receiver",
+        "to": "extract_message"
+      },
+      {
+        "from": "extract_message",
+        "to": "classify_intent"
+      },
+      {
+        "from": "classify_intent",
+        "to": "search_products",
+        "condition": "intent in ['product_inquiry', 'availability_check']"
+      },
+      {
+        "from": "classify_intent",
+        "to": "generate_response",
+        "condition": "intent not in ['product_inquiry', 'availability_check']"
+      },
+      {
+        "from": "search_products",
+        "to": "generate_response"
+      },
+      {
+        "from": "generate_response",
+        "to": "send_instagram_reply"
+      },
+      {
+        "from": "send_instagram_reply",
+        "to": "log_conversation"
+      }
+    ],
+    "entry_point": "webhook_receiver"
+  }
+}
+```
+
+**Tool**: `set_agent_graph`
+
+**Available Node Types**:
+- `webhook` - Receive webhooks
+- `transformer` - Transform data
+- `llm_classifier` - Classify with LLM
+- `vector_search` - RAG search
+- `llm_chat` - Generate responses
+- `api_call` - External API calls
+- `database_insert` - Save to database
+- `delay` - Wait/delay
+- `conditional` - Conditional branching
+- `parallel` - Parallel execution
+- `loop` - Loop execution
+
+**What gets validated**:
+- ✅ All node types are valid
+- ✅ All edges reference existing nodes
+- ✅ Entry point exists in nodes
+- ✅ No circular dependencies
+- ✅ Required config for each node type
+
+---
+
+### Step 4: Add Media (Optional but Recommended)
+
+Add icon, banner, and screenshots for better marketplace presence:
+
+```json
+{
+  "agent_id": "65f1a2b3c4d5e6f7a8b9c0d1",
+  "updates": {
+    "icon_url": "https://your-cdn.com/instagram-dm-agent-icon.png",
+    "banner_url": "https://your-cdn.com/instagram-dm-agent-banner.png",
+    "screenshots": [
+      "https://your-cdn.com/screenshot-1.png",
+      "https://your-cdn.com/screenshot-2.png",
+      "https://your-cdn.com/screenshot-3.png"
+    ],
+    "demo_url": "https://youtube.com/watch?v=...",
+    "video_url": "https://your-cdn.com/promo-video.mp4"
+  }
+}
+```
+
+**Tool**: `update_agent`
+
+---
+
+### Step 5: Validate Agent
+
+Before publishing, validate your agent configuration:
+
+```json
+{
+  "agent_id": "65f1a2b3c4d5e6f7a8b9c0d1"
+}
+```
+
+**Tool**: `validate_agent_configuration`
+
+**Response**:
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": [
+    "Testing status unknown. Ensure agent has been tested before publishing."
+  ],
+  "checklist": {
+    "wizard_configuration": true,
+    "agent_graph": true,
+    "pricing": true,
+    "metadata": true,
+    "testing": false
+  }
+}
+```
+
+**If validation fails**, fix the errors and run validation again.
+
+---
+
+### Step 6: Publish Agent
+
+Once validation passes, publish to marketplace:
+
+```json
+{
+  "agent_id": "65f1a2b3c4d5e6f7a8b9c0d1"
+}
+```
+
+**Tool**: `publish_agent`
+
+**Response (for Sellers)**:
+```json
+{
+  "success": true,
+  "message": "Agent submitted for review",
+  "agent_id": "65f1a2b3c4d5e6f7a8b9c0d1",
+  "agent_name": "Instagram DM Sales Agent",
+  "status": "pending_review",
+  "marketplace_url": "/agents/instagram-dm-sales-agent"
+}
+```
+
+**Response (for Admins)**:
+```json
+{
+  "success": true,
+  "message": "Agent published successfully",
+  "agent_id": "65f1a2b3c4d5e6f7a8b9c0d1",
+  "agent_name": "Instagram DM Sales Agent",
+  "status": "active",
+  "marketplace_url": "/agents/instagram-dm-sales-agent"
+}
+```
+
+---
+
+## Tool Reference
+
+### create_agent
+
+**Description**: Create a new agent with basic information
+
+**Required Parameters**:
+- `name` (string): Agent name (1-100 chars)
+- `description` (string): Short description (max 1000 chars)
+- `type` (enum): conversational | workflow | analytical | creative | research | automation
+- `category` (string): Agent category (e.g., Sales, Customer Support)
+
+**Optional Parameters**:
+- `detailed_description` (string): Long description (max 5000 chars)
+- `tags` (array): Tags for discoverability (max 20)
+- `wizard_configuration` (object): Wizard config (can also set separately)
+- `graph` (object): Agent graph (can also set separately)
+- `pricing` (object): Pricing configuration
+- `icon_url`, `banner_url`, `screenshots`, `demo_url`, `video_url`
+- `is_public` (boolean): Default false
+
+---
+
+### set_agent_wizard_config
+
+**Description**: Set or update wizard configuration for agent onboarding
+
+**Required Parameters**:
+- `agent_id` (string): Agent ID
+- `wizard_configuration` (object): Complete wizard config
+
+**Wizard Configuration Structure**:
+```typescript
+{
+  required_oauth_providers: string[],  // e.g., ["facebook", "instagram"]
+  required_credentials: CredentialField[],
+  required_platform_config: PlatformConfigField[],
+  custom_wizard_steps: CustomWizardStep[],
+  configuration_defaults: object
+}
+```
+
+**Credential Field**:
+```typescript
+{
+  key: string,           // Field name in config
+  label: string,         // UI label
+  type: "api_key" | "oauth" | "password" | "text" | "secret",
+  required: boolean,
+  placeholder?: string,
+  help_text?: string,
+  validation_regex?: string,
+  secure?: boolean,      // Encrypt in database
+  setup_guide?: {
+    title: string,
+    steps: string[],
+    documentation_url: string
+  }
+}
+```
+
+**Platform Config Field**:
+```typescript
+{
+  key: string,
+  label: string,
+  type: "select" | "text" | "url" | "number" | "checkbox" | "textarea",
+  options?: string[],    // Required for select type
+  required: boolean,
+  depends_on?: string,   // e.g., "platform_type=shopify"
+  placeholder?: string,
+  help_text?: string
+}
+```
+
+---
+
+### set_agent_graph
+
+**Description**: Set LangGraph workflow definition
+
+**Required Parameters**:
+- `agent_id` (string): Agent ID
+- `graph` (object): Complete graph definition
+
+**Graph Structure**:
+```typescript
+{
+  nodes: Array<{
+    id: string,
+    type: string,  // See available node types
+    config: object
+  }>,
+  edges: Array<{
+    from: string,
+    to: string,
+    condition?: string  // Optional condition
+  }>,
+  entry_point: string  // Node ID to start execution
+}
+```
+
+---
+
+### validate_agent_configuration
+
+**Description**: Validate agent before publishing
+
+**Required Parameters**:
+- `agent_id` (string): Agent ID
+
+**Returns**:
+```typescript
+{
+  valid: boolean,
+  errors: string[],
+  warnings: string[],
+  checklist: {
+    wizard_configuration: boolean,
+    agent_graph: boolean,
+    pricing: boolean,
+    metadata: boolean,
+    testing: boolean
+  }
+}
+```
+
+---
+
+### publish_agent
+
+**Description**: Publish agent to marketplace
+
+**Required Parameters**:
+- `agent_id` (string): Agent ID
+
+**Behavior**:
+- **Sellers**: Agent status → `pending_review`
+- **Admins**: Agent status → `active`
+
+---
+
+### update_agent
+
+**Description**: Update existing agent metadata
+
+**Required Parameters**:
+- `agent_id` (string): Agent ID
+- `updates` (object): Fields to update (partial)
+
+**Updatable Fields**:
+- All create_agent fields except `creator_id`
+- Can update wizard_configuration and graph separately using dedicated tools
+
+---
+
+## Examples
+
+### Example 1: Simple Chatbot Agent
+
+```json
+{
+  "name": "Customer Support Bot",
+  "description": "24/7 AI customer support assistant",
+  "type": "conversational",
+  "category": "Customer Support",
+  "graph": {
+    "nodes": [
+      {"id": "receive", "type": "webhook"},
+      {"id": "respond", "type": "llm_chat", "config": {"model": "gpt-4o"}},
+      {"id": "send", "type": "api_call"}
+    ],
+    "edges": [
+      {"from": "receive", "to": "respond"},
+      {"from": "respond", "to": "send"}
+    ],
+    "entry_point": "receive"
+  }
+}
+```
+
+### Example 2: Research Agent
+
+```json
+{
+  "name": "Market Research Agent",
+  "description": "Automated market research and analysis",
+  "type": "research",
+  "category": "Analytics",
+  "graph": {
+    "nodes": [
+      {"id": "trigger", "type": "webhook"},
+      {"id": "search_web", "type": "api_call"},
+      {"id": "analyze", "type": "llm_chat"},
+      {"id": "save", "type": "database_insert"}
+    ],
+    "edges": [
+      {"from": "trigger", "to": "search_web"},
+      {"from": "search_web", "to": "analyze"},
+      {"from": "analyze", "to": "save"}
+    ],
+    "entry_point": "trigger"
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Wizard Configuration
+
+✅ **DO**:
+- Provide clear help text for all fields
+- Include setup guides for complex credentials
+- Use validation regex for API keys
+- Mark sensitive fields as `secure: true`
+- Test the wizard flow before publishing
+
+❌ **DON'T**:
+- Ask for unnecessary credentials
+- Use vague labels like "Key 1", "Key 2"
+- Skip placeholder examples
+- Forget to validate OAuth scopes
+
+### 2. Agent Graph
+
+✅ **DO**:
+- Start with webhook receiver
+- Use descriptive node IDs
+- Add error handling nodes
+- Log important events
+- Test each node independently
+
+❌ **DON'T**:
+- Create circular dependencies
+- Skip entry_point validation
+- Use hardcoded credentials in config
+- Forget to handle edge cases
+
+### 3. Publishing
+
+✅ **DO**:
+- Add icon and banner before publishing
+- Write detailed descriptions
+- Include screenshots and demo video
+- Test with real users first
+- Monitor after publishing
+
+❌ **DON'T**:
+- Publish without validation
+- Skip testing phase
+- Use generic descriptions
+- Ignore validation warnings
+
+---
+
+## Troubleshooting
+
+### Validation Errors
+
+**"Wizard configuration not set"**
+- Run `set_agent_wizard_config` first
+
+**"Agent graph not set"**
+- Run `set_agent_graph` first
+
+**"Invalid OAuth provider: xxx"**
+- Use valid providers: facebook, instagram, google, etc.
+- See validator for complete list
+
+**"Node type 'xxx' not found"**
+- Use valid node types (webhook, llm_classifier, etc.)
+- See available node types list
+
+**"Edge references non-existent node 'xxx'"**
+- Check all edge `from` and `to` reference valid node IDs
+
+**"Entry point 'xxx' not found in nodes"**
+- Ensure `entry_point` matches a node ID
+
+### Publishing Errors
+
+**"Agent validation failed"**
+- Run `validate_agent_configuration` to see specific errors
+- Fix errors and try again
+
+**"Permission required: agents.create"**
+- You need seller role or higher
+- Contact admin to upgrade account
+
+**"Agent not found"**
+- Check agent_id is correct
+- Ensure you're authenticated
+
+---
+
+## Support
+
+For issues or questions:
+- GitHub: https://github.com/anthropics/claude-code/issues
+- Documentation: See CLAUDE.md
+- Backend API: https://agentsapi.chatslytics.com
+
+---
+
+**Last Updated**: 2026-02-06
+**Version**: 1.0.0
+**Author**: Development Team