payelink-agent-search 0.1.7

Python client for the Payelink Agent Search API.

PayeLink Agent Discovery SDK

What is this?

AI agents are multiplying across different protocols and organizations, but there's no easy way to discover them. This SDK solves that,search once, discover agents from anywhere.

Installation

pip install payelink-agent-search

Version

To check the installed version:

from payelink_agent_search import __version__
print(__version__)  # e.g., "0.1.6"

Quick Start

from payelink_agent_search import AgentSearchClient

# Create client
client = AgentSearchClient()

# Search for agents
response = client.search("Convert USD to KES")

# Use results
if response.success:
    for agent in response.agents:
        print(f"{agent.agent_name}: {agent.agent_description}")
        print(f"Endpoint: {agent.agent_card_url}")
        print("---")

client.close()

What Gets Discovered?

The SDK searches across multiple sources:

• ✅ A2A agents (/.well-known/agent-card.json)
• ✅ ACP agents (/.well-known/agent.yml)
• ✅ Custom registries (/agents/public)
• ✅ Open web (via intelligent search)

One search, every protocol.

Features

Multi-Protocol Discovery

# Automatically searches A2A, ACP, ANS, and custom endpoints
response = client.search("payment processing agent")

Filtering

response = client.search(
    query="Currency conversion",
    country="KE",              # Only Kenya
    capability="streaming",     # Must support streaming
    max_result=5
)

Context Manager Support

with AgentSearchClient() as client:
    response = client.search("translation agent")
    # Client auto-closes

Async Support

import asyncio
from payelink_agent_search import AsyncAgentSearchClient

async def main():
    async with AsyncAgentSearchClient() as client:
        response = await client.search("translation agent")
        if response.success:
            for agent in response.agents:
                print(f"{agent.agent_name}: {agent.agent_description}")

asyncio.run(main())

Async with Multiple Searches

import asyncio
from payelink_agent_search import AsyncAgentSearchClient

async def main():
    async with AsyncAgentSearchClient() as client:
        # Run multiple searches concurrently
        results = await asyncio.gather(
            client.search("currency conversion"),
            client.search("payment processing"),
            client.search("translation"),
        )
        
        for response in results:
            if response.success:
                print(f"Found {len(response.agents)} agents")

asyncio.run(main())

Response Format

class SearchResponse:
    success: bool                 # True if request succeeded
    agents: List[AgentDetails]    # Discovered agents (ranked)
    error: Optional[str]          # Error message if failed

class AgentDetails:
    agent_name: str               # Name of the agent
    agent_description: str        # What it does
    agent_card_url: str           # URL to invoke agent
    organization_name: str        # Who built it
    organization_url: str         # Organization website

Examples

Basic Search

from payelink_agent_search import AgentSearchClient

client = AgentSearchClient()
response = client.search("Find weather agents")

if response.success:
    print(f"Found {len(response.agents)} agents")
    for agent in response.agents:
        print(f"- {agent.agent_name}")

client.close()

Filtered Search

client = AgentSearchClient()

# Find agents with specific constraints
response = client.search(
    query="Financial services",
    country="KE",                               # Only agents from Kenya
    capability="streaming",                     # or "pushNotifications"
    default_input_mode=["text/plain", "application/json"],
    default_output_mode=["text/plain", "text/markdown"],
    max_result=5                                # Top 5 matches (default is 10)
)

if response.success:
    for agent in response.agents:
        print(f"{agent.agent_name} - {agent.organization_name}")
else:
    print(f"Error: {response.error}")

client.close()

Allowed values:

• capability: "streaming" or "pushNotifications"
• default_input_mode / default_output_mode: "text/plain", "application/json", "text/markdown"

Error Handling

from payelink_agent_search import AgentSearchClient
from payelink_agent_search.errors import SdkError

client = AgentSearchClient()

try:
    response = client.search("test query")
    
    if not response.success:
        print(f"Error: {response.error}")
    else:
        print(f"Success! Found {len(response.agents)} agents")
        
except SdkError as e:
    print(f"SDK Error: {e}")
finally:
    client.close()

Async Example

import asyncio
from payelink_agent_search import AsyncAgentSearchClient
from payelink_agent_search.errors import SdkError

async def main():
    async with AsyncAgentSearchClient() as client:
        try:
            response = await client.search("test query")
            
            if not response.success:
                print(f"Error: {response.error}")
            else:
                print(f"Success! Found {len(response.agents)} agents")
                
        except SdkError as e:
            print(f"SDK Error: {e}")

asyncio.run(main())

Why Use This?

Problem

• No unified way to discover them
• Manual configuration for each integration
• Agents can't find other agents to collaborate

Solution

• One search across all protocols
• Automatic discovery of agent endpoints
• Ranked results (most relevant first)
• Rich metadata (capabilities, organization, endpoints)

Use Cases

1. Agent-to-Agent Collaboration

# Supervisor agent needs a helper
payment_agent = client.search("payment processing KES").agents[0]
# Now supervisor can call payment_agent.agent_card_url

2. Dynamic Agent Selection

# Choose best agent at runtime (not hardcoded)
agents = client.search("translation Spanish to English", max_result=3)
best_agent = agents.agents[0]  # Highest ranked

3. Multi-Agent Workflows

# Build workflows from discovered agents
translator = client.search("translation").agents[0]
analyzer = client.search("sentiment analysis").agents[0]
mailer = client.search("email agent").agents[0]
# Chain them together

Requirements

• Python >= 3.8
• httpx >= 0.24.0
• pydantic >= 2.0.0

Error Types

• SdkError - Base error class
• HttpStatusError - HTTP 4xx/5xx errors
• NetworkError - Network failures
• TimeoutError - Request timeouts
• InvalidResponseError - Malformed responses

Links

• Documentation: Full docs
• Issues: GitHub Issues
• Source: GitHub

License

MIT License

---

Making AI agents discoverable • Built for the Agent 2.0 era