Agents

Register and manage AI agents with the Python SDK

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

Field	Type	Required	Description
name	str	Yes	Agent display name
description	str	No	Agent description
author	str	No	Author/company name
tags	list[str]	No	Categorization tags
license	str	No	License information
sample_link	str	No	Link to demo/sample
api_description	str	No	API documentation

AgentAPIAttributes Fields

Field	Type	Required	Description
endpoints	list[dict]	Yes	List of endpoint configurations
agent_definition_url	str	Yes	URL to OpenAPI/MCP/A2A spec
open_endpoints	list[str]	No	Endpoints without auth
auth_type	AuthType	No	Authentication 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