igentbase User Guide

Everything you need to discover, install, and use AI agents on the igentbase marketplace.

What is igentbase?

igentbase is a marketplace for AI agents. Developers publish agents that you can install and use through a simple API. Think of it like an app store, but for AI capabilities you call from your code, your IDE, or your AI assistant.

• Browse hundreds of agents across categories like productivity, security, devtools, analytics, and more
• Install any agent with one click
• Call agents through the igentbase endpoint using access keys
• Pay only for what you use — no subscriptions, no monthly fees

Creating an Account

Sign up with one of three OAuth providers:

• Google — use your Google account
• Microsoft — use your Microsoft/Azure AD account
• GitHub — use your GitHub account

We never see or store your password. Authentication is handled entirely by the OAuth provider. A session cookie keeps you signed in for up to 7 days.

Free Credits

Every new account receives $100 in free credits automatically. No credit card, no subscription, no strings attached.

Once your free credits run out, add more in the Billing page. You're never automatically charged — you add credits when you're ready.

Your Dashboard

The dashboard gives you an at-a-glance view of your account:

Below the stats, you'll see My Agents — a list of all agents you've installed. Click any agent to see detailed usage and settings.

Browsing the Agent Store

The Store page is your gateway to discovering agents. You can:

• Search — find agents by name or developer
• Filter by:
  • Category — productivity, communication, security, devtools, analytics, sales, etc.
  • Platform — Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, etc.
  • Capabilities — reasoning, planning, RAG, semantic search, code generation, etc.
  • Protocol — MCP or A2A
• Sort — by Popular (most installs), Newest, or Top Rated
• Paginate — browse through results 12 at a time

Each agent card shows the name, developer, short description, rating, install count, and category badges.

Agent Details

Click any agent to see its full profile with six tabs:

The hero section at the top shows key stats: rating, install count, last updated date, and protocol type.

Installing & Uninstalling Agents

Installing

1. Find the agent in the Store or marketplace
2. Click Install (or Use Agent on the marketplace site)
3. The agent appears in your My Agents list on the dashboard
4. Create an API key for the agent to start making calls

Uninstalling

1. Go to the agent's Usage page from your dashboard
2. In Settings, click Uninstall
3. All API keys for that agent are immediately revoked
4. You won't be charged for any calls after uninstalling

Versions & Pricing

Each agent can have multiple versions (e.g., 1.0.0, 1.1.0, 2.0.0). Here's what to know:

Versioning

• Versions use semver format (major.minor.patch)
• When you install an agent, you interact with a specific version
• The version is part of the API URL: /agent-name/1.0.0/mcp
• Developers can publish new versions with additional features or bug fixes

Pricing Stability

• You are never surprised by a price change on a version you're already using
• If a developer releases a more expensive version, you can stay on the old one
• Deprecated versions continue to work but may eventually be retired (with advance notice)

Reviews & Ratings

Help the community by reviewing agents you've used:

1. Go to the agent's detail page in the Store
2. Click the Reviews tab
3. Select a star rating (1-5) and write your review
4. Your review appears publicly with your display name

You can edit or delete your own reviews at any time. Reviews help other users discover quality agents and help developers improve their products.

Creating API Keys

API keys are how you authenticate calls to agents. Each key is scoped to one agent.

Creating a Key

1. Go to the agent's Usage page (click the agent from your dashboard)
2. Switch to the Settings tab
3. Click Create API Key
4. Give it a name (e.g., "Production", "Testing")
5. Copy the key immediately — it's shown only once

Key Format

Keys look like: atx-550e8400-e29b-41d4-a716-446655440000

The first few characters identify the agent. The rest is a unique random token.

Managing Keys

• You can create multiple keys per agent (e.g., separate keys for dev/staging/prod)
• Each key tracks its own usage (requests, tokens, cost)
• Revoke a key instantly from the Settings tab — it stops working immediately
• Set per-key daily limits to control spending (see Per-Key Daily Limits)

Using MCP Agents

MCP (Model Context Protocol) is the standard protocol for tool-calling agents. Most agents on igentbase use MCP.

How It Works

MCP uses JSON-RPC 2.0 over HTTPS. You send a request to the igentbase endpoint, which authenticates you and forwards it to the agent. The agent processes it and returns a response.

Endpoint

POST https://a3s.igentbase.com/{agent_id}/{version}/mcp

Making a Call

curl -X POST https://a3s.igentbase.com/codereview-pro/1.0.0/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "review_pr",
      "arguments": {
        "repo": "myorg/myrepo",
        "pr_number": 42
      }
    }
  }'

Common MCP Methods

MCP Response Format

MCP agents return JSON-RPC 2.0 responses. A successful tools/call response looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "The PR looks good overall. Two suggestions:\n1. Add null check on line 42\n2. Extract the retry logic into a helper function."
      }
    ]
  }
}

Content Types in MCP Responses

The content array can contain different types:

MCP Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Insufficient credits. Please add credits to continue.",
    "data": null
  }
}

MCP Streaming (SSE)

Some MCP functions support streaming via Server-Sent Events. The response arrives as a series of data: lines:

data: {"streaming":true,"delta":"The PR "}\n\n
data: {"streaming":true,"delta":"looks good "}\n\n
data: {"streaming":true,"delta":"overall."}\n\n
data: {"streaming":true,"delta":null,"input_tokens":42,"output_tokens":9,"cache_tokens":0}\n\n
data: [DONE]\n\n

• delta — the next chunk of text (null in the final usage event)
• The last event before [DONE] carries the total token counts
• [DONE] signals the end of the stream

Using MCP in AI Clients

Many AI clients (Claude Desktop, Cursor, Windsurf, VS Code extensions) support MCP natively. Check the agent's Integration tab for specific setup instructions for your platform. Typically you configure the endpoint URL and access key in your client's MCP settings.

Cold Start Agents

Some agents are hosted on serverless platforms (Vercel, Railway, Fly, Render, etc.) and take a few seconds to wake up on the first call. These agents are marked with a warmup indicator on their detail page.

To avoid latency on your first request, send a health check to wake the agent before calling it:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://a3s.igentbase.com/{agent_id}/{version}/health

Wait for a 200 response, then make your real MCP/A2A call. Subsequent calls will be fast as long as the agent stays warm. All agents on igentbase are required to have a /health endpoint, so this works for every agent.

Using A2A Agents

A2A (Agent-to-Agent) is Google's protocol for agent orchestration. Use A2A agents when you need agents to coordinate with each other.

Endpoint

POST https://a3s.igentbase.com/{agent_id}/{version}/a2a

Sending a Task

curl -X POST https://a3s.igentbase.com/data-analyst/1.0.0/a2a \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tasks/send",
    "params": {
      "id": "task-001",
      "message": {
        "role": "user",
        "parts": [
          {"type": "text", "text": "Analyze Q1 revenue trends"}
        ]
      }
    }
  }'

A2A for Orchestration

A2A is designed for multi-agent workflows where one agent delegates subtasks to others:

1. Your orchestrator agent sends a task to a specialist agent via tasks/send
2. For long-running tasks, use tasks/sendSubscribe to get SSE progress updates
3. Check task status with tasks/get
4. Agents can exchange artifacts (artifacts/create, artifacts/get)
5. Cancel running tasks with tasks/cancel

A2A Response Format

A2A responses follow the JSON-RPC 2.0 format. A successful tasks/send response returns a task object:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "task-001",
    "status": {
      "state": "completed"
    },
    "artifacts": [
      {
        "name": "analysis_result",
        "parts": [
          {
            "type": "text",
            "text": "Q1 revenue grew 23% YoY driven by enterprise expansion..."
          }
        ]
      }
    ]
  }
}

Task States

A2A Streaming (SSE via tasks/sendSubscribe)

For long-running tasks, use tasks/sendSubscribe to get real-time status updates:

data: {"jsonrpc":"2.0","id":1,"result":{"id":"task-001","status":{"state":"working","message":{"role":"agent","parts":[{"type":"text","text":"Analyzing revenue data..."}]}}}}\n\n
data: {"jsonrpc":"2.0","id":1,"result":{"id":"task-001","status":{"state":"working","message":{"role":"agent","parts":[{"type":"text","text":"Generating report..."}]}}}}\n\n
data: {"jsonrpc":"2.0","id":1,"result":{"id":"task-001","status":{"state":"completed"},"artifacts":[{"name":"report","parts":[{"type":"text","text":"Q1 revenue grew 23%..."}]}]}}\n\n

Each SSE event contains the full task object with its current state. When state reaches completed, failed, or canceled, the stream ends.

Artifact Parts

A2A artifacts can contain multiple parts of different types:

A2A Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "data": null
  }
}

Agent Discovery

Every A2A agent has a public Agent Card at:

GET https://a3s.igentbase.com/{agent_id}/{version}/.well-known/agent.json

This is unauthenticated — no API key needed. It returns the agent's capabilities, supported methods, and metadata.

MCP Dependencies

Some A2A agents depend on other MCP agents to complete tasks. For example, a "Research Assistant" A2A agent might call a "Web Search" MCP agent under the hood.

• When you install an A2A agent with MCP dependencies, the required MCP agents are automatically installed for you
• Managed API keys are created for each dependency (named "Auto: {Agent Name}")
• You are billed for both the A2A call and any MCP calls it makes — the total cost is shown on the agent's store page
• Dependencies and their estimated cost per task are listed on the agent's detail page

Task Timeout

A2A tasks have a configurable timeout — if a task doesn't complete within the timeout window, it expires. The default timeout is set by the developer for each skill, but you can override it:

1. Go to the agent's Usage page
2. Switch to Settings
3. Adjust Task Token Timeout (1 minute to 24 hours)

The developer's recommended timeout is shown as a hint. If you customize it, your setting is preserved even when the developer updates theirs.

Examples

Python — Call an MCP Agent

import httpx

API_KEY = "atx-your-key-here"
GATEWAY = "https://a3s.igentbase.com"

response = httpx.post(
    f"{GATEWAY}/codereview-pro/1.0.0/mcp",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tools/call",
        "params": {
            "name": "review_pr",
            "arguments": {"repo": "myorg/myrepo", "pr_number": 42}
        }
    }
)

result = response.json()
print(result)

Node.js — Call an MCP Agent

const response = await fetch(
  'https://a3s.igentbase.com/codereview-pro/1.0.0/mcp',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer atx-your-key-here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      id: 1,
      method: 'tools/call',
      params: {
        name: 'review_pr',
        arguments: { repo: 'myorg/myrepo', pr_number: 42 }
      }
    })
  }
);

const result = await response.json();
console.log(result);

Python — SSE Streaming (A2A)

import httpx

API_KEY = "atx-your-key-here"
GATEWAY = "https://a3s.igentbase.com"

with httpx.stream(
    "POST",
    f"{GATEWAY}/data-analyst/1.0.0/a2a",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "tasks/sendSubscribe",
        "params": {
            "id": "task-001",
            "message": {
                "role": "user",
                "parts": [{"type": "text", "text": "Analyze revenue"}]
            }
        }
    }
) as resp:
    for line in resp.iter_lines():
        if line.startswith("data: "):
            print(line[6:])

curl — List Available Tools

# Discover what tools an MCP agent offers (low cost — base fee only)
curl -X POST https://a3s.igentbase.com/codereview-pro/1.0.0/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Free Tier & Trials

Some agents offer a free tier — a limited number of free calls per function before billing starts.

Reset Period

Free tier limits use one of two reset periods, set by the developer:

• Lifetime (default) — your free calls never reset. Once used, they're gone
• Monthly — your free call count resets at the start of each calendar month. Look for the "/month" indicator on the Freemium badge

Look for the "Freemium" badge on agent functions in the Integration tab to see which ones offer free calls, how many, and whether they reset monthly.

Adding Credits

Go to Billing in the sidebar to manage your credits.

Adding Credits Manually

1. Click Add Credits
2. Select an amount ($5 to $982)
3. Pay with a saved payment method or add a new card
4. Credits are available instantly

Payment Methods

Add credit or debit cards in the Payment Methods tab. Cards are stored securely via Stripe — igentbase never sees your full card number.

How Pricing Works

Agents use one of two pricing models per function:

Per-Token Pricing

Cost scales with input/output length. Best for LLM-based agents.

Cost = (input_tokens / 1,000,000 × input_price)
     + (output_tokens / 1,000,000 × output_price)
     + (cache_tokens / 1,000,000 × cache_price)

Example: 500 input tokens at $2.00/1M + 200 output tokens at $4.00/1M = $0.001 + $0.0008 = $0.0018 per call.

Per-Request Pricing

Fixed cost per call, regardless of input/output size. Best for deterministic operations.

Example: $0.005 per call, whether you send 10 words or 10,000.

Base Fee (Overhead)

Utility methods like tools/list, initialize, and health/check are charged a negligible base fee (fractions of a cent). You'll rarely notice this on your bill.

Failed Requests

You are never charged for requests that fail. If an agent returns an error or is unreachable, no credits are deducted from your balance.

For streaming responses, you are charged only for the output you actually received. If a stream completes partially, you pay for the tokens delivered to you — not for the full response the agent intended to send.

View the exact pricing for each function in the agent's Integration tab before you install.

Token Calculation

For per-token agents, your cost depends on how many tokens are in the request and response.

What Are Tokens?

Tokens are the units that language models process. Roughly:

• 1 token ≈ 4 characters of English text
• 1 token ≈ 0.75 words
• 100 tokens ≈ 75 words
• 1,000 tokens ≈ 750 words (about 1.5 pages)

How Tokens Are Counted

Two independent counts happen for every per-token call:

1. The agent reports its model's token count in the response
2. The platform independently counts by tokenizing the request and response bodies using the same encoding the agent uses (e.g., cl100k_base for GPT/Claude models)

If the two counts diverge significantly (>20%), the call is flagged for review. This trust-but-verify system prevents agents from overcharging.

Three Token Types

Your exact token usage and cost per call are visible in the Audit tab of the agent's Usage page.

Auto-Recharge

Never run out of credits unexpectedly. Set up auto-recharge in Billing > Overview:

Auto-recharge uses your default payment method. You'll receive a notification each time it fires.

Organization Budget

Set a monthly spending cap for your entire organization in Billing > Overview. When the cap is reached, all API calls are rejected with a 429 error until the next month or until you raise the limit.

This is useful for teams to prevent runaway costs from automated processes.

Billing History

View all credit purchases and grants in Billing > Billing History. Each entry shows the date, amount, payment method, and a downloadable invoice.

The Grants tab shows credit grants (like your initial $100 free credits).

Rate Limits

The platform enforces rate limits to protect agents and ensure fair usage:

Every response includes rate limit headers so you know where you stand:

X-RateLimit-Limit-Requests-Minute: 60
X-RateLimit-Remaining-Requests-Minute: 42
X-RateLimit-Reset-Requests-Minute: 18s

When you hit a limit, the platform returns HTTP 429 with a Retry-After header telling you how long to wait.

Per-Key Daily Limits

Control spending per API key by setting daily limits in the agent's Settings tab:

Limits reset daily at midnight UTC. Once a limit is hit, the key is blocked for the rest of the day with a 429 response.

Stream Limits

For streaming responses (SSE), the platform enforces safety caps per response:

• 100,000 events max per response stream
• 1 GB max total response size

These are generous limits — a typical streaming response uses a few hundred events. If a stream is truncated, you're only billed for what you received.

Usage Dashboard

Click any installed agent to see its Usage page with detailed analytics:

Details Tab

• Date range filter — view usage for any time period
• Stat cards — total calls, total spend, average latency, error rate
• Usage chart — visual trend of calls and cost over time
• Detailed metrics — requests, input/output/cache cost breakdowns, latency percentiles, error counts
• Free quota — remaining free calls per function (if the agent offers a free tier)

Settings Tab

• Create and manage API keys
• View per-key usage (requests, cost)
• Set per-key daily limits
• View rate limit configuration
• Set task token timeout (A2A agents only) — controls how long task tokens remain valid

Audit Log

The Audit tab on the Usage page shows every individual API call with these columns:

Click any row to see full details including error messages. Search and filter by date range.

Data Export

Export your usage data as CSV from the Audit tab. Select a date range and click Export CSV. The export includes all calls with: Date/Time, Request ID, Version, Function, Input Tokens, Output Tokens, Cache Tokens, Latency, Status, and Error details.

Data Protection

What igentbase does log (for billing and monitoring only):

• Token counts (input, output, cache)
• Latency (response time)
• Function name called
• Cost per call
• Error codes (not error content)

What igentbase never logs:

• The content of your prompts or requests
• The content of agent responses
• Files or attachments you send to agents
• Your browsing history or cross-site activity

What is never shared with agent developers:

• Your IP address or geographic location
• Your account email or personal details
• Your API key or session tokens

Developers see only an anonymous usage token per agent. They cannot identify, track, or locate you.

All data in transit is encrypted with TLS 1.3. Data at rest is encrypted with AES-256.

Agent Governance

Every agent on the marketplace must declare its data governance practices. Check the Data & Privacy tab on any agent's detail page to see:

• Data collection — what data the agent collects from you
• Data storage — where your data is stored (region, provider)
• Data retention — how long your data is kept
• Training policy — whether your data is used for model training
• Compliance — GDPR, SOC 2, HIPAA certifications
• Security measures — encryption, access controls

This information is provided by the agent developer and verified by the platform.

Trust Scores

Every agent has a trust score computed from its governance declarations, uptime history, and compliance. Higher scores mean better transparency and security practices.

You can filter agents by trust score in the marketplace to find agents that meet your data protection requirements.

Team Management

Add team members to share your agent installations and billing. Go to Team in the sidebar.

Adding Members

1. Click Add Member
2. Enter their name and email
3. Choose whether they're an Admin (can manage billing, keys, and members) or a regular member
4. They receive an invitation email

What Team Members Share

• All installed agents
• Credit balance (shared organization wallet)
• Organization budget limit

What Team Members Have Separately

• Their own API keys
• Their own per-key daily limits
• Their own rate limit counters

Profile & Billing Info

Update your information in Profile:

Profile Information

• Full name
• Email (read-only — set by OAuth provider)
• Phone number
• Organization name
• Country

Billing Information

• Billing email (for invoices)
• Business address
• Tax ID (VAT, EIN, GST — for invoice compliance)

Notifications

The Notifications page shows alerts about your account:

• Low balance warnings
• Auto-recharge events
• Agent updates and new versions
• Agent deprecation notices
• Rate limit warnings
• Team invitation updates

Toggle email notifications on or off in Settings.

Settings

• Theme — switch between light and dark mode
• Email notifications — toggle on/off
• Account deletion — see below

Manage Account via API

Manage your account programmatically using API tokens. Generate a token from Settings > API Tokens.

Authentication

Include your token in the Authorization header:

Authorization: Bearer igb_usr_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Scopes

Tokens can be scoped to limit access. Leave scopes empty for full access.

Example: List Installed Agents

curl -H "Authorization: Bearer igb_usr_abc123..." \
  https://agent.igentbase.com/data/agents_added_list

Example: Check Balance

curl -H "Authorization: Bearer igb_usr_abc123..." \
  https://agent.igentbase.com/data/billing/credit_balance

Example: View Usage

curl -H "Authorization: Bearer igb_usr_abc123..." \
  "https://agent.igentbase.com/data/usage?page=1"

Response Format

// Success
{ "status": 1, "json": { ... } }

// Error
{ "status": 0, "msg": "Error description" }

Rate Limits

API tokens share the same rate limits as the dashboard. There is no separate rate limit for API access.

Token Management

• Generate tokens from Settings > API Tokens in your dashboard
• Maximum 10 active tokens per account
• Tokens can have expiration dates (30 days, 90 days, 1 year, or never)
• Revoke tokens anytime — they stop working immediately
• Tokens can be viewed anytime from the settings page — use the eye icon to reveal

Deleting Your Account

You can delete your account from Settings > Danger Zone.

When you delete your account:

• All API keys are immediately revoked
• All agent installations are removed
• Your profile and team memberships are deleted
• Remaining credit balance is forfeited (not refundable)
• Billing history is retained for 7 years (legal requirement)
• Reviews you've written remain visible (anonymized)

Before deleting, export any data you need from the Audit tab.

Error Codes

Platform Errors (from igentbase)

MCP Errors (JSON-RPC)

Agent Errors (from the agent itself)

When You're Throttled

If you receive a 429 response:

1. Check the Retry-After header — it tells you exactly how many seconds to wait
2. Check which limit you hit:
   • X-RateLimit-Remaining-Requests-Minute: 0 → you hit the per-minute limit, wait ~60s
   • X-RateLimit-Remaining-Requests-Hour: 0 → hourly limit, wait longer
   • Message says "insufficient credits" → add credits in Billing
   • Message says "organization budget" → raise your budget limit or wait for next month
   • Message says "daily limit" → your per-key limit was hit, wait until midnight UTC
3. Implement exponential backoff in your code — don't hammer the API with retries

Backoff Example (Python)

import time
import httpx

def call_with_retry(url, headers, body, max_retries=3):
    for attempt in range(max_retries):
        resp = httpx.post(url, headers=headers, json=body)
        if resp.status_code != 429:
            return resp

        retry_after = int(resp.headers.get("Retry-After", 5))
        wait = min(retry_after * (2 ** attempt), 60)
        print(f"Throttled. Waiting {wait}s...")
        time.sleep(wait)

    return resp  # return last 429 if all retries exhausted

Getting Help

Go to Support in the sidebar to:

• Submit a new support ticket
• View your ticket history and responses
• Report an agent (from the agent's detail page)

For urgent issues, email [email protected].

Terms & Privacy

By using igentbase, you agree to:

• Terms of Service
• Privacy Policy

Key Points

• igentbase does not intercept, inspect, store, or log the content of your requests or agent responses
• Only metadata (token counts, latency, cost) is recorded for billing
• Your data is never sold to advertisers or data brokers
• Your data is never used for AI model training
• Session cookies are server-side (Redis) with 7-day expiry
• We do not use tracking cookies, analytics pixels, or third-party cookies

Questions? Visit Support or email [email protected].