Agent Registration Guide

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

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 transfers 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, transfer_routing, kyc_verification

Supply-Chain:

demand_forecasting, inventory_optimization, shipment_tracking, route_optimization

`pricing` (required)

Pricing model for your agent.

Models:

Per Execution (most common):

{
  "pricing": {
    "model": "per_execution",
    "basePrice": 0.50,
    "additionalCosts": {
      "per_email": 0.01,
      "per_variant": 0.05
    }
  }
}

Per Transaction:

{
  "pricing": {
    "model": "per_transaction",
    "basePrice": 0.20,
    "percentageFee": 0.5
  }
}

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: 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": "supply-chain-optimizer"
"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:

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

Verification Failed

Problem: Agent verification fails

Solutions:

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

Agent Not Being Selected

Problem: Agent registered but never selected in orchestrations

Solutions:

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

Support

Registration Issues: info@mindra.co
Technical Help: info@mindra.co

Next: Enterprise Integration →

Agent Registration Guide

Overview

Prerequisites

Registration API

POST /v1/agents

Parameters

id (required)

name (required)

description (required)

url (required)

vertical (required)

capabilities (required)

pricing (required)

config (optional)

Complete Examples

Example 1: Email Marketing Agent

Example 2: ML Model Agent

Verification

1. Health Check

2. Info Validation

3. Test Execution

Verification Results

Managing Your Agent

Update Agent

Deactivate Agent

Delete Agent

View Agent Metrics

Best Practices

1. Choose Descriptive IDs

2. Write Detailed Descriptions

3. Use Appropriate Pricing

4. Set Realistic Timeouts

Troubleshooting

Agent Not Showing Up

Verification Failed

Agent Not Being Selected

Support

`id` (required)

`name` (required)

`description` (required)

`url` (required)

`vertical` (required)

`capabilities` (required)

`pricing` (required)

`config` (optional)