Skip to main content
This guide covers how to register and manage AI agents using the Nevermined Payments Python SDK.

​
Overview

AI Agents are services that users can access through payment plans. The Agents API allows you to:
  • Register new agents with associated payment plans
  • Register agents and plans together in a single operation
  • Update agent metadata and endpoints
  • Manage plan associations

​
Agents API

Access the Agents API through payments.agents: 
from payments_py import Payments, PaymentOptions

payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:your-key", environment="sandbox")
)

# Access agents API
agents_api = payments.agents

​
Register Agents

​
Basic Agent Registration

Register an agent and associate it with existing payment plans: 
from payments_py.common.types import AgentMetadata, AgentAPIAttributes

# Define agent metadata
agent_metadata = AgentMetadata(
    name="My AI Assistant",
    description="An intelligent assistant that helps with various tasks",
    tags=["ai", "assistant", "productivity"],
    author="Your Company"
)

# Define API configuration
agent_api = AgentAPIAttributes(
    endpoints=[
        {"POST": "https://your-api.com/api/v1/agents/:agentId/tasks"},
        {"GET": "https://your-api.com/api/v1/agents/:agentId/tasks/:taskId"}
    ],
    agent_definition_url="https://your-api.com/api/v1/openapi.json"
)

# List of plan IDs that grant access to this agent
payment_plans = [plan_id_1, plan_id_2]

# Register the agent
result = payments.agents.register_agent(
    agent_metadata=agent_metadata,
    agent_api=agent_api,
    payment_plans=payment_plans
)
print(f"Agent ID: {result['agentId']}")

​
Register Agent and Plan Together

Create both an agent and a payment plan in a single operation: 
from payments_py.common.types import AgentMetadata, AgentAPIAttributes, PlanMetadata
from payments_py.plans import get_erc20_price_config, get_fixed_credits_config

# Agent configuration
agent_metadata = AgentMetadata(
    name="AI Code Reviewer",
    description="Automated code review assistant",
    tags=["code", "review", "ai"]
)

agent_api = AgentAPIAttributes(
    endpoints=[{"POST": "https://your-api.com/api/v1/review"}],
    agent_definition_url="https://your-api.com/openapi.json"
)

# Plan configuration
plan_metadata = PlanMetadata(
    name="Code Review Plan",
    description="100 code reviews"
)

price_config = get_erc20_price_config(
    amount=50,
    token_address="0xYourTokenAddress",
    receiver=payments.account_address
)

credits_config = get_fixed_credits_config(credits_granted=100)

# Register both in one call
result = payments.agents.register_agent_and_plan(
    agent_metadata=agent_metadata,
    agent_api=agent_api,
    plan_metadata=plan_metadata,
    price_config=price_config,
    credits_config=credits_config,
    access_limit="credits"  # or "time"
)

print(f"Agent ID: {result['agentId']}")
print(f"Plan ID: {result['planId']}")
print(f"Transaction: {result['txHash']}")

​
Agent Configuration

​
AgentMetadata Fields

FieldTypeRequiredDescription
namestrYesAgent display name
descriptionstrNoAgent description
authorstrNoAuthor/company name
tagslist[str]NoCategorization tags
licensestrNoLicense information
sample_linkstrNoLink to demo/sample
api_descriptionstrNoAPI documentation

​
AgentAPIAttributes Fields

FieldTypeRequiredDescription
endpointslist[dict]YesList of endpoint configurations
agent_definition_urlstrYesURL to OpenAPI/MCP/A2A spec
open_endpointslist[str]NoEndpoints without auth
auth_typeAuthTypeNoAuthentication type

​
Endpoint Configuration

Endpoints are defined as dictionaries with HTTP verb as key and URL as value: 
agent_api = AgentAPIAttributes(
    endpoints=[
        {"POST": "https://api.example.com/agents/:agentId/tasks"},
        {"GET": "https://api.example.com/agents/:agentId/tasks/:taskId"},
        {"DELETE": "https://api.example.com/agents/:agentId/tasks/:taskId"}
    ],
    agent_definition_url="https://api.example.com/openapi.json"
)
The :agentId and :taskId placeholders will be replaced with actual values during request validation.

​
Retrieve Agents

​
Get a Single Agent

agent = payments.agents.get_agent(agent_id="your-agent-id")
print(f"Agent name: {agent['name']}")
print(f"Agent endpoints: {agent['endpoints']}")

​
Get Plans for an Agent

from payments_py.common.types import PaginationOptions

plans = payments.agents.get_agent_plans(
    agent_id="your-agent-id",
    pagination=PaginationOptions(page=1, offset=10)
)
print(f"Associated plans: {plans}")

​
Update Agents

​
Update Agent Metadata

updated_metadata = AgentMetadata(
    name="Updated Agent Name",
    description="Updated description with new features",
    tags=["ai", "updated", "v2"]
)

updated_api = AgentAPIAttributes(
    endpoints=[{"POST": "https://new-api.com/v2/tasks"}],
    agent_definition_url="https://new-api.com/v2/openapi.json"
)

result = payments.agents.update_agent_metadata(
    agent_id="your-agent-id",
    agent_metadata=updated_metadata,
    agent_api=updated_api
)
print(f"Update successful: {result}")

​
Manage Plan Associations

​
Add a Plan to an Agent

result = payments.agents.add_plan_to_agent(
    plan_id="plan-to-add",
    agent_id="your-agent-id"
)
print(f"Plan added: {result}")

​
Remove a Plan from an Agent

result = payments.agents.remove_plan_from_agent(
    plan_id="plan-to-remove",
    agent_id="your-agent-id"
)
print(f"Plan removed: {result}")

​
Complete Example

from payments_py import Payments, PaymentOptions
from payments_py.common.types import AgentMetadata, AgentAPIAttributes, PlanMetadata
from payments_py.plans import (
    get_erc20_price_config,
    get_fixed_credits_config,
    get_free_price_config
)

# Initialize
payments = Payments.get_instance(
    PaymentOptions(nvm_api_key="nvm:your-key", environment="sandbox")
)

ERC20_TOKEN = "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
builder_address = payments.account_address

# 1. Create a payment plan first
plan_result = payments.plans.register_credits_plan(
    plan_metadata=PlanMetadata(name="AI Agent Plan"),
    price_config=get_erc20_price_config(20, ERC20_TOKEN, builder_address),
    credits_config=get_fixed_credits_config(100)
)
plan_id = plan_result['planId']

# 2. Register an agent with the plan
agent_result = payments.agents.register_agent(
    agent_metadata=AgentMetadata(
        name="My First AI Agent",
        description="A demo AI agent",
        tags=["demo", "ai"]
    ),
    agent_api=AgentAPIAttributes(
        endpoints=[{"POST": "https://api.example.com/agents/:agentId/tasks"}],
        agent_definition_url="https://api.example.com/openapi.json"
    ),
    payment_plans=[plan_id]
)
agent_id = agent_result['agentId']
print(f"Created agent: {agent_id}")

# 3. Or create both together
combo_result = payments.agents.register_agent_and_plan(
    agent_metadata=AgentMetadata(name="Combo Agent"),
    agent_api=AgentAPIAttributes(
        endpoints=[{"POST": "https://api.example.com/combo"}],
        agent_definition_url="https://api.example.com/openapi.json"
    ),
    plan_metadata=PlanMetadata(name="Combo Plan"),
    price_config=get_free_price_config(),
    credits_config=get_fixed_credits_config(10)
)
print(f"Combo Agent: {combo_result['agentId']}, Plan: {combo_result['planId']}")

# 4. Retrieve agent details
agent = payments.agents.get_agent(agent_id)
print(f"Agent details: {agent}")

# 5. Get associated plans
plans = payments.agents.get_agent_plans(agent_id)
print(f"Agent plans: {plans}")

# 6. Update agent metadata
payments.agents.update_agent_metadata(
    agent_id=agent_id,
    agent_metadata=AgentMetadata(name="Updated Agent Name"),
    agent_api=AgentAPIAttributes(
        endpoints=[{"POST": "https://api.example.com/v2/agents/:agentId/tasks"}],
        agent_definition_url="https://api.example.com/v2/openapi.json"
    )
)

​
Next Steps

Publishing Static Resources

Publish files and datasets

Querying an Agent

Learn how to access agents