Configuration is the credentials object every SDK module accepts. By default each module instantiates its own Configuration from environment variables, so most code never touches it directly. Construct one explicitly when you need to override credentials or point at a self-hosted controller.
from xpander_sdk import Configuration
config = Configuration(
api_key="your-api-key",
organization_id="your-org-id",
)
Constructor
Configuration(
api_key: Optional[str] = None, # XPANDER_API_KEY
base_url: Optional[str] = None, # XPANDER_BASE_URL
organization_id: Optional[str] = None, # XPANDER_ORGANIZATION_ID
agent_id: Optional[str] = None, # XPANDER_AGENT_ID
)
Attributes
| Attribute | Type | Default | Description |
|---|
api_key | str | None | XPANDER_API_KEY env var | API key for authentication. Required for any cloud call. |
organization_id | str | None | XPANDER_ORGANIZATION_ID env var | Organization identifier. Required for self-hosted controllers; optional but recommended for cloud. |
base_url | str | None | Auto-detected from env | API endpoint. Defaults to https://inbound.xpander.ai for cloud. Set to your Agent Controller URL for self-hosted. |
agent_id | str | None | None | Optional default agent ID. When set, methods that take agent_id can be called without arguments. Falls back to XPANDER_AGENT_ID. |
Environment variables
The SDK reads these on import. Setting them once via .env or your shell removes the need to construct Configuration manually.
| Variable | Purpose |
|---|
XPANDER_API_KEY | API key. Required. |
XPANDER_ORGANIZATION_ID | Organization ID. Required for self-hosted; recommended for cloud. |
XPANDER_BASE_URL | Override the API base URL. |
XPANDER_AGENT_ID | Default agent ID. Lets Backend(), Events(), and Agents().aget() work without an explicit ID. |
from dotenv import load_dotenv
from xpander_sdk import Configuration
load_dotenv()
config = Configuration() # picks up XPANDER_* vars
Methods
get_full_url() -> str
Returns the API URL, with the organization ID appended when the controller requires it.
config = Configuration(
base_url="https://agent-controller.acme.com",
organization_id="org_123",
)
config.get_full_url()
# 'https://agent-controller.acme.com/org_123'
config = Configuration(
base_url="https://inbound.xpander.ai",
organization_id="org_123",
)
config.get_full_url()
# 'https://inbound.xpander.ai' (cloud: no prefix)
base_url contains agent-controller or port 9016. You don’t need to do this yourself.
Self-hosted
Use the Agent Controller API key generated during your Helm install (not your cloud API key) and point base_url at the controller:
config = Configuration(
api_key="agent-controller-api-key",
organization_id="your-org-id",
base_url="https://agent-controller.your-company.com",
)
export XPANDER_API_KEY="agent-controller-api-key"
export XPANDER_ORGANIZATION_ID="your-org-id"
export XPANDER_BASE_URL="https://agent-controller.your-company.com"
The base_url must point at the Agent Controller endpoint (e.g. https://agent-controller.{your-domain}), not the root domain. The SDK detects this URL pattern and prefixes paths with the organization ID via get_full_url().
Sharing config across modules
Pass the same Configuration to every module so they hit the same endpoint and use the same credentials:
from xpander_sdk import Configuration, Agents, Tasks, KnowledgeBases
config = Configuration(api_key="...", organization_id="...")
agents = Agents(configuration=config)
tasks = Tasks(configuration=config)
kbs = KnowledgeBases(configuration=config)
Agent, Task, KnowledgeBase) carry the Configuration they were loaded with, so subsequent method calls on them reuse it automatically.
