Agents

The Agents API allows AI builders to register their AI agents with the Nevermined protocol, making them discoverable and accessible through payment plans.

Overview of Agents API

The Agents API (payments.agents) enables you to:

Register AI agents with metadata and API endpoints
Associate agents with one or more payment plans
Register agents and plans together in a single operation
Update agent metadata and configuration
Retrieve agent information
Manage plan associations (add/remove plans from agents)

Agent Metadata Structure

Agents require metadata for discovery and identification:

import { AgentMetadata } from '@nevermined-io/payments'

const agentMetadata: AgentMetadata = {
  name: 'Weather AI Agent',
  description: 'Provides real-time weather forecasts and climate data',
  tags: ['weather', 'forecast', 'climate'],
  dateCreated: new Date(),
  author: 'Your Company Name',
  // Additional metadata fields...
}

Agent API Configuration

AgentAPIAttributes describes how requests to your agent are authenticated and (optionally) which routes are gated by your Payment Plan. All fields are optional.

Minimal (recommended)

Most builders only need to configure how the agent is authenticated. If you integrate with the Payments library and gate paid routes via library annotations or middleware, you do not need to declare endpoints or an OpenAPI URL at registration time.

import { AgentAPIAttributes } from '@nevermined-io/payments'

const agentApi: AgentAPIAttributes = {
  authType: 'bearer',
  token: process.env.AGENT_BEARER_TOKEN,
}

With Additional Security (opt-in)

If you want the Nevermined platform to enforce a route-level allowlist (defense-in-depth on top of your library-level gating), provide endpoints. You can also provide agentDefinitionUrl to publish a discoverable OpenAPI / MCP / A2A descriptor.

const agentApi: AgentAPIAttributes = {
  authType: 'bearer',
  token: process.env.AGENT_BEARER_TOKEN,

  // Additional Security: only requests matching this allowlist are accepted by
  // the Nevermined platform's x402 verification service. Omitted = allow-all (default).
  endpoints: [
    { POST: 'https://api.example.com/v1/agents/:agentId/tasks' },
    { GET: 'https://api.example.com/v1/agents/:agentId/tasks/:taskId' },
  ],
  openEndpoints: ['https://api.example.com/v1/health'],

  // Optional: discoverable agent definition (OpenAPI / MCP Manifest / A2A card).
  agentDefinitionUrl: 'https://api.example.com/openapi.json',
}

Migration note: agents registered before endpoint and agent definition fields became optional may still have these fields populated and will continue to enforce the allowlist as before. Nothing changes for them. Use the Edit Agent screen on app.nevermined.app to add or remove the configuration.

Endpoint Patterns (Additional Security)

When you opt in to the allowlist, you can use path parameters in your endpoint definitions:

const agentApi: AgentAPIAttributes = {
  endpoints: [
    { POST: 'https://api.example.com/agents/:agentId/query' },
    { GET: 'https://api.example.com/agents/:agentId/status' },
    { POST: 'https://api.example.com/agents/:agentId/tasks/:taskId/cancel' },
  ],
}

Register Agents

Register Agent with Existing Plans

If you’ve already registered payment plans, you can register an agent and associate it with those plans:

import { Payments, AgentMetadata, AgentAPIAttributes } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox',
})

// Define agent metadata
const agentMetadata: AgentMetadata = {
  name: 'Weather Forecast Agent',
  description: 'Get accurate weather forecasts for any location',
  tags: ['weather', 'forecast', 'api'],
}

// Configure API authentication. endpoints + agentDefinitionUrl are
// optional — see "Additional Security (opt-in)" above.
const agentApi: AgentAPIAttributes = {
  authType: 'bearer',
  token: process.env.AGENT_BEARER_TOKEN,
}

// Register agent with existing plans
const { agentId } = await payments.agents.registerAgent(
  agentMetadata,
  agentApi,
  [planId1, planId2]  // Array of plan IDs
)

console.log(`Agent registered with ID: ${agentId}`)

Register Agent and Plan Together

For convenience, you can register both an agent and its payment plan in a single operation:

import { Payments, AgentMetadata, AgentAPIAttributes, PlanMetadata } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox',
})

const builderAddress = payments.getAccountAddress()
const ERC20_ADDRESS = '0x036CbD53842c5426634e7929541eC2318f3dCF7e'

// Define plan
const planMetadata: PlanMetadata = {
  name: 'Weather Agent Access Plan',
  description: 'Get 1000 credits to access weather data',
}

const priceConfig = payments.plans.getCryptoPriceConfig(
  10_000_000n,
  builderAddress,
  ERC20_ADDRESS
)

const creditsConfig = payments.plans.getFixedCreditsConfig(1000n, 1n)

// Define agent
const agentMetadata: AgentMetadata = {
  name: 'Weather Forecast Agent',
  description: 'Real-time weather forecasts powered by AI',
  tags: ['weather', 'ai', 'forecast'],
}

const agentApi: AgentAPIAttributes = {
  authType: 'bearer',
  token: process.env.AGENT_BEARER_TOKEN,
  // Optional: opt in to platform-enforced route allowlist. See
  // "Additional Security (opt-in)" above.
  // endpoints: [
  //   { POST: 'https://weather-api.example.com/v1/agents/:agentId/tasks' },
  // ],
}

// Register both together
const { agentId, planId } = await payments.agents.registerAgentAndPlan(
  agentMetadata,
  agentApi,
  planMetadata,
  priceConfig,
  creditsConfig
)

console.log(`Agent ID: ${agentId}`)
console.log(`Plan ID: ${planId}`)

Retrieve Agents

List Your Agents

List the agents you published — the authenticated caller’s own agents. This is account management, not a marketplace search: it never returns other users’ agents. Pass an orgId to list every agent in an organization you belong to.

// Your own agents (paginated: { total, page, offset, agents })
const { agents } = await payments.agents.getAgents()

agents.forEach((agent) => {
  console.log(`${agent.name}: ${agent.agentId}`)
})

// Every agent in an organization you belong to
const { agents: orgAgents } = await payments.agents.getAgents(1, 100, 'created', 'desc', 'org-acme')

Get a Specific Agent

// Get agent details by ID
const agent = await payments.agents.getAgent(agentId)

console.log(`Name: ${agent.name}`)
console.log(`Description: ${agent.description}`)
console.log(`Endpoints: ${JSON.stringify(agent.endpoints)}`)

Get Plans for an Agent

// Get all payment plans associated with an agent
const plans = await payments.agents.getAgentPlans(agentId)

plans.forEach(plan => {
  console.log(`Plan: ${plan.name} (${plan.planId})`)
})

Update Agent Metadata

You can update agent metadata and API configuration after registration. This is also where builders typically opt in to Additional Security by adding an endpoints allowlist or an agentDefinitionUrl to an existing agent:

// Update agent information and opt in to the route-level allowlist.
await payments.agents.updateAgentMetadata(
  agentId,
  {
    description: 'Updated description with new features',
    tags: ['weather', 'forecast', 'climate', 'ai-powered'],
  },
  {
    // Adding `endpoints` activates the platform-enforced allowlist.
    // Do not use `endpoints: []` to mean "allow all": a configured-but-empty
    // allowlist is treated as deny-all unless `openEndpoints` matches,
    // preserving legacy semantics. Only include `endpoints` when you want
    // the allowlist to be enforced.
    endpoints: [
      { POST: 'https://weather-api.example.com/v2/agents/:agentId/forecast' },
      { GET: 'https://weather-api.example.com/v2/agents/:agentId/history' },
      { GET: 'https://weather-api.example.com/v2/agents/:agentId/alerts' },
    ],
    agentDefinitionUrl: 'https://weather-api.example.com/openapi.json',
  }
)

console.log('Agent updated successfully')

Manage Agent Plans

Add Plans to an Agent

Associate additional payment plans with an existing agent:

// Add new plans to an agent
await payments.agents.addPlanToAgent(newPlanId, agentId)

console.log(`Added plan ${newPlanId} to agent ${agentId}`)

Remove Plans from an Agent

Remove payment plan associations:

// Remove a plan from an agent
await payments.agents.removePlanFromAgent(planIdToRemove, agentId)

console.log(`Removed plan ${planIdToRemove} from agent ${agentId}`)

Authentication Types

The Agents API supports multiple authentication types:

// No authentication required
const agentApi = {
  endpoints: [{ GET: 'https://api.example.com/public' }],
  authType: 'none',
}

// Basic authentication
const agentApi = {
  endpoints: [{ POST: 'https://api.example.com/agent' }],
  authType: 'basic',
}

// Bearer token (most common for AI agents)
const agentApi = {
  endpoints: [{ POST: 'https://api.example.com/agent' }],
  authType: 'bearer',  // X402 access token in Authorization header
}

// OAuth
const agentApi = {
  endpoints: [{ POST: 'https://api.example.com/agent' }],
  authType: 'oauth',
}

Complete Example: Multi-Endpoint Agent

import { Payments, EnvironmentName } from '@nevermined-io/payments'
import { AgentMetadata, AgentAPIAttributes } from '@nevermined-io/payments'

const payments = Payments.getInstance({
  nvmApiKey: process.env.NVM_API_KEY!,
  environment: 'sandbox' as EnvironmentName,
})

// Comprehensive agent configuration
const agentMetadata: AgentMetadata = {
  name: 'Advanced Weather AI',
  description: 'Multi-modal weather analysis with forecasts, alerts, and historical data',
  tags: ['weather', 'forecast', 'climate', 'alerts', 'ai'],
  author: 'Weather Tech Inc.',
  dateCreated: new Date(),
}

const agentApi: AgentAPIAttributes = {
  endpoints: [
    { POST: 'https://api.weather-tech.com/v1/agents/:agentId/forecast' },
    { GET: 'https://api.weather-tech.com/v1/agents/:agentId/forecast/:forecastId' },
    { POST: 'https://api.weather-tech.com/v1/agents/:agentId/alerts' },
    { GET: 'https://api.weather-tech.com/v1/agents/:agentId/history' },
    { DELETE: 'https://api.weather-tech.com/v1/agents/:agentId/alerts/:alertId' },
  ],
  openEndpoints: [
    'https://api.weather-tech.com/v1/health',
    'https://api.weather-tech.com/v1/status',
  ],
  authType: 'bearer',
  agentDefinitionUrl: 'https://api.weather-tech.com/openapi.json',
}

// Register with multiple plans
const { agentId } = await payments.agents.registerAgent(
  agentMetadata,
  agentApi,
  [basicPlanId, proPlanId, enterprisePlanId]
)

console.log(`Advanced agent registered: ${agentId}`)

// Retrieve and verify
const agent = await payments.agents.getAgent(agentId)
const { plans, total, page, offset } = await payments.agents.getAgentPlans(agentId)

console.log(`Agent has ${plans.length} plans on page ${page} (offset ${offset}, total ${total})`)

Best Practices

Descriptive Metadata: Use clear names and descriptions for better discoverability
Relevant Tags: Add tags that help users find your agent
RESTful Endpoints: Follow REST conventions for endpoint paths
OpenAPI Specs: Provide agent definition URLs for better integration
Multiple Plans: Offer different pricing tiers for various use cases
Bearer Auth: Use bearer token authentication for secure access

Payment Plans - Create plans to associate with agents
Publishing Static Resources - Register static content agents
Validation of Requests - Validate incoming agent requests

Source References:

src/api/agents-api.ts (Agents API methods)
tests/e2e/test_payments_e2e.test.ts (lines 373-449)
tests/e2e/test_x402_e2e.test.ts (agent registration examples)

TypeScript SDK

Python SDK

CLI

OpenClaw Plugin

Agents

Agents

Overview of Agents API

Agent Metadata Structure

Agent API Configuration

Minimal (recommended)

With Additional Security (opt-in)

Endpoint Patterns (Additional Security)

Register Agents

Register Agent with Existing Plans

Register Agent and Plan Together

Retrieve Agents

List Your Agents

Get a Specific Agent

Get Plans for an Agent

Update Agent Metadata

Manage Agent Plans

Add Plans to an Agent

Remove Plans from an Agent

Authentication Types

Complete Example: Multi-Endpoint Agent

Best Practices

​Agents

​Overview of Agents API

​Agent Metadata Structure

​Agent API Configuration

​Minimal (recommended)

​With Additional Security (opt-in)

​Endpoint Patterns (Additional Security)

​Register Agents

​Register Agent with Existing Plans

​Register Agent and Plan Together

​Retrieve Agents

​List Your Agents

​Get a Specific Agent

​Get Plans for an Agent

​Update Agent Metadata

​Manage Agent Plans

​Add Plans to an Agent

​Remove Plans from an Agent

​Authentication Types

​Complete Example: Multi-Endpoint Agent

​Best Practices

​Related Documentation

Agents

Overview of Agents API

Agent Metadata Structure

Agent API Configuration

Minimal (recommended)

With Additional Security (opt-in)

Endpoint Patterns (Additional Security)

Register Agents

Register Agent with Existing Plans

Register Agent and Plan Together

Retrieve Agents

List Your Agents

Get a Specific Agent

Get Plans for an Agent

Update Agent Metadata

Manage Agent Plans

Add Plans to an Agent

Remove Plans from an Agent

Authentication Types

Complete Example: Multi-Endpoint Agent

Best Practices

Related Documentation