API参照

Alius Agent Teamは、システムとのプログラム的なインタラクションをサポートする完全なREST APIを提供します。このドキュメントでは、すべてのAPIエンドポイント、要求パラメータ、応答形式について詳細に説明します。

API概要

基本情報

  • 基本URL：https://api.alius.ai/v1
  • APIバージョン：v1
  • プロトコル：HTTPSのみ
  • データ形式：JSON
  • 文字エンコーディング：UTF-8

認証方式

APIは、以下の認証方式をサポート：

Bearerトークン

要求ヘッダーにAuthorizationフィールドを追加：

Authorization: Bearer YOUR_API_TOKEN

APIキー

要求ヘッダーに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

SMSログイン

エンドポイント：POST /auth/login/sms

説明：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"
    }
  }
}

SMS認証コード送信

エンドポイント：POST /auth/sms/send

説明：SMS認証コードを送信

要求本体：

{
  "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"
  }
}

WeChatログイン

エンドポイント：POST /auth/login/wechat

説明：WeChatでログイン

要求本体：

{
  "code": "wechat_auth_code"
}

トークンリフレッシュ

エンドポイント：POST /auth/refresh

説明：リフレッシュトークンで新しいアクセストークンを取得

要求本体：

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

ログアウト

エンドポイント：POST /auth/logout

説明：ログアウト、トークンを無効化

要求本体：

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

Agent API

エージェントリスト

エンドポイント：GET /agents

説明：エージェントリストを取得

照会パラメータ：

パラメータタイプ必須説明
pagenumberいいえページ番号、デフォルト1
limitnumberいいえページあたり数量、デフォルト20、最大100
statusstringいいえステータスでフィルタ
typestringいいえタイプでフィルタ
teamIdstringいいえチームでフィルタ
searchstringいいえ検索キーワード

応答：

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "agent_12345",
        "name": "My Code Assistant",
        "description": "コード生成とレビューに特化したエージェント",
        "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
    }
  }
}

エージェント作成

エンドポイント：POST /agents

説明：新しいエージェントを作成

要求本体：

{
  "name": "My Code Assistant",
  "description": "コード生成とレビューに特化したエージェント",
  "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"
  }
}

エージェント詳細取得

エンドポイント：GET /agents/:id

説明：指定エージェントの詳細情報を取得

パスパラメータ：

パラメータタイプ必須説明
idstringはいAgent ID

応答：エージェントリストの単一エージェントオブジェクトと同じ

エージェント更新

エンドポイント：PUT /agents/:id

説明：エージェント情報を更新

パスパラメータ：

パラメータタイプ必須説明
idstringはいAgent ID

要求本体：

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

エージェント削除

エンドポイント：DELETE /agents/:id

説明：エージェントを削除

パスパラメータ：

パラメータタイプ必須説明
idstringはいAgent ID

エージェント起動

エンドポイント：POST /agents/:id/actions/start

説明：エージェントを起動

パスパラメータ：

パラメータタイプ必須説明
idstringはいAgent ID

エージェント停止

エンドポイント：POST /agents/:id/actions/stop

説明：エージェントを停止

エージェント再起動

エンドポイント：POST /agents/:id/actions/restart

説明：エージェントを再起動

エージェントログ取得

エンドポイント：GET /agents/:id/logs

説明：エージェントの実行ログを取得

照会パラメータ：

パラメータタイプ必須説明
levelstringいいえログレベルフィルタ
startTimestringいいえ開始時間
endTimestringいいえ終了時間
limitnumberいいえ戻り数量、デフォルト100
offsetnumberいいえオフセット、デフォルト0

Task API

タスクリスト

エンドポイント：GET /tasks

説明：タスクリストを取得

照会パラメータ：

パラメータタイプ必須説明
pagenumberいいえページ番号
limitnumberいいえページあたり数量
statusstringいいえステータスでフィルタ
agentIdstringいいえエージェントでフィルタ
prioritystringいいえ優先度でフィルタ
assigneeIdstringいいえ担当者でフィルタ

タスク作成

エンドポイント：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

説明：通知リストを取得

照会パラメータ：

パラメータタイプ必須説明
pagenumberいいえページ番号
limitnumberいいえページあたり数量
readbooleanいいえ既読状態でフィルタ
typestringいいえタイプでフィルタ

通知を既読にマーク

エンドポイント：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をサポートし、特定のイベントが発生した際に指定URLにHTTP POST要求を送信可能。

サポートされるイベントタイプ

  • agent.created：エージェント作成
  • agent.updated：エージェント更新
  • agent.deleted：エージェント削除
  • agent.status_changed：エージェントステータス変更
  • 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'
});

// エージェントリスト
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('タスク完了:', data);
});

Python SDK例

インストール

pip install alius-agent-team-sdk

使用例

from alius_agent_team import AliusClient

# クライアント初期化
client = AliusClient(api_key="YOUR_API_KEY")

# エージェントリスト
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管理をサポート
  • SMS、Apple、WeChatログインをサポート

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