Managing AI Agents

Complete guide to registering and managing AI agents with the Nevermined CLI

Managing AI Agents

Complete guide to registering and managing AI agents with the Nevermined CLI.

Overview

AI agents are services that users can access by purchasing payment plans. Agents can be:

• AI assistants: Chat-based conversational agents
• API services: REST APIs with metered access
• Data pipelines: Processing services with usage tracking
• Tools: Utility services with pay-per-use billing

Listing Agent Plans

Get the list of plans that can be ordered to access an agent:

nvm agents get-agent-plans <agent-id>

# With pagination
nvm agents get-agent-plans <agent-id> --pagination '{"page": 1, "offset": 10}'

# JSON output
nvm agents get-agent-plans <agent-id> --format json

Getting Agent Details

Retrieve detailed information about a specific agent:

nvm agents get-agent <agent-id>

Example:

nvm agents get-agent "did:nvm:abc123"

Output includes:

• Agent metadata (name, description, creator)
• API endpoint configuration
• Associated payment plans

Registering Agents

Register Agent with Existing Plans

Register a new AI agent and associate it with one or more existing payment plans:

nvm agents register-agent \
  --agent-metadata agent-metadata.json \
  --agent-api "https://api.example.com/v1/agent" \
  --payment-plans "plan-id-1,plan-id-2"

agent-metadata.json:

{
  "name": "My AI Assistant",
  "description": "GPT-4 powered conversational AI with specialized knowledge",
  "version": "1.0.0",
  "author": "Your Name",
  "tags": ["ai", "assistant", "gpt4"],
  "customData": {
    "capabilities": ["chat", "code-generation", "analysis"],
    "model": "gpt-4",
    "language": "en"
  }
}

Register Agent and Plan Together

Register a new AI agent and create a payment plan for it in a single command:

nvm agents register-agent-and-plan \
  --agent-metadata agent-metadata.json \
  --agent-api "https://api.example.com/v1/agent" \
  --plan-metadata plan-metadata.json \
  --price-config price-config.json \
  --credits-config credits-config.json

Optional flags:

• --access-limit — Limit the number of times the plan can be ordered

plan-metadata.json:

{
  "name": "My Agent - Basic Plan",
  "description": "100 credits for API access",
  "tags": ["ai", "assistant", "basic"]
}

price-config.json:

{
  "tokenAddress": "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d",
  "price": 1000000,
  "amountOfCredits": 100
}

credits-config.json:

{
  "subscriptionType": "credits",
  "accessType": "credits",
  "minCreditsToCharge": 1,
  "maxCreditsToCharge": 10
}

Updating Agents

Update Agent Metadata

Modify agent name, description, API endpoint, or other metadata:

nvm agents update-agent-metadata <agent-id> \
  --agent-metadata updated-metadata.json \
  --agent-api "https://api-v2.example.com/agent"

Both --agent-metadata and --agent-api are required.

updated-metadata.json:

{
  "name": "My AI Assistant Pro",
  "description": "Enhanced GPT-4 assistant with advanced capabilities",
  "version": "2.0.0",
  "tags": ["ai", "assistant", "gpt4", "premium"]
}

Managing Payment Plans

Add Payment Plan to Agent

Associate an existing payment plan with an agent:

nvm agents add-plan-to-agent <plan-id> --agent-id <agent-id>

Example:

nvm agents add-plan-to-agent "did:nvm:plan123" --agent-id "did:nvm:agent456"

Remove Payment Plan from Agent

Disassociate a payment plan from an agent:

nvm agents remove-plan-from-agent <plan-id> --agent-id <agent-id>

Example:

nvm agents remove-plan-from-agent "did:nvm:plan123" --agent-id "did:nvm:agent456"

List Plans Associated with Agent

See which plans give access to an agent:

nvm agents get-agent-plans <agent-id>

Integration Examples

Example 1: Full Agent Setup

Complete workflow to register and configure an AI agent:

#!/bin/bash
# Complete agent setup script

# 1. Create a payment plan first
PLAN_ID=$(nvm plans register-credits-plan \
  --plan-metadata plan.json \
  --price-config price.json \
  --credits-config credits.json \
  --format json | jq -r '.planId')

echo "Created plan: $PLAN_ID"

# 2. Register the agent with the plan
AGENT_ID=$(nvm agents register-agent \
  --agent-metadata agent.json \
  --agent-api "https://api.example.com/agent" \
  --payment-plans "$PLAN_ID" \
  --format json | jq -r '.agentId')

echo "Registered agent: $AGENT_ID"

# 3. Update agent metadata if needed
nvm agents update-agent-metadata $AGENT_ID \
  --agent-metadata updated-agent.json \
  --agent-api "https://api.example.com/agent"

# 4. Verify agent is accessible
nvm agents get-agent $AGENT_ID

echo "Agent setup complete!"

Example 2: One-Step Agent and Plan Registration

Register an agent and its payment plan in a single command:

nvm agents register-agent-and-plan \
  --agent-metadata agent.json \
  --agent-api "https://api.example.com/agent" \
  --plan-metadata plan.json \
  --price-config price.json \
  --credits-config credits.json

Example 3: Multi-Plan Agent

Register an agent with multiple pricing tiers:

# Create basic plan
BASIC_PLAN=$(nvm plans register-credits-plan \
  --plan-metadata basic-plan.json \
  --price-config basic-price.json \
  --credits-config basic-credits.json \
  --format json | jq -r '.planId')

# Create premium plan
PREMIUM_PLAN=$(nvm plans register-credits-plan \
  --plan-metadata premium-plan.json \
  --price-config premium-price.json \
  --credits-config premium-credits.json \
  --format json | jq -r '.planId')

# Register agent with both plans
nvm agents register-agent \
  --agent-metadata agent.json \
  --agent-api "https://api.example.com" \
  --payment-plans "$BASIC_PLAN,$PREMIUM_PLAN"

JSON Output for Automation

Use --format json to integrate with other tools:

# Get agent data
AGENT=$(nvm agents get-agent "did:nvm:agent123" --format json)

# Extract fields
NAME=$(echo $AGENT | jq -r '.name')
echo "Agent: $NAME"

Best Practices

1. Use Descriptive Metadata

Provide comprehensive information about your agent:

{
  "name": "GPT-4 Code Assistant",
  "description": "AI-powered code generation and debugging assistant",
  "version": "1.2.0",
  "author": "YourCompany",
  "tags": ["code", "ai", "programming", "debugging"]
}

2. Implement Proper API Endpoints

Ensure your agent API follows best practices:

• Use HTTPS for all endpoints
• Implement rate limiting
• Return proper HTTP status codes
• Include error handling

3. Test Before Production

Always test agents in sandbox environment:

# Register in sandbox
nvm --profile sandbox agents register-agent \
  --agent-metadata agent.json \
  --agent-api "https://staging-api.example.com" \
  --payment-plans "$STAGING_PLAN_ID"

# Test the agent
nvm --profile sandbox agents get-agent $STAGING_AGENT_ID

# Once verified, deploy to production
nvm --profile production agents register-agent \
  --agent-metadata agent.json \
  --agent-api "https://api.example.com" \
  --payment-plans "$PROD_PLAN_ID"

Common Issues

”Payment plan not found”

Verify the payment plan exists and you’re using the correct plan ID:

# List all your plans
nvm plans get-plans

# Verify specific plan
nvm plans get-plan <plan-id>

“Insufficient permissions”

Ensure you’re the agent owner or have proper permissions:

# Check agent details
nvm agents get-agent <agent-id>

# Verify you're using the correct profile
nvm config show

Next Steps

• Purchases - Users ordering your agent plans
• Querying - Accessing agents with X402 tokens
• Plans - Creating payment plans for your agents