API 参考

Alius Agent Team 提供完整的 REST API，支持与系统进行程序化交互。本文档详细介绍所有 API 端点、请求参数和响应格式。

API 概览

基础信息

• 基础 URL：https://api.alius.ai/v1
• API 版本：v1
• 协议：HTTPS 仅
• 数据格式：JSON
• 字符编码：UTF-8

认证方式

API 支持以下认证方式：

Bearer Token

在请求头中添加 Authorization 字段：

Authorization: Bearer YOUR_API_TOKEN

API Key

在请求头中添加 X-API-Key 字段：

X-API-Key: YOUR_API_KEY

速率限制

API 实施速率限制以确保系统稳定：

• 默认限制：每分钟 60 次请求
• 批量操作：每分钟 10 次请求
• 响应头中包含速率限制信息：
  • X-RateLimit-Limit：速率限制
  • X-RateLimit-Remaining：剩余请求次数
  • X-RateLimit-Reset：速率限制重置时间

错误处理

API 使用标准 HTTP 状态码表示请求结果：

成功状态码

• 200 OK：请求成功
• 201 Created：资源创建成功
• 202 Accepted：请求已接受，正在处理
• 204 No Content：请求成功，无返回内容

客户端错误状态码

• 400 Bad Request：请求参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：无权限
• 404 Not Found：资源不存在
• 409 Conflict：资源冲突
• 422 Unprocessable Entity：请求格式正确但语义错误
• 429 Too Many Requests：请求过于频繁

服务端错误状态码

• 500 Internal Server Error：服务器内部错误
• 502 Bad Gateway：网关错误
• 503 Service Unavailable：服务不可用
• 504 Gateway Timeout：网关超时

错误响应格式

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "请求参数错误",
    "details": {
      "field": "email",
      "issue": "无效的邮箱格式"
    }
  }
}

认证 API

短信登录

端点：POST /auth/login/sms

描述：使用短信验证码登录

请求体：

{
  "phone": "+8613800138000",
  "code": "123456"
}

响应：

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 3600,
    "user": {
      "id": "user_12345",
      "username": "example_user",
      "email": "user@example.com"
    }
  }
}

发送短信验证码

端点：POST /auth/sms/send

描述：发送短信验证码

请求体：

{
  "phone": "+8613800138000"
}

响应：

{
  "success": true,
  "data": {
    "expiresIn": 300,
    "requestId": "req_12345"
  }
}

Apple 登录

端点：POST /auth/login/apple

描述：使用 Apple ID 登录

请求体：

{
  "identityToken": "apple_identity_token",
  "authorizationCode": "apple_auth_code",
  "user": {
    "email": "user@example.com",
    "name": "Example User"
  }
}

微信登录

端点：POST /auth/login/wechat

描述：使用微信登录

请求体：

{
  "code": "wechat_auth_code"
}

刷新令牌

端点：POST /auth/refresh

描述：使用刷新令牌获取新的访问令牌

请求体：

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

退出登录

端点：POST /auth/logout

描述：退出登录，使令牌失效

请求体：

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Agent API

列出 Agent

端点：GET /agents

描述：获取 Agent 列表

查询参数：

响应：

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "agent_12345",
        "name": "My Code Assistant",
        "description": "专门用于代码生成和审查的 Agent",
        "type": "codegen",
        "status": "active",
        "health": {
          "score": 95,
          "lastCheck": "2024-01-15T10:00:00Z"
        },
        "config": {
          "model": "gpt-4",
          "temperature": 0.2,
          "maxTokens": 4096
        },
        "createdAt": "2024-01-01T00:00:00Z",
        "updatedAt": "2024-01-15T10:00:00Z",
        "ownerId": "user_12345",
        "teamId": "team_12345"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 45,
      "totalPages": 3
    }
  }
}

创建 Agent

端点：POST /agents

描述：创建新的 Agent

请求体：

{
  "name": "My Code Assistant",
  "description": "专门用于代码生成和审查的 Agent",
  "type": "codegen",
  "config": {
    "model": "gpt-4",
    "temperature": 0.2,
    "maxTokens": 4096
  },
  "teamId": "team_12345"
}

响应：

{
  "success": true,
  "data": {
    "id": "agent_12345",
    "name": "My Code Assistant",
    "status": "inactive",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

获取 Agent 详情

端点：GET /agents/:id

描述：获取指定 Agent 的详细信息

路径参数：

响应：与列出 Agent 的单个 Agent 对象相同

更新 Agent

端点：PUT /agents/:id

描述：更新 Agent 信息

路径参数：

请求体：

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "config": {
    "temperature": 0.3
  }
}

删除 Agent

端点：DELETE /agents/:id

描述：删除 Agent

路径参数：

启动 Agent

端点：POST /agents/:id/actions/start

描述：启动 Agent

路径参数：

停止 Agent

端点：POST /agents/:id/actions/stop

描述：停止 Agent

重启 Agent

端点：POST /agents/:id/actions/restart

描述：重启 Agent

获取 Agent 日志

端点：GET /agents/:id/logs

描述：获取 Agent 的执行日志

查询参数：

Task API

列出任务

端点：GET /tasks

描述：获取任务列表

查询参数：

创建任务

端点：POST /tasks

描述：创建新任务

请求体：

{
  "title": "代码审查",
  "description": "审查以下 Pull Request 的代码质量",
  "agentId": "agent_12345",
  "priority": "high",
  "deadline": "2024-01-20T17:00:00Z",
  "attachments": [
    {
      "type": "url",
      "url": "https://github.com/example/repo/pull/123"
    }
  ]
}

获取任务详情

端点：GET /tasks/:id

描述：获取指定任务的详细信息

更新任务

端点：PUT /tasks/:id

描述：更新任务信息

删除任务

端点：DELETE /tasks/:id

描述：删除任务

取消任务

端点：POST /tasks/:id/actions/cancel

描述：取消任务

重试任务

端点：POST /tasks/:id/actions/retry

描述：重试失败的任务

获取任务结果

端点：GET /tasks/:id/result

描述：获取任务执行结果

Team API

列出团队

端点：GET /teams

描述：获取用户所属的团队列表

创建团队

端点：POST /teams

描述：创建新团队

请求体：

{
  "name": "My Team",
  "description": "这是我的团队",
  "visibility": "private"
}

获取团队详情

端点：GET /teams/:id

描述：获取指定团队的详细信息

更新团队

端点：PUT /teams/:id

描述：更新团队信息

删除团队

端点：DELETE /teams/:id

描述：删除团队

邀请成员

端点：POST /teams/:id/members/invite

描述：邀请用户加入团队

请求体：

{
  "email": "user@example.com",
  "role": "member"
}

移除成员

端点：DELETE /teams/:id/members/:userId

描述：移除团队成员

更新成员角色

端点：PUT /teams/:id/members/:userId/role

描述：更新团队成员角色

请求体：

{
  "role": "admin"
}

User API

获取当前用户信息

端点：GET /users/me

描述：获取当前认证用户的信息

更新用户信息

端点：PUT /users/me

描述：更新当前用户信息

获取用户列表（团队）

端点：GET /teams/:teamId/users

描述：获取团队成员列表（需要团队管理员权限）

Notification API

列出通知

端点：GET /notifications

描述：获取通知列表

查询参数：

标记通知为已读

端点：PUT /notifications/:id/read

描述：标记指定通知为已读

标记所有通知为已读

端点：PUT /notifications/read-all

描述：标记所有通知为已读

删除通知

端点：DELETE /notifications/:id

描述：删除指定通知

Session API

列出会话

端点：GET /sessions

描述：获取会话列表

获取会话详情

端点：GET /sessions/:id

描述：获取指定会话的详细信息

关闭会话

端点：POST /sessions/:id/actions/close

描述：关闭指定会话

Webhook

Webhook 事件

Alius Agent Team 支持 Webhook，可以在特定事件发生时发送 HTTP POST 请求到您指定的 URL。

支持的事件类型

• agent.created：Agent 创建
• agent.updated：Agent 更新
• agent.deleted：Agent 删除
• agent.status_changed：Agent 状态变更
• task.created：任务创建
• task.updated：任务更新
• task.completed：任务完成
• task.failed：任务失败
• team.member_joined：成员加入团队
• team.member_left：成员离开团队

Webhook 负载示例

{
  "event": "task.completed",
  "data": {
    "taskId": "task_12345",
    "agentId": "agent_12345",
    "status": "completed",
    "result": {
      "output": "任务执行结果..."
    }
  },
  "timestamp": "2024-01-15T10:30:00Z",
  "signature": "webhook_signature"
}

配置 Webhook

端点：POST /webhooks

描述：创建 Webhook 配置

请求体：

{
  "url": "https://your-server.com/webhook",
  "events": ["task.completed", "agent.status_changed"],
  "secret": "your_webhook_secret"
}

SDK 和示例

官方 SDK

Alius Agent Team 提供以下官方 SDK：

• JavaScript/TypeScript：@alius/agent-team-sdk
• Python：alius-agent-team-sdk
• Go：github.com/alius/agent-team-sdk-go
• Java：com.alius.agent-team-sdk

JavaScript SDK 示例

安装

npm install @alius/agent-team-sdk

使用示例

import { AliusClient } from '@alius/agent-team-sdk';

// 初始化客户端
const client = new AliusClient({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://api.alius.ai/v1'
});

// 列出 Agent
const agents = await client.agents.list({
  status: 'active',
  limit: 10
});

console.log(agents);

// 创建任务
const task = await client.tasks.create({
  title: '代码审查',
  description: '审查 PR #123',
  agentId: 'agent_12345',
  priority: 'high'
});

console.log(task);

// 监听 Webhook 事件
client.webhooks.on('task.completed', (data) => {
  console.log('Task completed:', data);
});

Python SDK 示例

安装

pip install alius-agent-team-sdk

使用示例

from alius_agent_team import AliusClient

# 初始化客户端
client = AliusClient(api_key="YOUR_API_KEY")

# 列出 Agent
agents = client.agents.list(status="active", limit=10)
print(agents)

# 创建任务
task = client.tasks.create(
    title="代码审查",
    description="审查 PR #123",
    agent_id="agent_12345",
    priority="high"
)
print(task)

# 获取任务结果
result = client.tasks.get_result(task.id)
print(result)

最佳实践

API 调用优化

• 使用分页：对于大量数据的请求，使用分页避免超时
• 批量操作：使用批量 API 减少请求次数
• 缓存响应：缓存不经常变更的数据
• 使用 Webhook：对于实时性要求高的场景，使用 Webhook 而非轮询

错误处理

• 实现重试逻辑：对于可恢复的错误（如 429、503），实施指数退避重试
• 记录错误：记录所有 API 错误，便于排查问题
• 用户友好提示：向用户展示友好的错误提示

安全

• 保护 API 密钥：不要在前端代码中硬编码 API 密钥
• 使用最低权限：只请求必要的权限
• 验证 Webhook 签名：验证 Webhook 请求的签名，确保来源可信

更新日志

v1.0.0 (2024-01-01)

• 初始 API 版本发布
• 支持基本的 Agent、Task、Team 管理
• 支持短信、Apple、微信登录

v1.1.0 (2024-02-15)

• 新增 Session API
• 新增 Webhook 支持
• 改进错误处理

v1.2.0 (2024-03-30)

• 新增批量操作 API
• 新增高级搜索功能
• 性能优化

总结

Alius Agent Team API 提供了完整的程序化访问能力，支持各种集成和自动化场景。如果您有任何 API 相关的问题或建议，请随时联系我们的技术支持团队。

详细的错误代码列表、更高级的用法示例以及最新的 API 更新，请访问我们的开发者门户：https://developers.alius.ai