基础用法
本页展示 SOVR SDK 的基础用法示例。
初始化客户端
首先需要初始化 SOVR 客户端。建议使用环境变量存储 API Key。
python
import os
from sovr_sdk import SOVRClient
# 从环境变量读取配置
client = SOVRClient(
base_url=os.getenv("SOVR_API_URL", "https://api.sovr.ai"),
api_key=os.getenv("SOVR_API_KEY")
)
# 验证连接
if client.is_connected:
print("✅ 连接成功")
else:
print("❌ 连接失败")typescript
import { SOVRClient } from '@sovr/sdk';
// 从环境变量读取配置
const client = new SOVRClient({
baseUrl: process.env.SOVR_API_URL || 'https://api.sovr.ai',
apiKey: process.env.SOVR_API_KEY
});
// 验证连接
const isConnected = await client.ping();
console.log(isConnected ? '✅ 连接成功' : '❌ 连接失败');创建决策
决策是 SOVR 中最基本的操作单元。以下示例展示如何创建不同类型的决策。
低风险决策
低风险决策通常不需要人工审批，可以直接执行。
python
# 创建低风险决策
decision = client.create_decision(
action="send_notification",
context={
"type": "email",
"recipient": "user@example.com",
"subject": "订单发货通知",
"body": "您的订单已发货，预计3天内送达。"
},
risk_level="low",
requires_approval=False
)
print(f"决策 ID: {decision.id}")
print(f"状态: {decision.status}") # 通常是 "approved" 或 "executed"typescript
// 创建低风险决策
const decision = await client.createDecision({
action: 'send_notification',
context: {
type: 'email',
recipient: 'user@example.com',
subject: '订单发货通知',
body: '您的订单已发货，预计3天内送达。'
},
riskLevel: 'low',
requiresApproval: false
});
console.log(`决策 ID: ${decision.id}`);
console.log(`状态: ${decision.status}`);高风险决策
高风险决策需要人工审批后才能执行。
python
# 创建高风险决策（需要审批）
decision = client.create_decision(
action="process_refund",
context={
"order_id": "ORD-12345",
"amount": 5000.00,
"reason": "客户申请退款",
"customer_id": "CUS-67890"
},
risk_level="high",
requires_approval=True
)
print(f"决策 ID: {decision.id}")
print(f"状态: {decision.status}") # "pending" - 等待审批
# 检查审批状态
if decision.status == "pending":
print("⏳ 等待人工审批...")typescript
// 创建高风险决策（需要审批）
const decision = await client.createDecision({
action: 'process_refund',
context: {
orderId: 'ORD-12345',
amount: 5000.00,
reason: '客户申请退款',
customerId: 'CUS-67890'
},
riskLevel: 'high',
requiresApproval: true
});
console.log(`决策 ID: ${decision.id}`);
console.log(`状态: ${decision.status}`); // "pending" - 等待审批
if (decision.status === 'pending') {
console.log('⏳ 等待人工审批...');
}查询决策状态
创建决策后，可以随时查询其状态。
python
# 获取单个决策
decision = client.get_decision("dec_xxxxxxxxxxxx")
print(f"状态: {decision.status}")
print(f"创建时间: {decision.created_at}")
# 列出最近的决策
decisions = client.list_decisions(limit=10)
for d in decisions:
print(f"[{d.status}] {d.action} - {d.id}")
# 按状态筛选
pending_decisions = client.list_decisions(
status="pending",
limit=20
)
print(f"待审批决策数量: {len(pending_decisions)}")typescript
// 获取单个决策
const decision = await client.getDecision('dec_xxxxxxxxxxxx');
console.log(`状态: ${decision.status}`);
console.log(`创建时间: ${decision.createdAt}`);
// 列出最近的决策
const decisions = await client.listDecisions({ limit: 10 });
for (const d of decisions) {
console.log(`[${d.status}] ${d.action} - ${d.id}`);
}
// 按状态筛选
const pendingDecisions = await client.listDecisions({
status: 'pending',
limit: 20
});
console.log(`待审批决策数量: ${pendingDecisions.length}`);错误处理
正确处理错误是构建健壮应用的关键。
python
from sovr_sdk.exceptions import (
SOVRError,
AuthenticationError,
ValidationError,
RateLimitError,
NotFoundError
)
try:
decision = client.create_decision(
action="send_email",
context={"to": "invalid-email"}, # 无效数据
risk_level="low"
)
except AuthenticationError as e:
print(f"认证失败: {e.message}")
# 检查 API Key 是否正确
except ValidationError as e:
print(f"参数验证失败: {e.message}")
print(f"错误字段: {e.field}")
except RateLimitError as e:
print(f"请求过于频繁，请在 {e.retry_after} 秒后重试")
except NotFoundError as e:
print(f"资源不存在: {e.message}")
except SOVRError as e:
print(f"SOVR 错误: {e.message}")typescript
import {
SOVRError,
AuthenticationError,
ValidationError,
RateLimitError,
NotFoundError
} from '@sovr/sdk';
try {
const decision = await client.createDecision({
action: 'send_email',
context: { to: 'invalid-email' }, // 无效数据
riskLevel: 'low'
});
} catch (error) {
if (error instanceof AuthenticationError) {
console.error(`认证失败: ${error.message}`);
} else if (error instanceof ValidationError) {
console.error(`参数验证失败: ${error.message}`);
console.error(`错误字段: ${error.field}`);
} else if (error instanceof RateLimitError) {
console.error(`请求过于频繁，请在 ${error.retryAfter} 秒后重试`);
} else if (error instanceof NotFoundError) {
console.error(`资源不存在: ${error.message}`);
} else if (error instanceof SOVRError) {
console.error(`SOVR 错误: ${error.message}`);
}
}下一步
了解基础用法后，您可以继续学习：