> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# Python SDK

> Alephant Python SDK 的安装、配置和使用

官方 Alephant Python SDK 让 Python 应用程序能够访问 Alephant SaaS API。它同时支持同步和异步使用，并提供完整的类型提示。

## 安装

通过 pip 安装 SDK：

```bash
pip install alephantai-saas-api
```

## 初始化

您可以根据应用程序架构初始化同步或异步客户端。

### 同步客户端

```python
import os
from alephantai_saas import AlephantAi318537Api

client = AlephantAi318537Api(
    base_url=os.environ["ALEPHANT_SAAS_BASE_URL"],
    api_key=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
)
```

### 异步客户端

适用于 FastAPI 或 Starlette 等现代异步框架：

```python
import os
from alephantai_saas import AsyncAlephantAi318537Api

async_client = AsyncAlephantAi318537Api(
    base_url=os.environ["ALEPHANT_SAAS_BASE_URL"],
    api_key=f"Bearer {os.environ['ALEPHANT_API_TOKEN']}",
)
```

## 使用示例

### 冒烟测试

使用 health 端点验证 SDK 能否连接到已配置的 SaaS API 主机。

```python
response = client.system.health_check()
print(response)
```

### 列出工作区

```python
def fetch_workspaces():
    try:
        response = client.workspaces.list_users_workspaces()
        for workspace in response.data:
            print(f"Workspace: {workspace.name} (ID: {workspace.id})")
    except Exception as e:
        print(f"Error fetching workspaces: {e}")
```

### 获取 Agent 分析数据

```python
async def get_agent_metrics(agent_id: str):
    analytics = await async_client.analytics.get_agent_analytics(
        agent_id=agent_id,
        period="7d"
    )
    print(f"Total Cost: ${analytics.total_cost}")
    print(f"Total Requests: {analytics.total_requests}")
```

## 基础 URL

SaaS SDK 需要显式指定 `base_url`。请根据您的环境使用开发、生产或私有化部署主机。

```python
client = AlephantAi318537Api(
    base_url="https://alephant.your-company.com/api",
    api_key="Bearer <token>",
)
```