Python SDK

import os

import requests

api_key = os.environ.get("THREETONE_API_KEY")
if not api_key or not api_key.strip():
    raise RuntimeError("Set THREETONE_API_KEY in your server environment.")


def list_agents(cursor=None):
    params = {"page_size": 20}
    if cursor is not None:
        params["cursor"] = cursor

    try:
        response = requests.get(
            "https://api.threetone.in/v1/convai/agents",
            headers={"x-api-key": api_key},
            params=params,
            timeout=(5, 30),
            allow_redirects=False,
        )
    except requests.RequestException:
        raise RuntimeError(
            "GET /v1/convai/agents failed before a usable response arrived."
        ) from None

    request_id = response.headers.get("X-Request-Id", "unavailable")[:128]
    context = (
        f"GET /v1/convai/agents status={response.status_code} "
        f"request_id={request_id!r}"
    )
    if response.status_code != 200:
        raise RuntimeError(context)

    try:
        page = response.json()
    except ValueError:
        raise RuntimeError(f"Invalid JSON; {context}") from None

    if not isinstance(page, dict) or not isinstance(page.get("agents"), list):
        raise RuntimeError(f"Invalid agents response; {context}")
    if type(page.get("has_more")) is not bool:
        raise RuntimeError(f"Invalid pagination response; {context}")
    next_cursor = page.get("next_cursor")
    if next_cursor is not None and not isinstance(next_cursor, str):
        raise RuntimeError(f"Invalid cursor; {context}")
    if page["has_more"] and not next_cursor:
        raise RuntimeError(f"Missing next cursor; {context}")
    for agent in page["agents"]:
        if (
            not isinstance(agent, dict)
            or not isinstance(agent.get("agent_id"), str)
            or not isinstance(agent.get("name"), str)
        ):
            raise RuntimeError(f"Invalid agent entry; {context}")

    return page["agents"], page["has_more"], next_cursor


agents, has_more, next_cursor = list_agents()
for agent in agents:
    print(agent["agent_id"], agent["name"])
print("More agents available:", has_more)