# ANS Python SDK
Python SDK for interacting with the Agent Network System (ANS).
## Installation
Install from PyPI:
```bash
pip install ans-project-sdk
```
## Usage
### ANSClient
The main entry point for the SDK is the `ANSClient` class.
```python
from ans_project.sdk import ANSClient
client = ANSClient() # Defaults to public ANS endpoint
# Generate a new key pair
public_key, private_key = ANSClient.generate_key_pair()
# Register an agent
agent_data = {
"agent_id": "my-python-agent.ans",
"name": "My Python Agent",
"capabilities": ["python_sdk_test"],
"public_key": public_key
}
try:
response = client.register(agent_data, private_key)
print("Registration successful:", response)
except Exception as e:
print("Registration failed:", e)
# Lookup an agent
try:
response = client.lookup({"agent_id": "my-python-agent.ans"})
print("Lookup successful:", response)
except Exception as e:
print("Lookup failed:", e)
```
### anslookup CLI
The SDK includes a command-line interface tool, `anslookup`, for quickly querying the Agent Network System.
To use it, ensure the SDK is installed (e.g., `pip install ans-project-sdk`)
```bash
# Get help and see all options
anslookup --help
# Lookup an agent by its ID
anslookup my-python-agent.ans
# Lookup agents by name and trust level
anslookup --query "Nexus Voyager" --trust-level "provisional"
# Lookup agents by capabilities (use quotes for capabilities with spaces)
anslookup --capabilities "discovery,learning"
```
### Payload Validation
The SDK uses `Pydantic` to perform client-side validation on the `register` method's payload. This ensures that the data conforms to the ANS backend schema before it is sent, providing fast and clear error messages.
For example, if you try to register an agent without the required `name` field:
```python
# Invalid payload (missing 'name')
invalid_agent_data = {
"agent_id": "invalid-agent.ans",
"public_key": public_key
}
try:
client.register(invalid_agent_data, private_key)
except ValueError as e:
print(f"Validation failed as expected: {e}")
```
This will immediately raise a `ValueError` with a detailed message about the missing field, preventing an unnecessary API call.
### Key Management
The `generate_key_pair` method returns a new public/private key pair in PEM format. **The private key must be stored securely and should not be checked into version control.**
For production applications, use a secure secret management system like Google Secret Manager.
Raw data
{
"_id": null,
"home_page": "https://github.com/g-clouds/ANS/tree/main/sdk/sdk-python",
"name": "ans-project-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "ans, agent, sdk, cli, lookup, discovery, ai-agent",
"author": "gClouds R&D | gLabs",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/64/e0/0904d589a573a52f2407af7c04d39983b3ac8be7c8511504932ce0b3effe/ans_project_sdk-0.0.4.tar.gz",
"platform": null,
"description": "# ANS Python SDK\r\n\r\nPython SDK for interacting with the Agent Network System (ANS).\r\n\r\n## Installation\r\n\r\nInstall from PyPI:\r\n\r\n```bash\r\npip install ans-project-sdk\r\n```\r\n\r\n## Usage\r\n\r\n### ANSClient\r\n\r\nThe main entry point for the SDK is the `ANSClient` class.\r\n\r\n```python\r\nfrom ans_project.sdk import ANSClient\r\n\r\nclient = ANSClient() # Defaults to public ANS endpoint\r\n\r\n# Generate a new key pair\r\npublic_key, private_key = ANSClient.generate_key_pair()\r\n\r\n# Register an agent\r\nagent_data = {\r\n \"agent_id\": \"my-python-agent.ans\",\r\n \"name\": \"My Python Agent\",\r\n \"capabilities\": [\"python_sdk_test\"],\r\n \"public_key\": public_key\r\n}\r\ntry:\r\n response = client.register(agent_data, private_key)\r\n print(\"Registration successful:\", response)\r\nexcept Exception as e:\r\n print(\"Registration failed:\", e)\r\n\r\n\r\n# Lookup an agent\r\ntry:\r\n response = client.lookup({\"agent_id\": \"my-python-agent.ans\"})\r\n print(\"Lookup successful:\", response)\r\nexcept Exception as e:\r\n print(\"Lookup failed:\", e)\r\n```\r\n\r\n### anslookup CLI\r\n\r\nThe SDK includes a command-line interface tool, `anslookup`, for quickly querying the Agent Network System.\r\n\r\nTo use it, ensure the SDK is installed (e.g., `pip install ans-project-sdk`) \r\n\r\n```bash\r\n# Get help and see all options\r\nanslookup --help\r\n\r\n# Lookup an agent by its ID\r\nanslookup my-python-agent.ans\r\n\r\n# Lookup agents by name and trust level\r\nanslookup --query \"Nexus Voyager\" --trust-level \"provisional\"\r\n\r\n# Lookup agents by capabilities (use quotes for capabilities with spaces)\r\nanslookup --capabilities \"discovery,learning\"\r\n```\r\n\r\n### Payload Validation\r\n\r\nThe SDK uses `Pydantic` to perform client-side validation on the `register` method's payload. This ensures that the data conforms to the ANS backend schema before it is sent, providing fast and clear error messages.\r\n\r\nFor example, if you try to register an agent without the required `name` field:\r\n\r\n```python\r\n# Invalid payload (missing 'name')\r\ninvalid_agent_data = {\r\n \"agent_id\": \"invalid-agent.ans\",\r\n \"public_key\": public_key\r\n}\r\n\r\ntry:\r\n client.register(invalid_agent_data, private_key)\r\nexcept ValueError as e:\r\n print(f\"Validation failed as expected: {e}\")\r\n```\r\n\r\nThis will immediately raise a `ValueError` with a detailed message about the missing field, preventing an unnecessary API call.\r\n\r\n### Key Management\r\n\r\nThe `generate_key_pair` method returns a new public/private key pair in PEM format. **The private key must be stored securely and should not be checked into version control.**\r\n\r\nFor production applications, use a secure secret management system like Google Secret Manager.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Python SDK for the Agent Network System (ANS)",
"version": "0.0.4",
"project_urls": {
"Homepage": "https://github.com/g-clouds/ANS/tree/main/sdk/sdk-python"
},
"split_keywords": [
"ans",
" agent",
" sdk",
" cli",
" lookup",
" discovery",
" ai-agent"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e49d76b37a18c32fc8d451fa984e34a6b2ffa0d8fde63c5e1c56588729f32600",
"md5": "f904dbdea1a7ca0fbdfa0294def8f134",
"sha256": "13479b11fa583d6d72eb3f7b3a2c516d6d0817ba557591b3823ce3eeaf45bebc"
},
"downloads": -1,
"filename": "ans_project_sdk-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f904dbdea1a7ca0fbdfa0294def8f134",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 2710,
"upload_time": "2025-09-11T00:16:40",
"upload_time_iso_8601": "2025-09-11T00:16:40.266063Z",
"url": "https://files.pythonhosted.org/packages/e4/9d/76b37a18c32fc8d451fa984e34a6b2ffa0d8fde63c5e1c56588729f32600/ans_project_sdk-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "64e00904d589a573a52f2407af7c04d39983b3ac8be7c8511504932ce0b3effe",
"md5": "6fc76986ea8a4c6b35633ceb9d7238b6",
"sha256": "ffe79186dbb99a8a128f1b2bf61e2245cb45e79a3cf59e5416b894a1640f32eb"
},
"downloads": -1,
"filename": "ans_project_sdk-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "6fc76986ea8a4c6b35633ceb9d7238b6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 2928,
"upload_time": "2025-09-11T00:16:41",
"upload_time_iso_8601": "2025-09-11T00:16:41.354863Z",
"url": "https://files.pythonhosted.org/packages/64/e0/0904d589a573a52f2407af7c04d39983b3ac8be7c8511504932ce0b3effe/ans_project_sdk-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 00:16:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "g-clouds",
"github_project": "ANS",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ans-project-sdk"
}
JSON
