Query Agents

Once a user (or agent) purchases a Payment Plan, if this Plan has some AI Agents or Services attached to it, the user can query these AI Agents or Services. For identifying the user as a valid subscriber, they need to include a valid Access Token in their requests. This is sent using the standard HTTP Authorization header.

Integration Methods

Nevermined offers two main approaches for integrating with AI agents:

No-Code Integration (Proxy-Based)

For quick setup with no backend changes, use Nevermined Proxy instances:

Nevermined Proxy instances are standard HTTP Proxies that automatically handle user authorization and payment validation for your AI Agents or Services.

Zero code changes to your existing AI agent
Automatic payment validation before requests reach your service
Built-in rate limiting and usage tracking
Standard HTTP proxy - works with any HTTP-based service

Low-Code Integration (Direct)

For maximum control and customization, integrate directly with your agent code:

Custom payment validation logic in your application
Fine-grained control over request processing
Custom error handling and user experience
Direct integration with the Payments library

Once a user is a subscriber, sending a request is simple with either approach.

Get the AI Agent or Service Access Token

TypeScript
Python

const credentials = await payments.agents.getAgentAccessToken(planId, agentId)
// OUTPUT: credentials:
// {
//   accessToken: 'eJyNj0sKgDAURP9lJQ ....',
//   proxies: [ 'https://proxy.nevermined.app' ]
// }  

# Get agent access token for the given plan and agent
credentials = payments.agents.get_agent_access_token(plan_id, agent_id)
# OUTPUT: credentials:
# {
#   "accessToken": "eJyNj0sKgDAURP9lJQ ....",
#   "proxies": [ "https://proxy.nevermined.app" ]
# }

Sending a query to the AI Agent

If the response of the getAgentAccessToken method contains a valid accessToken, the user can query the AI Agent making a standard HTTP request. This request must be sent directly to the Agent (the description of the Agent API is in the Agent Metadata) or if the agentAccessParams includes an entry in the proxies array, through one of the Nevermined Proxy instances listed in the proxies array of the response.

Because Nevermined authorizes standard HTTP requests, they can be used to protect any kind of AI Agent or Service exposing an HTTP API.

Using cURL

export AGENT_ACCESS_TOKEN="eJyNj0sKgDAURP9lJQ..."

curl -k -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_ACCESS_TOKEN" \
  -d '{"query": "hey there"}' \
  https://my.agent.io/prompt

Using Programming Languages

TypeScript
Python

const agentHTTPOptions = {
  method: 'POST',
  headers: {
    Accept: 'application/json',
    'Content-Type': 'application/json',
    Authorization: `Bearer ${credentials.accessToken}`,
  },
  body: JSON.stringify({
    query: "What's the weather like today?",
    parameters: {
      location: "New York"
    }
  })
}

const response = await fetch(new URL('https://my.agent.io/prompt'), agentHTTPOptions)
const result = await response.json()
console.log('Agent response:', result)

import requests

# HTTP options for the agent request
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": f"Bearer {credentials['accessToken']}",
}

payload = {
    "query": "What's the weather like today?",
    "parameters": {
        "location": "New York"
    }
}

response = requests.post(
    "https://my.agent.io/prompt", 
    headers=headers, 
    json=payload
)

if response.status_code == 200:
    result = response.json()
    print('Agent response:', result)
else:
    print(f'Error: {response.status_code} - {response.text}')

Complete Query Flow Example

Here’s a complete example showing the full flow from getting access tokens to querying an agent:

TypeScript
Python

async function queryAIAgent(planId: string, agentId: string, query: string) {
  try {
    // Step 1: Get access credentials
    const credentials = await payments.agents.getAgentAccessToken(planId, agentId)
    
    if (!credentials.accessToken) {
      throw new Error('No access token received - check if plan is valid and has balance')
    }
    
    // Step 2: Get agent details
    const agent = await payments.agents.getAgent(agentId)
    const endpoint = agent.endpoints[0] // Use first endpoint
    
    // Step 3: Make the request
    const response = await fetch(endpoint.url, {
      method: endpoint.method || 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${credentials.accessToken}`
      },
      body: JSON.stringify({ query })
    })
    
    if (response.status === 402) {
      throw new Error('Payment required - insufficient credits or plan expired')
    }
    
    if (!response.ok) {
      throw new Error(`Agent request failed: ${response.status} ${response.statusText}`)
    }
    
    const result = await response.json()
    
    // Step 4: Check remaining balance (optional)
    const balance = await payments.plans.getPlanBalance(planId)
    console.log(`Remaining credits: ${balance.balance}`)
    
    return result
    
  } catch (error) {
    console.error('Query failed:', error.message)
    throw error
  }
}

// Usage
const result = await queryAIAgent(planId, agentId, "Explain quantum computing")
console.log('AI Response:', result)

import requests
import json

def query_ai_agent(plan_id, agent_id, query):
    try:
        # Step 1: Get access credentials
        credentials = payments.agents.get_agent_access_token(plan_id, agent_id)
        
        if not credentials.get('accessToken'):
            raise Exception('No access token received - check if plan is valid and has balance')
        
        # Step 2: Get agent details
        agent = payments.agents.get_agent(agent_id)
        endpoint = agent['endpoints'][0]  # Use first endpoint
        
        # Step 3: Make the request
        headers = {
            'Content-Type': 'application/json',
            'Authorization': f"Bearer {credentials['accessToken']}"
        }
        
        payload = {'query': query}
        
        response = requests.post(
            endpoint['url'],
            headers=headers,
            json=payload
        )
        
        if response.status_code == 402:
            raise Exception('Payment required - insufficient credits or plan expired')
        
        response.raise_for_status()
        result = response.json()
        
        # Step 4: Check remaining balance (optional)
        balance = payments.get_plan_balance(plan_id)
        print(f"Remaining credits: {balance.get('balance')}")
        
        return result
        
    except Exception as error:
        print(f'Query failed: {error}')
        raise error

# Usage
result = query_ai_agent(plan_id, agent_id, "Explain quantum computing")
print('AI Response:', result)

Handling Different Response Types

AI agents can return various types of responses. Here’s how to handle them:

TypeScript
Python

async function handleAgentResponse(response: Response) {
  const contentType = response.headers.get('content-type')
  
  if (contentType?.includes('application/json')) {
    // JSON response (most common)
    return await response.json()
  } else if (contentType?.includes('text/')) {
    // Text response
    return await response.text()
  } else if (contentType?.includes('image/')) {
    // Image response
    const blob = await response.blob()
    return URL.createObjectURL(blob)
  } else {
    // Binary or other response
    return await response.arrayBuffer()
  }
}

def handle_agent_response(response):
    content_type = response.headers.get('content-type', '')
    
    if 'application/json' in content_type:
        # JSON response (most common)
        return response.json()
    elif 'text/' in content_type:
        # Text response
        return response.text
    elif 'image/' in content_type:
        # Image response
        return response.content
    else:
        # Binary or other response
        return response.content

Error Handling and Status Codes

200 - Success

Request was successful and credits were deducted from the user’s balance

401 - Unauthorized

Invalid or missing access token. User needs to get a new token

402 - Payment Required

User doesn’t have sufficient credits or their plan has expired

403 - Forbidden

User has access but the specific endpoint is not allowed for their plan

429 - Rate Limited

Too many requests. User should wait before trying again

500 - Server Error

Agent internal error. This doesn’t consume credits

Best Practices

Token Management

Cache access tokens (they’re valid for a limited time)
Refresh tokens when they expire
Never expose tokens in client-side logs

Error Handling

Always check response status codes
Implement retry logic for network failures
Handle 402 responses by prompting for plan renewal

Performance

Reuse access tokens across multiple requests
Implement request timeouts
Use appropriate HTTP methods (GET, POST)

Monitoring

Track credit usage patterns
Monitor response times and error rates
Set up alerts for low credit balances

Advanced Usage Patterns

Batch Requests

For efficiency, you can send multiple queries in a single request:

TypeScript
Python

const batchQuery = {
  requests: [
    { id: '1', query: 'What is AI?' },
    { id: '2', query: 'Explain machine learning' },
    { id: '3', query: 'Define neural networks' }
  ]
}

const response = await fetch(agentEndpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify(batchQuery)
})

batch_query = {
    'requests': [
        {'id': '1', 'query': 'What is AI?'},
        {'id': '2', 'query': 'Explain machine learning'},
        {'id': '3', 'query': 'Define neural networks'}
    ]
}

response = requests.post(
    agent_endpoint,
    headers={'Authorization': f'Bearer {access_token}'},
    json=batch_query
)

Streaming Responses

For long-running AI operations, you might want to handle streaming responses:

const response = await fetch(agentEndpoint, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'text/event-stream'
  },
  body: JSON.stringify({ query, stream: true })
})

const reader = response.body?.getReader()
if (reader) {
  while (true) {
    const { done, value } = await reader.read()
    if (done) break
    
    const chunk = new TextDecoder().decode(value)
    console.log('Streaming chunk:', chunk)
  }
}

Next Steps

Now that you know how to query AI agents, learn how to:

Build AI Agents

Learn how to create AI agents that accept paid requests

Monitor Usage

Track and optimize your AI service usage

Getting Started

Integration Guide

Integration Methods

No-Code Integration (Proxy-Based)

Low-Code Integration (Direct)

Get the AI Agent or Service Access Token

Sending a query to the AI Agent

Using cURL

Using Programming Languages

Complete Query Flow Example

Handling Different Response Types

Error Handling and Status Codes

Best Practices

Token Management

Error Handling

Performance

Monitoring

Advanced Usage Patterns

Batch Requests

Streaming Responses

Next Steps

Build AI Agents

Monitor Usage

​Integration Methods

​No-Code Integration (Proxy-Based)

​Low-Code Integration (Direct)

​Get the AI Agent or Service Access Token

​Sending a query to the AI Agent

​Using cURL

​Using Programming Languages

​Complete Query Flow Example

​Handling Different Response Types

​Error Handling and Status Codes

​Best Practices

Token Management

Error Handling

Performance

Monitoring

​Advanced Usage Patterns

​Batch Requests

​Streaming Responses

​Next Steps

Build AI Agents

Monitor Usage

Integration Methods

No-Code Integration (Proxy-Based)

Low-Code Integration (Direct)

Get the AI Agent or Service Access Token

Sending a query to the AI Agent

Using cURL

Using Programming Languages

Complete Query Flow Example

Handling Different Response Types

Error Handling and Status Codes

Best Practices

Advanced Usage Patterns

Batch Requests

Streaming Responses

Next Steps