Custom Python SDK Quickstart

Enterprise agents, scoped to your org, governed by your policies.

Use this quickstart from LangChain, LlamaIndex, DSPy, notebooks, or an in-house Python orchestrator. The example mints an OIDC token with httpx, sends Authorization: Bearer <token> with x-faos-tenant-id, and invokes one tenant-scoped FAOS tool.

Back to Works Everywhere.

Step 1: Install

cd docs-site/examples/custom/py-sdk
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env

Fill in .env with the service-account credentials issued for the target tenant.

FAOS_BASE_URL=https://api.staging.faosx.ai
FAOS_CLIENT_ID=your-client-id
FAOS_CLIENT_SECRET=your-client-secret
FAOS_TENANT_ID=your-tenant-id

Step 2: Auth

The example uses OAuth 2.0 client credentials. FAOS_TENANT_ID is mandatory and becomes the x-faos-tenant-id header.

token_response = await client.post(
    f"{config.base_url}/oauth/token",
    data={
        "grant_type": "client_credentials",
        "client_id": config.client_id,
        "client_secret": config.client_secret,
        "audience": "faos-mcp",
    },
    headers={"x-faos-tenant-id": config.tenant_id},
)

Step 3: Invoke

Run the included minimal Python example:

python example.py

Every FAOS call carries bearer auth and tenant context:

headers = {
    "Authorization": f"Bearer {access_token}",
    "content-type": "application/json",
    "x-faos-tenant-id": config.tenant_id,
}

The runnable package lives at docs-site/examples/custom/py-sdk.

Troubleshooting

Auth failures

401 usually means the OIDC token mint failed, the secret is expired, or the token audience is wrong. 403 usually means the service account is valid but lacks access to the requested tenant or tool. Confirm both Authorization: Bearer <token> and x-faos-tenant-id are present; a missing or wrong tenant header is the most common cross-tenant leak misconfiguration.

TLS

If httpx or aiohttp raises TLS or certificate verification errors, upgrade certifi, verify your corporate proxy root CA is installed, and confirm FAOS_BASE_URL points to the expected staging or production hostname. Avoid disabling certificate verification in shared examples.

Rate limits

429 responses may include retry-after. Back off per tenant and tool invocation, preserve idempotency keys for retried writes, and do not retry with a different FAOS_TENANT_ID.

Production Notes

Pin faos-sdk by major and minor, keep Python at 3.11 or newer, and load tenant-specific credentials per deployment environment. Cross-tenant leakage is almost always tenant A credentials mixed with tenant B headers or a long-lived client reusing headers across requests.