taiji-pda-v0/docs/API_INTEGRATION.md

API 集成说明

本文档说明如何在前端项目中使用后端 API 接口。

环境配置

在项目根目录创建 .env.local 文件（或使用 .env.example 作为模板）：

NEXT_PUBLIC_DATA_INGESTION_URL=http://localhost:8001
NEXT_PUBLIC_MCP_SERVER_URL=http://localhost:8000
NEXT_PUBLIC_API_GATEWAY_URL=http://localhost:80

API 客户端使用

导入 API 客户端

import { TaijiAPIClient } from "@/lib/api-client"

认证相关

登录

try {
  const result = await TaijiAPIClient.login("user@example.com", "password", "user")
  if (result.success) {
    // Token 已自动保存到 localStorage
    console.log("登录成功", result.data.user)
  }
} catch (error) {
  console.error("登录失败", error)
}

登出

await TaijiAPIClient.logout()
// Token 已自动清除

刷新 Token

await TaijiAPIClient.refreshToken()

用户侧平台 API

获取仪表板统计

const stats = await TaijiAPIClient.getUserDashboardStats()
console.log(stats.data.activeAgents)

部署 Agent

const result = await TaijiAPIClient.deployAgent({
  agentId: "agent-uuid",
  instances: 3,
  model: "gpt-4o-mini",
  gateway: "MCP"
})

创建工作流

const workflow = await TaijiAPIClient.createWorkflow({
  name: "订单处理流程",
  gateway: "MCP",
  nodes: [
    {
      agentId: "agent-1",
      agentType: "platform",
      agentName: "订单验证Agent",
      order: 1
    }
  ]
})

获取计费历史

const history = await TaijiAPIClient.getBillingHistory({
  startTime: "2025-01-01T00:00:00Z",
  endTime: "2025-01-31T23:59:59Z",
  page: 1,
  pageSize: 20
})

渠道合作伙伴 API

获取租户列表

const tenants = await TaijiAPIClient.getChannelTenants()

创建租户

const tenant = await TaijiAPIClient.createChannelTenant({
  name: "企业客户A",
  email: "contact@company-a.com",
  password: "securepass123",
  subscriptionTier: "enterprise"
})

分配租户资源

await TaijiAPIClient.allocateTenantResources("tenant-id", {
  agents: [
    { agentId: "agent-1", quantity: 10 }
  ],
  models: [
    { modelName: "gpt-4", rpm: 10000, tpm: 500000 }
  ],
  customAgentResources: {
    cpu: 2.0,
    memory: 4.0
  }
})

超级管理员 API

获取平台统计

const stats = await TaijiAPIClient.getAdminDashboardStats()

创建渠道

const channel = await TaijiAPIClient.createAdminChannel({
  name: "合作渠道A",
  email: "partner@channel-a.com",
  password: "channelpass123",
  commissionRate: 10.0
})

审批申请

await TaijiAPIClient.reviewApplication("application-id", true, "审批通过")

供应商管理 API

获取模型供应商列表

const providers = await TaijiAPIClient.getModelProviders()

创建模型供应商

const provider = await TaijiAPIClient.createModelProvider({
  name: "OpenAI",
  provider: "openai",
  apiUrl: "https://api.openai.com/v1",
  apiKey: "sk-xxxxx",
  supportedModels: ["gpt-4", "gpt-4o-mini"],
  rpm: 3500,
  tpm: 90000
})

Data Ingestion 服务 API

获取健康状态

const health = await TaijiAPIClient.getHealth()

同步 RapidAPI

await TaijiAPIClient.syncRapidAPI("weather", 100)

处理 APILLAMA

const result = await TaijiAPIClient.processAPILLAMA(
  { title: "Weather API", description: "Get weather" },
  { service: "Weather service" },
  "json_schema"
)

获取工具列表

const tools = await TaijiAPIClient.getTools("weather", 100, 0)

MCP Server API

注册 Agent

const agent = await TaijiAPIClient.registerAgent({
  name: "weather-agent",
  description: "Weather information agent",
  capabilities: ["weather_query"]
})

获取 Agent 列表

const agents = await TaijiAPIClient.getAgents(0, 100)

执行 Agent 工具

const result = await TaijiAPIClient.executeAgentTool("agent-id", {
  method: "tools/call",
  params: {
    tool: { name: "math_add", function_name: "math_add" },
    arguments: { a: 10, b: 20 }
  }
})

WebSocket 连接

const ws = TaijiAPIClient.createAgentWebSocket("agent-id")

ws.onopen = () => {
  console.log("WebSocket connected")
  ws.send(JSON.stringify({
    type: "mcp_request",
    payload: {
      method: "tools/list",
      params: {}
    }
  }))
}

ws.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log("Received:", data)
}

错误处理

所有 API 方法都会抛出错误，建议使用 try-catch 处理：

try {
  const result = await TaijiAPIClient.getUserDashboardStats()
  // 处理成功结果
} catch (error: any) {
  console.error("API Error:", error.message)
  // 显示错误提示给用户
}

认证 Token 管理

API 客户端会自动管理认证 Token：

• 登录时: Token 自动保存到 localStorage
• 请求时: Token 自动添加到请求头 Authorization: Bearer <token>
• 登出时: Token 自动清除

如果需要手动获取 Token：

const token = localStorage.getItem("auth_token")

API Key 认证

除了 JWT Token，还支持 API Key 认证：

// 设置 API Key
localStorage.setItem("api_key", "sk-xxxxx")

// API 客户端会自动使用 API Key
const result = await TaijiAPIClient.getUserDashboardStats()

注意事项

1. 环境变量: 确保设置了正确的 API 端点 URL
2. CORS: 开发环境需要后端配置 CORS 允许前端域名
3. 错误处理: 所有 API 调用都应该有错误处理
4. Token 过期: 如果 Token 过期，需要重新登录或刷新 Token
5. 类型安全: API 客户端使用 TypeScript，建议启用类型检查

相关文档

• 后端 API 接口文档: /tools/taiji-AI-PAD/Docs/前后端调试说明/API接口文档.md
• 后端需求文档: /tools/taiji-pad-v0/docs/backend-api-requirements.md