MindraDocs

Agent Registration Guide

8 min read

Register your custom agent with Mindra Platform to make it available for orchestration.

Overview

After deploying your agent, register it with Mindra Platform so it can be:

  • Discovered by the orchestration engine
  • Selected based on capabilities and vertical
  • Used in multi-agent workflows
  • Monitored and tracked

Prerequisites

  • Deployed agent accessible via HTTPS
  • Valid Mindra API key with agents:write permission
  • Agent implements HTTP Agent Protocol correctly

Registration API

POST /v1/agents

Register a new agent.

Request:

curl -X POST https://api.mindra.co/v1/agents \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-custom-agent",
    "name": "My Custom Agent",
    "description": "Detailed description of what your agent does",
    "url": "https://my-agent.example.com",
    "vertical": "custom",
    "capabilities": ["capability1", "capability2"],
    "pricing": {
      "model": "per_execution",
      "basePrice": 0.50
    },
    "config": {
      "timeout": 30000,
      "retries": 3
    }
  }'

Response (201 Created):

{
  "id": "my-custom-agent",
  "name": "My Custom Agent",
  "description": "Detailed description of what your agent does",
  "url": "https://my-agent.example.com",
  "vertical": "custom",
  "capabilities": ["capability1", "capability2"],
  "pricing": {
    "model": "per_execution",
    "basePrice": 0.50
  },
  "config": {
    "timeout": 30000,
    "retries": 3
  },
  "isActive": true,
  "version": "1.0.0",
  "createdAt": "2025-11-10T10:00:00Z",
  "updatedAt": "2025-11-10T10:00:00Z"
}

Parameters

id (required)

Unique identifier for your agent.

Format: lowercase alphanumeric with hyphens Example: my-custom-agent, email-campaign-ai, blockchain-tx-processor

name (required)

Human-readable name for your agent.

Example: My Custom Agent, Email Campaign AI, Blockchain Transaction Processor

description (required)

Detailed description of what your agent does.

Length: 10-1000 characters Example:

"Advanced email campaign generator using AI. Creates personalized email content,
subject lines, and A/B test variations optimized for your target audience.
Supports 15+ languages and industry-specific templates."

url (required)

Public HTTPS URL where your agent is accessible.

Format: Must be HTTPS Example: https://my-agent.example.com, https://agents.mycompany.com/email-ai

vertical (required)

Business vertical your agent specializes in.

Options:

  • marketing - Marketing automation
  • cross-border - International payments and compliance
  • supply-chain - Logistics and inventory
  • finance - Financial analysis and reporting
  • hr - Human resources automation
  • legal - Legal document processing
  • healthcare - Healthcare and medical
  • education - Educational content
  • custom - Custom/other verticals

capabilities (required)

List of specific capabilities your agent provides.

Type: Array of strings Example:

{
  "capabilities": [
    "email_generation",
    "a_b_testing",
    "audience_segmentation",
    "analytics"
  ]
}

Common capabilities by vertical:

Marketing:

  • email_generation, social_media_content, seo_optimization, a_b_testing

Cross-Border:

  • multi_currency_conversion, compliance_check, payment_routing, kyc_verification

Supply-Chain:

  • demand_forecasting, inventory_optimization, shipment_tracking, route_optimization

pricing (required)

Pricing model for your agent.

Models:

  1. Per Execution (most common):
{
  "pricing": {
    "model": "per_execution",
    "basePrice": 0.50,
    "additionalCosts": {
      "per_email": 0.01,
      "per_variant": 0.05
    }
  }
}
  1. Per Transaction:
{
  "pricing": {
    "model": "per_transaction",
    "basePrice": 0.20,
    "percentageFee": 0.5
  }
}
  1. Subscription (for enterprise):
{
  "pricing": {
    "model": "subscription",
    "monthlyPrice": 99.00,
    "additionalCosts": {
      "per_user": 5.00
    }
  }
}

config (optional)

Agent configuration and constraints.

Fields:

  • timeout: Execution timeout in milliseconds (default: 30000, max: 300000)
  • retries: Number of retry attempts (default: 3, max: 5)
  • rateLimit: Max requests per minute (default: 100)
  • maxConcurrent: Max concurrent executions (default: 10)

Example:

{
  "config": {
    "timeout": 60000,
    "retries": 5,
    "rateLimit": 50,
    "maxConcurrent": 5
  }
}

Complete Examples

Example 1: Email Marketing Agent

curl -X POST https://api.mindra.co/v1/agents \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "email-campaign-ai-pro",
    "name": "Email Campaign AI Pro",
    "description": "AI-powered email marketing campaign creator with advanced personalization, A/B testing, and multi-language support. Optimized for B2B SaaS companies.",
    "url": "https://agents.acme.com/email-ai",
    "vertical": "marketing",
    "capabilities": [
      "email_generation",
      "subject_line_optimization",
      "a_b_testing",
      "audience_segmentation",
      "personalization",
      "multi_language"
    ],
    "pricing": {
      "model": "per_execution",
      "basePrice": 0.75,
      "additionalCosts": {
        "per_email": 0.01,
        "per_language": 0.10,
        "per_variant": 0.05
      }
    },
    "config": {
      "timeout": 45000,
      "retries": 3,
      "rateLimit": 100,
      "maxConcurrent": 10
    }
  }'

Example 2: Payment Processor Agent

curl -X POST https://api.mindra.co/v1/agents \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "crypto-payment-processor",
    "name": "Crypto Payment Processor",
    "description": "Instant cross-border crypto payments with XRP on XRP Ledger. Automatic compliance checks, KYC verification, and real-time settlement.",
    "url": "https://pay.cryptoagent.io",
    "vertical": "cross-border",
    "capabilities": [
      "crypto_payments",
      "multi_currency_conversion",
      "kyc_verification",
      "compliance_check",
      "real_time_settlement",
      "transaction_tracking"
    ],
    "pricing": {
      "model": "per_transaction",
      "basePrice": 0.50,
      "percentageFee": 0.3,
      "additionalCosts": {
        "kyc_check": 0.25,
        "compliance_report": 0.15
      }
    },
    "config": {
      "timeout": 90000,
      "retries": 5,
      "rateLimit": 200,
      "maxConcurrent": 50
    }
  }'

Example 3: ML Model Agent

curl -X POST https://api.mindra.co/v1/agents \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "demand-forecasting-ml",
    "name": "Demand Forecasting ML",
    "description": "Machine learning model for inventory demand forecasting. Trained on 5 years of historical data with 95% accuracy. Supports seasonal adjustments and external factors.",
    "url": "https://ml.supplychain.io/forecast",
    "vertical": "supply-chain",
    "capabilities": [
      "demand_forecasting",
      "time_series_analysis",
      "seasonal_adjustment",
      "anomaly_detection",
      "confidence_intervals"
    ],
    "pricing": {
      "model": "per_execution",
      "basePrice": 0.25,
      "additionalCosts": {
        "per_sku": 0.001,
        "per_week_forecast": 0.05
      }
    },
    "config": {
      "timeout": 30000,
      "retries": 2,
      "rateLimit": 500,
      "maxConcurrent": 20
    }
  }'

Verification

After registration, Mindra Platform verifies your agent:

1. Health Check

Platform calls GET /health to verify accessibility:

GET https://my-agent.example.com/health

Expected response:

{
  "status": "healthy",
  "timestamp": 1699632000
}

2. Info Validation

Platform calls GET /info to validate metadata:

GET https://my-agent.example.com/info

Expected response must match registration:

{
  "id": "my-custom-agent",
  "name": "My Custom Agent",
  "description": "...",
  "version": "1.0.0",
  "capabilities": ["..."],
  "pricing": {...}
}

3. Test Execution

Platform performs a test execution:

POST https://my-agent.example.com/execute
Content-Type: application/json

{
  "input": {
    "prompt": "__MINDRA_TEST__",
    "context": {}
  },
  "metadata": {
    "requestId": "test_123",
    "userId": "system",
    "timeout": 30000
  }
}

Expected response format:

{
  "result": {...},
  "metadata": {
    "cost": 0.00,
    "duration": 100,
    "model": "test"
  }
}

Verification Results

If verification succeeds:

{
  "verified": true,
  "message": "Agent verified successfully",
  "checks": {
    "health": "pass",
    "info": "pass",
    "execute": "pass"
  }
}

If verification fails:

{
  "verified": false,
  "message": "Agent verification failed",
  "checks": {
    "health": "pass",
    "info": "fail - metadata mismatch",
    "execute": "pass"
  },
  "errors": [
    "Info endpoint returned different ID than registered"
  ]
}

Managing Your Agent

Update Agent

curl -X PATCH https://api.mindra.co/v1/agents/my-custom-agent \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "pricing": {
      "model": "per_execution",
      "basePrice": 0.60
    }
  }'

Deactivate Agent

curl -X PATCH https://api.mindra.co/v1/agents/my-custom-agent \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "isActive": false
  }'

Delete Agent

curl -X DELETE https://api.mindra.co/v1/agents/my-custom-agent \
  -H "Authorization: Bearer mk_your_api_key"

Warning: Deletion is permanent. Active executions will fail.

View Agent Metrics

curl https://api.mindra.co/v1/agents/my-custom-agent/metrics \
  -H "Authorization: Bearer mk_your_api_key"

Response:

{
  "agentId": "my-custom-agent",
  "metrics": {
    "totalExecutions": 1247,
    "successfulRuns": 1198,
    "failedRuns": 49,
    "avgDuration": 4523,
    "totalCost": 623.50,
    "last24h": {
      "executions": 87,
      "successRate": 0.97
    },
    "last7d": {
      "executions": 621,
      "successRate": 0.96
    }
  }
}

Best Practices

1. Choose Descriptive IDs

# ✅ Good - Clear and descriptive
"id": "email-campaign-ai-pro"
"id": "crypto-payment-usdc"
"id": "ml-demand-forecasting"

# ❌ Bad - Generic or unclear
"id": "agent1"
"id": "my-agent"
"id": "test"

2. Write Detailed Descriptions

# ✅ Good - Detailed, specific
"description": "AI-powered email campaign creator specializing in B2B SaaS.
Creates personalized content, optimizes subject lines, and generates A/B test
variants. Supports 15 languages and integrates with major email platforms."

# ❌ Bad - Too vague
"description": "Creates emails"

3. Use Appropriate Pricing

# ✅ Good - Transparent, itemized
{
  "pricing": {
    "model": "per_execution",
    "basePrice": 0.50,
    "additionalCosts": {
      "per_email": 0.01,
      "per_language": 0.10
    }
  }
}

# ❌ Bad - Hidden costs
{
  "pricing": {
    "model": "per_execution",
    "basePrice": 0.01  // Too low, likely hidden costs
  }
}

4. Set Realistic Timeouts

# ✅ Good - Based on actual performance
{
  "config": {
    "timeout": 45000  // Agent typically takes 30-40s
  }
}

# ❌ Bad - Unrealistic
{
  "config": {
    "timeout": 300000  // 5 minutes for a simple task
  }
}

Troubleshooting

Agent Not Showing Up

Problem: Agent registered but not appearing in agent list

Solutions:

  1. Check if isActive: true
  2. Verify agent passed all verification checks
  3. Ensure agent is publicly accessible via HTTPS
  4. Check health endpoint is responding

Verification Failed

Problem: Agent verification fails

Solutions:

  1. Verify all endpoints (/health, /info, /execute) are working
  2. Ensure /info returns data matching registration
  3. Check agent responds to test execution with __MINDRA_TEST__
  4. Verify SSL certificate is valid

Agent Not Being Selected

Problem: Agent registered but never selected in orchestrations

Solutions:

  1. Check capabilities match common use cases
  2. Ensure vertical is appropriate
  3. Verify pricing is competitive
  4. Check agent performance metrics (slow agents get deprioritized)
  5. Improve agent description for better matching

Support

Next: Enterprise Integration →

Found an issue? Report it on GitHub →