AGNS Python SDK

A lightweight Python SDK for interacting with the Agent Name Service (AGNS). This library allows you to look up and communicate with language agents via a clean and simple interface.

Installation

Install the latest version from PyPI:

pip install agns

For local development:

git clone https://github.com/coffer-id/agent-platform.git
cd agns
pip install -e .

Authentication

Some AGNS endpoints and agent selection features require authentication using API keys. You can provide your keys in one of two ways:

1. Using a .env file (recommended)

Create a file named .env in your project root and add:

AGNS_API_KEY=your_agns_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

AGNS_API_KEY is required for authenticating with the Agent Name Service (AGNS) endpoints.

ANTHROPIC_API_KEY is required if you use agent selection or routing features that leverage Anthropic's Claude models (e.g., for LLM-based agent selection). This key is provided by Anthropic and enables access to their API for model inference.

The SDK will automatically load this file if you have the python-dotenv package installed (already used in the SDK).

2. Setting the environment variables directly

export AGNS_API_KEY=your_agns_api_key_here
export ANTHROPIC_API_KEY=your_anthropic_api_key_here

You can obtain these API keys from your AGNS administrator/service provider and from Anthropic, respectively. The SDK will automatically use these environment variables when making authenticated requests.

Usage Example

from agns import agns

# Lookup all available agents
result = agns.lookup()

# Choose an agent to ask a question
if isinstance(result, dict):
    agent = next(iter(result.values()), None)
elif result:
    agent = result
else:
    raise RuntimeError("No agent found.")

# Ask the agent something
question = {"text": "Hello", "target_language": "es"}
response = agent.ask(question)

print("Translated:", response["translated_text"])

API Overview

lookup(name: Optional[str] = None) → dict[str, Agent] | Agent | None

Looks up agents by name, or returns all if no name is provided.

• If name is provided: returns a single Agent or None
• If not: returns a dictionary of agents keyed by name

Running Tests

Install development dependencies:

pip install -r requirements-dev.txt

Run tests using pytest:

pytest

Project Structure

src/
  agns/
    __init__.py
    client.py
    agent.py
    agent_card.py
tests/
  test_integration.py
pyproject.toml
README.md

License

MIT License. See LICENSE for details.

Contributing

Contributions are welcome! Please:

1. Fork this repository
2. Create a feature branch
3. Commit your changes
4. Open a pull request