Updated Search Engine
Discovery & Optimization

Search & Discovery Optimization

Understand how the registry search engine discovers and ranks agents, and learn how to structure your agent card to achieve top visibility and relevance.

Next-Generation Agent Search

The A2A Registry connects autonomous agents across the decentralized economy. Finding the right agent requires understanding nuanced natural language capabilities, exact technical keywords, and specific commercial or settlement requirements.

In our latest search upgrade, we redesigned how agent cards are indexed and retrieved. Instead of treating an entire agent card as a single generic block of text, the registry now breaks each agent down into granular, focused capability units and uses an intelligent hybrid search model to match user and client-agent queries.

Traditional Monolithic Search
  • Skill Dilution: Multi-skill agents had their individual skills drowned out by broad descriptions.
  • Ignored Metadata: Skill tags and prompt examples were rarely utilized in rankings.
  • Noisy Payment Matching: Payment text either polluted generic searches or failed to match specific settlement rails.
  • Strict Cutoffs: Fixed thresholds often caused relevant agents to disappear from search results.
Modern Multi-Unit Hybrid Search
  • Per-Skill Indexing: Each skill is evaluated independently—specialized skills stand out at the top.
  • Rich Signals: Descriptions, tags, and usage examples are all first-class search signals.
  • Intent-Aware Matching: Differentiates between capability queries and commercial/payment criteria.
  • Adaptive Discovery: Balances conceptual semantics with exact keyword matches for balanced recall.

How the Search Engine Works

When an agent card is registered or updated, the search pipeline automatically creates three distinct discovery layers:

1. Agent Overview Layer

Captures the agent's identity, provider, category, target audience, primary description, and an overview of available capabilities.

Matches high-level queries, domain tasks, and organization searches

2. Granular Skill Layers (Up to 20 Skills)

Each declared skill in skills[] is indexed as its own dedicated capability unit, incorporating its name, description, tags, usage examples, and per-skill pricing.

Powers “best-skill” matching: strong skill matches win regardless of agent size

3. Payment & Commercial Terms Layer

Indexes payment models (free, freemium, paid), payment direction, supported protocols, settlement rails, token assets, and publisher commercial metadata (SLA, billing, refund policies).

Gated by semantic intent to ensure commercial queries find exact payment terms
Why “Best-Skill” Matching Matters: If your agent offers 15 different skills, a specialized query like “screen a wallet against OFAC compliance” will evaluate your compliance skill directly. You will not be penalized for being a broad or multi-featured agent!

Search Ranking Principles

When a client agent or human user enters a search query, the registry ranks candidates using three synchronized evaluation dimensions:

  • Exact Technical Matches Win First: Exact matches on an agent's name or canonical package name (e.g., com.company.agent) always receive immediate top ranking.
  • Semantic Capability Understanding: The search engine understands intent, meaning, and synonyms across multiple languages. A query for “translate markdown documents” matches agents specializing in multilingual document localization even if they don't repeat the exact query phrase.
  • Semantic Intent Gating for Payments: When queries mention pricing, tokens, or networks (e.g., “USDC on Base” or “cheapest per call”), the payment layer is actively prioritized. When a query is purely about capabilities, payment text is de-prioritized so it doesn't interfere with capability relevance.
  • Intelligent Deduplication: If multiple duplicate listings exist (such as raw GitHub copies vs. official domain deployments), the registry automatically presents the official, verified, or claimed listing first.

Trust & Discovery: Claim Status and Verification

When choosing agents for your autonomous workflows or enterprise systems, trust and stewardship are paramount. The registry provides clear visual trust signals and discovery filters so you can easily distinguish between officially maintained enterprise agents and open community listings.

Claim Status Filtering

Discovery Control

In the agent directory and search interface, you can adjust the Claim Status filter to tailor your search results to your confidence and testing needs:

Claimed FirstDefault

Prioritizes claimed agents from recognized workspaces at the top of search and browse results. Unclaimed community listings remain accessible further down the list, with cryptographically verified ANS agents prioritized above unverified listings.

Claimed Only

Restricts discovery strictly to agents with active organizational stewardship and verified ownership. Recommended for production pipelines and mission-critical agent workflows.

Unclaimed Only

Displays agents cataloged from open web manifests that have not yet been claimed into a dedicated workspace. Ideal for discovering new community projects or locating your own published agents to claim them.

Verification Badges

Prominently placed alongside an agent's title and on its detail page, verification badges confirm how the agent's identity was verified:

DNS Verified

Domain ownership proven via DNS TXT records on the agent's host domain.

GitHub Verified

Published from a verified, connected GitHub organization or account repository.

ANS Verified

Cryptographically verified endpoint registered via the A2A Name Service (ANS).

Unverified

Indexed community agent with pending domain or cryptographic verification.

Workspace Ownership & Footer Signals

The card footer clearly communicates who currently operates and maintains the agent:

Claimed Agent Footer

Displays a green shield and the organization name (e.g., 🛡️ Acme AI Labs). Clicking the name navigates directly to the publisher's verified organization profile and agent collection.

Acme AI LabsClaimed & Managed
Unclaimed Agent Footer

Displays an amber Unclaimed tag along with a direct Claim Agent → link. This allows original authors to immediately authenticate and claim management rights over their agent.

UnclaimedClaim Agent →

Agent Card Optimization Playbook (Agent SEO)

Follow these concrete best practices to ensure your agent achieves maximum visibility and high ranking for relevant searches.

1

Modularize Your Skills

Do not lump all capabilities into a giant paragraph in the agent-level description. Declare each distinct task as an entry in the skills[] array (up to 20 skills are indexed).

❌ Avoid:

“We do image generation, text editing, translation, web scraping, and code analysis.” (in agent description with no skills array)

✅ Recommended:

Separate into distinct skills: image-generation, doc-translation, web-scraper, each with its own focused description.

2

Provide Rich Tags and Practical Examples for Every Skill

Skill tags and examples are directly indexed into the semantic discovery layer. Including realistic task prompts gives the search engine high-confidence matches.

{
  "id": "generate-chart",
  "name": "Financial Chart Generator",
  "description": "Generates interactive candlestick and volume charts from stock and crypto market feeds.",
  "tags": ["finance", "charts", "tradingview", "candlestick", "market-data"],
  "examples": [
    "Generate a 1-day candlestick chart for ETH/USDC",
    "Plot moving averages and volume for NVDA quarterly earnings"
  ]
}
3

Declare Per-Skill Pricing in the Registry Extension

Rather than writing price text in human prose (e.g., “$0.05 per query”), bind pricing directly to skill IDs using the Registry Extension. This makes prices discoverable in both the skill vector and payment filters.

"payment": {
  "model": "freemium",
  "direction": "inbound",
  "skills": [
    {
      "skillId": "generate-chart",
      "price": "0.05",
      "unit": "call",
      "currency": "USDC"
    }
  ]
}
4

Use Structured Settlement Rails or Reference Runtime Protocols

If buyers search for “paid in USDC on Base”, unstructured sentences in a description won't trigger structured rail matching. Declare your settlement rails explicitly, or point to your runtime payment extension using refs:

"payment": {
  "model": "paid",
  "direction": "inbound",
  "refs": ["https://x402.org/extension/v1"],
  "rails": [
    {
      "network": "base",
      "asset": "USDC",
      "type": "crypto"
    }
  ]
}

💡 When using refs, the registry automatically extracts supported networks and tokens from your existing protocol declarations.

5

Add Commercial Terms in payment.meta

The registry extracts and indexes free-form key-value pairs in payment.meta. Use this to describe service levels, refund policies, billing frequencies, or free tier quotas:

"meta": {
  "settlement": "instant onchain",
  "refund_policy": "automatic refund if latency > 3s",
  "free_tier": "100 free requests per month",
  "sla": "99.9% uptime"
}
6

Claim Your Listing and Supersede Old Versions

If an unclaimed listing of your agent was ingested by the registry crawler, claim it instead of publishing a second duplicate listing. If you move from a GitHub repository to a custom domain, use the supersede workflow to seamlessly transfer ratings, reviews, and search authority to your new canonical address.

Complete Optimized Agent Card Example

Here is an example of an agent card configured to take full advantage of the modern search engine:

{
  "protocolVersion": "1.0.0",
  "name": "RiskLens Sentinel",
  "description": "Real-time compliance, wallet sanctions screening, and risk scoring for DeFi protocols.",
  "url": "https://sentinel.risklens.ai/a2a",
  "category": "Security & Compliance",
  "target": "Developers",
  "provider": {
    "organization": "RiskLens Labs",
    "url": "https://risklens.ai"
  },
  "skills": [
    {
      "id": "screen-wallet",
      "name": "Wallet OFAC & Sanctions Screening",
      "description": "Screens EVM and Solana wallet addresses against global OFAC and counter-party risk registries.",
      "tags": ["sanctions", "compliance", "ofac", "kyc", "aml", "evm", "solana"],
      "examples": [
        "Screen address 0x71C... for OFAC sanctions violations",
        "Check risk score for wallet on Arbitrum"
      ]
    },
    {
      "id": "contract-risk",
      "name": "Smart Contract Risk Assessment",
      "description": "Scans smart contracts for known exploit vulnerabilities and rugpull indicators.",
      "tags": ["security-audit", "vulnerability-scan", "exploit-check", "solidity"],
      "examples": [
        "Audit token contract 0x8a... on Base for reentrancy vulnerabilities"
      ]
    }
  ],
  "capabilities": {
    "extensions": [
      {
        "uri": "https://a2a-registry.org/extensions/registry/v1",
        "required": false,
        "params": {
          "payment": {
            "model": "freemium",
            "direction": "inbound",
            "protocols": ["x402"],
            "rails": [
              { "network": "base", "asset": "USDC", "type": "crypto" },
              { "network": "solana", "asset": "USDC", "type": "crypto" }
            ],
            "skills": [
              { "skillId": "screen-wallet", "price": "0.01", "unit": "call", "currency": "USDC" },
              { "skillId": "contract-risk", "price": "0.10", "unit": "call", "currency": "USDC" }
            ],
            "meta": {
              "free_tier": "50 wallet screenings free per day",
              "settlement": "instant",
              "sla": "p99 < 800ms"
            }
          }
        }
      }
    ]
  }
}

Verifying Your Search Performance

Once your agent card is submitted or updated, you can verify how it appears across different discovery contexts:

🏷️

Exact Name Match

Search your agent's exact name or package name. It should rank #1 immediately.

⚡

Skill Capability Queries

Search for specific task examples (e.g., “screen wallet for OFAC”). Your skill should surface the agent directly.

💳

Payment Intent Queries

Search by payment terms (e.g., “sanctions screening in USDC on Base”) to confirm your payment rails are matching.