2877 Arena API 3dbfee82

多Agent策略竞技场 API 文档

概述

多Agent策略竞技场API提供了完整的竞技场管理、策略竞争、Agent讨论和评估功能接口。

基础URL

/api/arena

认证

所有API端点都需要认证。请在请求头中包含有效的认证token。

竞技场管理

创建竞技场

POST /api/arena/create

创建一个新的多Agent策略竞技场。

请求体

{
  "name": "我的竞技场",
  "description": "测试竞技场描述",
  "agent_count": 5,
  "symbols": ["000001.SZ", "600000.SH"],
  "discussion_max_rounds": 3,
  "initial_capital": 100000.0,
  "backtest_start_date": "2024-01-01",
  "backtest_end_date": "2024-12-31",
  "simulated_duration_days": 30
}

参数说明

响应

{
  "id": "arena_abc123",
  "name": "我的竞技场",
  "state": "created",
  "active_strategies": 0,
  "total_strategies": 0,
  "eliminated_strategies": 0,
  "discussion_rounds": 0,
  "last_evaluation": null,
  "duration_seconds": 0,
  "error_count": 0,
  "last_error": null
}

获取竞技场状态

GET /api/arena/{arena_id}/status

获取指定竞技场的当前状态。

响应

{
  "id": "arena_abc123",
  "name": "我的竞技场",
  "state": "discussing",
  "active_strategies": 5,
  "total_strategies": 5,
  "eliminated_strategies": 0,
  "discussion_rounds": 2,
  "last_evaluation": "2024-01-15T10:30:00",
  "duration_seconds": 3600.5,
  "error_count": 0,
  "last_error": null
}

状态说明

启动竞技场

POST /api/arena/{arena_id}/start

启动竞技场竞争流程。

响应

{
  "status": "started",
  "arena_id": "arena_abc123"
}

暂停竞技场

POST /api/arena/{arena_id}/pause

暂停竞技场竞争流程。

恢复竞技场

POST /api/arena/{arena_id}/resume

恢复已暂停的竞技场。

删除竞技场

DELETE /api/arena/{arena_id}

删除指定竞技场及其所有数据。

列出所有竞技场

GET /api/arena/list

查询参数

响应

{
  "total": 3,
  "arenas": [
    {
      "id": "arena_abc123",
      "name": "竞技场1",
      "state": "discussing",
      "active_strategies": 5
    }
  ]
}

思考流

SSE实时思考流

GET /api/arena/{arena_id}/thinking-stream

Server-Sent Events端点，实时获取Agent思考消息。

查询参数

事件格式

data: {
  "id": "msg_123",
  "arena_id": "arena_abc123",
  "agent_id": "agent_1",
  "agent_role": "strategy_generator",
  "round_id": "round_1",
  "message_type": "thinking",
  "content": "分析市场数据...",
  "metadata": {},
  "timestamp": "2024-01-15T10:30:00"
}

消息类型

获取讨论历史

GET /api/arena/{arena_id}/discussions

响应

{
  "total": 5,
  "discussions": [
    {
      "id": "round_1",
      "arena_id": "arena_abc123",
      "round_number": 1,
      "mode": "debate",
      "participants": ["agent_1", "agent_2"],
      "conclusions": {
        "agent_1": "建议采用均线策略",
        "agent_2": "建议关注风险控制"
      },
      "started_at": "2024-01-15T10:00:00",
      "completed_at": "2024-01-15T10:30:00",
      "duration_seconds": 1800
    }
  ]
}

策略管理

获取策略列表

GET /api/arena/{arena_id}/strategies

查询参数

获取策略详情

GET /api/arena/{arena_id}/strategies/{strategy_id}

响应

{
  "id": "strategy_1",
  "name": "均线交叉策略",
  "description": "基于MA5和MA20的交叉信号",
  "agent_id": "agent_1",
  "agent_role": "strategy_generator",
  "stage": "simulated",
  "is_active": true,
  "current_score": 75.5,
  "current_rank": 2,
  "logic": "当MA5上穿MA20时买入...",
  "rules": {
    "buy_condition": "MA5 > MA20",
    "sell_condition": "MA5 < MA20",
    "stop_loss": 0.05,
    "take_profit": 0.10
  }
}

获取排行榜

GET /api/arena/{arena_id}/leaderboard

响应

{
  "total": 5,
  "leaderboard": [
    {
      "rank": 1,
      "strategy_id": "strategy_1",
      "name": "均线交叉策略",
      "agent_id": "agent_1",
      "agent_role": "strategy_generator",
      "score": 85.5,
      "stage": "simulated"
    }
  ]
}

获取策略评分明细

GET /api/arena/{arena_id}/strategies/{strategy_id}/score-breakdown

响应

{
  "strategy_id": "strategy_1",
  "total_score": 75.5,
  "breakdown": {
    "profitability": 80.0,
    "risk_control": 70.0,
    "stability": 75.0,
    "adaptability": 72.0
  },
  "weights": {
    "profitability": 0.30,
    "risk_control": 0.30,
    "stability": 0.20,
    "adaptability": 0.20
  }
}

评估与淘汰

触发评估

POST /api/arena/{arena_id}/evaluate

手动触发周期评估。

请求体

{
  "period": "weekly"
}

获取淘汰历史

GET /api/arena/{arena_id}/elimination-history

响应

{
  "total": 3,
  "events": [
    {
      "id": "elim_strategy_3",
      "type": "elimination",
      "timestamp": "2024-01-15T10:30:00",
      "period": "weekly",
      "strategy_name": "高频交易策略",
      "strategy_id": "strategy_3",
      "score": 45.2,
      "reason": "评分低于淘汰阈值"
    },
    {
      "id": "eval_123",
      "type": "evaluation",
      "timestamp": "2024-01-15T10:00:00",
      "period": "weekly",
      "total_strategies": 5,
      "eliminated_count": 1
    }
  ]
}

讨论控制

触发讨论

POST /api/arena/{arena_id}/discussion/start

请求体

{
  "mode": "debate"
}

获取当前讨论状态

GET /api/arena/{arena_id}/discussion/current

人工干预

POST /api/arena/{arena_id}/discussion/intervention

允许人工干预竞技场运行。

请求体

{
  "action": "inject_message",
  "message": "请关注近期市场波动风险",
  "reason": "市场环境变化"
}

可用操作

示例 - 调整评分

{
  "action": "adjust_score",
  "target_strategy_id": "strategy_1",
  "score_adjustment": 10,
  "reason": "手动奖励优秀表现"
}

示例 - 强制淘汰

{
  "action": "eliminate_strategy",
  "target_strategy_id": "strategy_3",
  "reason": "策略逻辑存在严重问题"
}

错误响应

所有API在发生错误时返回以下格式：

{
  "detail": "错误描述信息"
}

常见HTTP状态码

WebSocket支持

思考流同时支持WebSocket连接（开发中）：

ws://localhost:8000/ws/arena/{arena_id}/thinking