Parloa Python SDK

Official Python client for the Parloa API.

Installation

pip install parloa

Usage

Authenticate with Parloa.token_provider(). It caches OAuth tokens and refreshes them before expiry, so you pass the provider to any client that needs auth. Omit base_url to let the SDK resolve the correct API gateway per API group; pass base_url only if you want every sub-client pinned to one gateway (see Automatic base URL resolution).

from parloa import Parloa

CLIENT_ID = "client_01HZX9YQK0V4N4G9Z8B7Q1T2C3"
CLIENT_SECRET = "client_secret"
AGENT_ID = "agt_01HZX9YQK0V4N4G9Z8B7Q1T2C3"

provider = Parloa.token_provider(
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
)

client = Parloa(token=provider)
skills = client.skills.list(agent_id=AGENT_ID)
print(skills.data[0].name)

simulations = client.simulations.list_definitions(agent_id=AGENT_ID)
print(simulations.items[0].name)

Async usage follows the same pattern with AsyncParloa:

import asyncio

from parloa import AsyncParloa

async def main() -> None:
    provider = AsyncParloa.token_provider(
        client_id="client_01HZX9YQK0V4N4G9Z8B7Q1T2C3",
        client_secret="client_secret",
    )
    client = AsyncParloa(token=provider)
    skills = await client.skills.list(agent_id="agt_01HZX9YQK0V4N4G9Z8B7Q1T2C3")
    print(skills.data[0].name)

asyncio.run(main())

Automatic base URL resolution

By default, when you omit base_url, the SDK resolves the correct API gateway for each API group before sending a request. You can also force this on with resolve_base_url_automatically=True even when a base_url is set (useful when base_url points at the default API gateway but sub-clients should route to tenant-specific gateways).

# No base_url — resolution is on by default
client = Parloa(token=provider)
agents = client.agents.list()

# Explicit opt-out: pin every sub-client to one gateway
client = Parloa(base_url="https://runtime.example.com", token=provider)

What happens on each request

1. You access a sub-client, for example client.agents.
2. Before the HTTP request is sent, an httpx event hook looks up your URL map — from an in-memory cache when available, otherwise from the tenant URLs API (GET /v0/urls).
3. The hook looks up the tag for that sub-client (e.g. agents) and rewrites the request host to the tenant URL.
4. The actual API call goes to the resolved gateway.

Tenant URLs are cached for one hour, so later calls to the same process reuse the map without another /v0/urls round trip.

@startuml
actor User
participant "Parloa" as Client
participant "__getattribute__" as GetAttr
participant "Tenant URLs\n(/v0/urls)" as TenantUrls
participant "Agents API" as Agents

User -> Client : agents.list()
Client -> GetAttr : access client.agents
GetAttr -> Client : build AgentsClient\n(with URL resolver hook)
Client -> TenantUrls : GET /v0/urls\n(cached after first call)
TenantUrls --> Client : {"agents": "https://runtime.example.com", ...}
Client -> Agents : GET /v0/agents\n(host rewritten)
Agents --> Client : response
Client --> User : agents
@enduml

The tenant_urls sub-client is excluded from this rewrite — it must always hit the default API gateway to fetch the map.

Why __getattribute__ is involved

BaseClient is generated by the Fern SDK from the OpenAPI spec. It defines sub-clients like agents and oauth as ordinary @property methods, each sharing a single httpx client and one fixed base_url. We can't change those property implementations directly, so Parloa overrides __getattribute__ to intercept access to registered sub-clients. When you write client.agents:

1. Python calls Parloa.__getattribute__("agents").
2. The handler walks the class hierarchy, finds the agents property on BaseClient, and looks it up in _BASE_CLIENT_PROPERTY_CLIENTS.
3. It calls _create_client_wrapper("agents"), which attaches a per-tag URL resolver, then instantiates AgentsClient with that wrapper.
4. The sub-client is cached on _agents so this setup runs only once.

Inside the handler, reads and writes use object.__getattribute__ and object.__setattr__ instead of normal attribute access. That avoids infinite recursion: a plain self._agents inside __getattribute__ would call __getattribute__ again.

This acts as a guard when a new SDK version is generated: if Fern adds a sub-client to BaseClient but nobody registers it in _BASE_CLIENT_PROPERTY_CLIENTS, accessing it raises AttributeError with a message asking you to add it to the registry. That covers the common case of new @property sub-clients, but if Fern changes the SDK shape in a bigger way — for example, replacing properties with a different access pattern — the override logic itself may need to be updated.

Tests

• Registry coverage — tests/sdk/test_client_registry.py parametrizes over every @property on BaseClient / AsyncBaseClient and checks that Parloa / AsyncParloa can construct it. This catches sub-clients that Fern added but nobody wired into the override registry.
• Missing URL groups — tests/sdk/test_base_url_rerouting.py includes test_missing_url_group_raises_key_error (and the async variant). If /v0/urls returns a map without the tag a sub-client needs (e.g. agents), the SDK raises KeyError with a clear message instead of sending the request to the wrong host.

See demo/README.md for a live walkthrough with debug logging against a compiled wheel.