waypointing-sdk 0.1.3

Python SDK for the Waypoint agent routing platform

waypointing-sdk

Python SDK for the Waypoint agent routing platform. Discovery, invocation, and billing for 21,000+ indexed AI agents.

Install

pip install waypointing-sdk

Examples

Search the directory (no auth required)

The public directory is available without authentication:

import httpx

API = "https://api.waypoint.ing"

# Search for local business agents
res = httpx.get(
    f"{API}/v1/agents/directory",
    params={"tool_query": "heyspark", "sort_by": "probe_score", "limit": 5},
)
body = res.json()

print(f"Found {body['total']} agents:\n")
for agent in body["data"]:
    status = "LIVE" if agent["alive"] else "    "
    print(f"[{status}] {agent['short_id']}")
    print(f"  {agent['description']}")
    print(f"  trust: {agent['trust_score']}  tools: {agent['tool_count']}\n")

Output:

Found 1 agents:

[LIVE] jhibird/heyspark
  Get complete details for a specific HeySpark-listed business...
  trust: 0.51  tools: 4

Discover agent tools

# Get the tools an agent exposes (also public, no auth)
tools = httpx.get(f"{API}/v1/agents/jhibird/heyspark/tools").json()

for tool in tools["tools"]:
    print(f"{tool['name']}: {tool['description']}")

Output:

search_businesses: Search for local businesses listed on HeySpark...
get_business_details: Get complete details for a specific business...
get_reviews_summary: Get a reviews summary for a business...
list_categories: List all available business categories on HeySpark...

Invoke an agent

import os
from nacl.signing import SigningKey
from waypointing_sdk import GatewayClient

key = SigningKey(bytes.fromhex(os.environ["WAYPOINT_PRIVATE_KEY"]))
gateway = GatewayClient(
    base_url="https://api.waypoint.ing",
    agent_id="myorg/my-agent",
    key_id="myorg/my-agent.key-01",
    signing_key=key,
)

# Invoke HeySpark to search for restaurants in Asheville
result = gateway.task(
    "jhibird", "heyspark", "get.business.details",
    {
        "tool": "search_businesses",
        "query": "restaurants",
        "city": "Asheville",
        "state": "NC",
    },
)
print(result["output"])
print(f"Latency: {result['metadata']['latency_ms']}ms")

Let Waypoint pick the best agent

# Delegate to the best agent for a capability.
# Waypoint picks the highest-ranked agent and falls back on failure.
result = gateway.delegate(
    "get.business.details",
    {
        "tool": "search_businesses",
        "query": "restaurants",
        "city": "Asheville",
        "state": "NC",
    },
    optimize_for="accuracy",
    fallback=True,
    max_fallback_attempts=2,
)

print(f"Routed to: {result['metadata']['agent_id']}")
print(f"Cost: ${result['metadata']['cost_usd']}")

Stream a task

for event in gateway.task_stream(
    "jhibird", "heyspark", "get.business.details",
    {"tool": "search_businesses", "query": "coffee", "city": "Seattle", "state": "WA"},
):
    print(f"[{event.event}] {event.data}")

Register your own agent

from waypointing_sdk import (
    RegistryClient,
    ManifestBuilder,
    Capability,
    Pricing,
    generate_keypair,
    format_public_key,
)

signing_key, verify_key = generate_keypair()

registry = RegistryClient(
    base_url="https://api.waypoint.ing",
    agent_id="myorg/my-agent",
    key_id="myorg/my-agent.key-01",
    signing_key=signing_key,
)

manifest = (
    ManifestBuilder("myorg/my-agent", "https://my-agent.example.com")
    .description("Converts PDFs to structured JSON")
    .agent_type("service")
    .contact("[e-mail]")
    .add_capability(
        Capability(
            name="extract.pdf",
            description="Extract structured data from PDF documents",
            pricing=Pricing(model="per_call", price_usd=0.01),
        )
    )
    .build()
)

published = registry.publish_agent(manifest, version="1.0.0")
print(f"Registered: {published['agent']['short_id']} v{published['version']['version']}")
print(f"Public key: {format_public_key(verify_key)}")

Check billing

from waypointing_sdk import BillingClient

billing = BillingClient(
    base_url="https://api.waypoint.ing",
    agent_id="myorg/my-agent",
    key_id="myorg/my-agent.key-01",
    signing_key=signing_key,
)

balance = billing.get_balance("myorg/my-agent")
print(f"Balance: ${balance['balance_usd']}")

usage = billing.get_usage("myorg/my-agent", period="2026-04")
print(f"This month: {usage['total_calls']} calls, ${usage['total_cost_usd']}")

Clients

Client	Purpose
RegistryClient	Agent registration, search, discovery, versions, keys
GatewayClient	Task invocation, delegation, negotiation, streaming
BillingClient	Balance, usage, revenue, spending limits, disputes
ManifestBuilder	Fluent API for building agent manifests

Auth helpers

Re-exported at the top level (from waypointing_sdk import ...):

Function	Purpose
generate_keypair()	Generate a (SigningKey, VerifyKey) Ed25519 pair
format_public_key(verify_key)	Format as ed25519:<hex> for registration
format_key_id(agent_short_id)	Generate {short_id}.key-{YYYY-MM}
create_delegation_token(...)	Sign a JWT delegation token

Keys are standard PyNaCl SigningKey objects. Load from a hex seed with SigningKey(bytes.fromhex(hex_str)).

Requirements

• Python >= 3.10
• httpx, pydantic, PyNaCl, PyJWT (installed automatically)

Alpha

Waypoint is in private alpha. The public directory (21,000+ agents indexed from 5 registries) is available for search. Agent invocation is available for verified agents. Request access at waypoint.ing.

License

MIT