# A2A Registry Python Client
Official Python client library for the A2A Registry - a community-driven directory of AI agents.
## Installation
```bash
pip install a2a-registry-client
# For async support:
pip install "a2a-registry-client[async]"
```
## Quick Start
```python
from a2a_registry import Registry
# Initialize the registry client
registry = Registry()
# Get all agents
agents = registry.get_all()
for agent in agents:
print(f"{agent.name} - {agent.description}")
# Find agents by skill
weather_agents = registry.find_by_skill("weather-forecast")
# Find agents by capability
streaming_agents = registry.find_by_capability("streaming")
# Search agents by text
search_results = registry.search("translation")
```
## Features
- Simple, intuitive API
- Automatic caching for better performance
- Type hints and full typing support
- Comprehensive search and filtering options
- Lightweight with minimal dependencies
## API Reference
### Registry Class
#### `get_all() -> List[Agent]`
Retrieve all agents from the registry.
#### `find_by_skill(skill_id: str) -> List[Agent]`
Find agents that have a specific skill.
#### `find_by_capability(capability: str) -> List[Agent]`
Find agents with a specific A2A protocol capability (e.g., "streaming", "pushNotifications").
#### `find_by_author(author: str) -> List[Agent]`
Find all agents by a specific author.
#### `search(query: str) -> List[Agent]`
Search agents by text across name, description, and skills.
#### `get_by_id(agent_id: str) -> Optional[Agent]`
Get a specific agent by its ID.
### Agent Model
```python
class Agent:
name: str
description: str
author: str
wellKnownURI: str
skills: List[Skill]
capabilities: Optional[Capabilities]
version: Optional[str]
registryTags: Optional[List[str]]
documentationUrl: Optional[str]
# ... additional fields
```
### Skill Model
```python
class Skill:
id: str
name: str
description: str
tags: Optional[List[str]]
inputModes: Optional[List[str]]
outputModes: Optional[List[str]]
```
## Examples
### Finding Translation Agents
```python
from a2a_registry import Registry
registry = Registry()
# Find agents with translation skills
translators = registry.find_by_skill("translation")
for agent in translators:
print(f"Agent: {agent.name}")
print(f"Author: {agent.author}")
for skill in agent.skills:
if "translation" in skill.id.lower():
print(f" Skill: {skill.name} - {skill.description}")
```
### Filtering by Multiple Criteria
```python
from a2a_registry import Registry
registry = Registry()
# Get all agents
all_agents = registry.get_all()
# Filter for agents that support streaming and have specific skills
filtered = [
agent for agent in all_agents
if agent.capabilities and agent.capabilities.streaming
and any(s.id == "real-time-data" for s in agent.skills)
]
```
## Advanced Features
### Input/Output Mode Filtering
```python
# Find agents that accept specific input types
text_agents = registry.find_by_input_mode("text/plain")
image_agents = registry.find_by_input_mode("image/jpeg")
# Find agents that produce specific output types
json_agents = registry.find_by_output_mode("application/json")
# Find agents with both specific input AND output modes
versatile_agents = registry.find_by_modes(
input_mode="text/plain",
output_mode="application/json"
)
# Discover all available modes
input_modes = registry.get_available_input_modes()
output_modes = registry.get_available_output_modes()
```
### Multi-Criteria Filtering
```python
# Advanced filtering with multiple criteria
filtered_agents = registry.filter_agents(
skills=["text-generation", "summarization"],
capabilities=["streaming", "pushNotifications"],
input_modes=["text/plain"],
output_modes=["application/json"],
authors=["OpenAI", "Anthropic"],
tags=["production-ready"],
protocol_version="1.0"
)
```
### Enhanced Statistics
```python
stats = registry.get_stats()
print(f"Total agents: {stats['total_agents']}")
print(f"Streaming agents: {stats['capabilities_count']['streaming']}")
print(f"Available input modes: {stats['available_input_modes']}")
print(f"Protocol versions: {stats['protocol_versions']}")
```
### Registry Metadata Access
```python
for agent in registry.get_all():
print(f"Agent: {agent.name}")
print(f"Registry ID: {agent.registry_id}") # Smart property
print(f"Source: {agent.registry_source}") # Smart property
```
### Async Support
For high-performance applications:
```python
import asyncio
from a2a_registry import AsyncRegistry
async def main():
async with AsyncRegistry() as registry:
agents = await registry.get_all()
weather_agents = await registry.search("weather")
stats = await registry.get_stats()
# All sync methods available as async
filtered = await registry.filter_agents(
capabilities=["streaming"],
input_modes=["text/plain"]
)
asyncio.run(main())
```
## Caching
The client automatically caches the registry data for 5 minutes to reduce network requests. You can customize and control caching:
```python
# Custom cache duration (10 minutes)
registry = Registry(cache_duration=600)
# Manual cache control
registry.refresh() # Force reload from API
registry.clear_cache() # Clear cache
```
## Contributing
Contributions are welcome! Please see the main [A2A Registry repository](https://github.com/prassanna-ravishankar/a2a-registry) for contribution guidelines.
## License
MIT License - see LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "a2a-registry-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "a2a, agents, ai, registry, protocol",
"author": null,
"author_email": "A2A Registry Community <contact@a2aregistry.org>",
"download_url": "https://files.pythonhosted.org/packages/71/fc/49252321e709d22df279c5dd02532d0b360f04b137b1220abae1aa5c7204/a2a_registry_client-0.0.3.tar.gz",
"platform": null,
"description": "# A2A Registry Python Client\n\nOfficial Python client library for the A2A Registry - a community-driven directory of AI agents.\n\n## Installation\n\n```bash\npip install a2a-registry-client\n\n# For async support:\npip install \"a2a-registry-client[async]\"\n```\n\n## Quick Start\n\n```python\nfrom a2a_registry import Registry\n\n# Initialize the registry client\nregistry = Registry()\n\n# Get all agents\nagents = registry.get_all()\nfor agent in agents:\n print(f\"{agent.name} - {agent.description}\")\n\n# Find agents by skill\nweather_agents = registry.find_by_skill(\"weather-forecast\")\n\n# Find agents by capability\nstreaming_agents = registry.find_by_capability(\"streaming\")\n\n# Search agents by text\nsearch_results = registry.search(\"translation\")\n```\n\n## Features\n\n- Simple, intuitive API\n- Automatic caching for better performance\n- Type hints and full typing support\n- Comprehensive search and filtering options\n- Lightweight with minimal dependencies\n\n## API Reference\n\n### Registry Class\n\n#### `get_all() -> List[Agent]`\nRetrieve all agents from the registry.\n\n#### `find_by_skill(skill_id: str) -> List[Agent]`\nFind agents that have a specific skill.\n\n#### `find_by_capability(capability: str) -> List[Agent]`\nFind agents with a specific A2A protocol capability (e.g., \"streaming\", \"pushNotifications\").\n\n#### `find_by_author(author: str) -> List[Agent]`\nFind all agents by a specific author.\n\n#### `search(query: str) -> List[Agent]`\nSearch agents by text across name, description, and skills.\n\n#### `get_by_id(agent_id: str) -> Optional[Agent]`\nGet a specific agent by its ID.\n\n### Agent Model\n\n```python\nclass Agent:\n name: str\n description: str\n author: str\n wellKnownURI: str\n skills: List[Skill]\n capabilities: Optional[Capabilities]\n version: Optional[str]\n registryTags: Optional[List[str]]\n documentationUrl: Optional[str]\n # ... additional fields\n```\n\n### Skill Model\n\n```python\nclass Skill:\n id: str\n name: str\n description: str\n tags: Optional[List[str]]\n inputModes: Optional[List[str]]\n outputModes: Optional[List[str]]\n```\n\n## Examples\n\n### Finding Translation Agents\n\n```python\nfrom a2a_registry import Registry\n\nregistry = Registry()\n\n# Find agents with translation skills\ntranslators = registry.find_by_skill(\"translation\")\n\nfor agent in translators:\n print(f\"Agent: {agent.name}\")\n print(f\"Author: {agent.author}\")\n for skill in agent.skills:\n if \"translation\" in skill.id.lower():\n print(f\" Skill: {skill.name} - {skill.description}\")\n```\n\n### Filtering by Multiple Criteria\n\n```python\nfrom a2a_registry import Registry\n\nregistry = Registry()\n\n# Get all agents\nall_agents = registry.get_all()\n\n# Filter for agents that support streaming and have specific skills\nfiltered = [\n agent for agent in all_agents\n if agent.capabilities and agent.capabilities.streaming\n and any(s.id == \"real-time-data\" for s in agent.skills)\n]\n```\n\n## Advanced Features\n\n### Input/Output Mode Filtering\n\n```python\n# Find agents that accept specific input types\ntext_agents = registry.find_by_input_mode(\"text/plain\")\nimage_agents = registry.find_by_input_mode(\"image/jpeg\")\n\n# Find agents that produce specific output types\njson_agents = registry.find_by_output_mode(\"application/json\")\n\n# Find agents with both specific input AND output modes\nversatile_agents = registry.find_by_modes(\n input_mode=\"text/plain\",\n output_mode=\"application/json\"\n)\n\n# Discover all available modes\ninput_modes = registry.get_available_input_modes()\noutput_modes = registry.get_available_output_modes()\n```\n\n### Multi-Criteria Filtering\n\n```python\n# Advanced filtering with multiple criteria\nfiltered_agents = registry.filter_agents(\n skills=[\"text-generation\", \"summarization\"],\n capabilities=[\"streaming\", \"pushNotifications\"],\n input_modes=[\"text/plain\"],\n output_modes=[\"application/json\"],\n authors=[\"OpenAI\", \"Anthropic\"],\n tags=[\"production-ready\"],\n protocol_version=\"1.0\"\n)\n```\n\n### Enhanced Statistics\n\n```python\nstats = registry.get_stats()\nprint(f\"Total agents: {stats['total_agents']}\")\nprint(f\"Streaming agents: {stats['capabilities_count']['streaming']}\")\nprint(f\"Available input modes: {stats['available_input_modes']}\")\nprint(f\"Protocol versions: {stats['protocol_versions']}\")\n```\n\n### Registry Metadata Access\n\n```python\nfor agent in registry.get_all():\n print(f\"Agent: {agent.name}\")\n print(f\"Registry ID: {agent.registry_id}\") # Smart property\n print(f\"Source: {agent.registry_source}\") # Smart property\n```\n\n### Async Support\n\nFor high-performance applications:\n\n```python\nimport asyncio\nfrom a2a_registry import AsyncRegistry\n\nasync def main():\n async with AsyncRegistry() as registry:\n agents = await registry.get_all()\n weather_agents = await registry.search(\"weather\")\n stats = await registry.get_stats()\n \n # All sync methods available as async\n filtered = await registry.filter_agents(\n capabilities=[\"streaming\"],\n input_modes=[\"text/plain\"]\n )\n\nasyncio.run(main())\n```\n\n## Caching\n\nThe client automatically caches the registry data for 5 minutes to reduce network requests. You can customize and control caching:\n\n```python\n# Custom cache duration (10 minutes)\nregistry = Registry(cache_duration=600)\n\n# Manual cache control\nregistry.refresh() # Force reload from API\nregistry.clear_cache() # Clear cache\n```\n\n## Contributing\n\nContributions are welcome! Please see the main [A2A Registry repository](https://github.com/prassanna-ravishankar/a2a-registry) for contribution guidelines.\n\n## License\n\nMIT License - see LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client library for the A2A Registry",
"version": "0.0.3",
"project_urls": {
"Documentation": "https://github.com/prassanna-ravishankar/a2a-registry",
"Homepage": "https://www.a2aregistry.org",
"Issues": "https://github.com/prassanna-ravishankar/a2a-registry/issues",
"Repository": "https://github.com/prassanna-ravishankar/a2a-registry"
},
"split_keywords": [
"a2a",
" agents",
" ai",
" registry",
" protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "56c57c8fe8dada75f1902b99d40ee4b0aa68d407e48cc24c338b6c5fb828b546",
"md5": "805315abb4f999f7512b50aa8cefce03",
"sha256": "28758334dc2126f5285aaf2f9f376939c4fdad9e5e08825a421f08b882b12a22"
},
"downloads": -1,
"filename": "a2a_registry_client-0.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "805315abb4f999f7512b50aa8cefce03",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 9051,
"upload_time": "2025-08-13T13:41:05",
"upload_time_iso_8601": "2025-08-13T13:41:05.595635Z",
"url": "https://files.pythonhosted.org/packages/56/c5/7c8fe8dada75f1902b99d40ee4b0aa68d407e48cc24c338b6c5fb828b546/a2a_registry_client-0.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "71fc49252321e709d22df279c5dd02532d0b360f04b137b1220abae1aa5c7204",
"md5": "bc2c5e4e68762c6f0890aca566af2ae2",
"sha256": "9577a01a3ce98b74adbbef2eb874087fc944c2d0cef18e9455708134f086e4af"
},
"downloads": -1,
"filename": "a2a_registry_client-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "bc2c5e4e68762c6f0890aca566af2ae2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 10356,
"upload_time": "2025-08-13T13:41:06",
"upload_time_iso_8601": "2025-08-13T13:41:06.936231Z",
"url": "https://files.pythonhosted.org/packages/71/fc/49252321e709d22df279c5dd02532d0b360f04b137b1220abae1aa5c7204/a2a_registry_client-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 13:41:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "prassanna-ravishankar",
"github_project": "a2a-registry",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "a2a-registry-client"
}
JSON
