Agent Mode API Manual | Hawk-Backtester

Concept»

あなたの AI Agent が自律的に「戦略生成 → 実行 → 評価 → 改善」を循環させます。
※ AI Agent はお客様がご契約・ご用意されるもので、本サービスには含まれません。

1戦略コード生成

データ特徴量をもとに
hawk-bt の Strategy を生成

AI Agent

2バックテスト実行・結果閲覧

hawk-bt → WASM へ
STEP_NEXT ループを自動実行

AI Agent

API

4戦略を改善

評価結果をもとに
パラメータ / ロジックを修正

AI Agent

3結果を評価

return, DD, profit factor 等
を判定、改善ポイントを特定

AI Agent

Quick Start»

pip install hawk-bt

※ PyPI 上の hawk-backtester は本プロジェクトとは無関係の別パッケージです。

サービスログイン後、with AI Agent タブをクリック
Agent Mode を ON
Agent Dashboard をブラウザで開いたままにする
AI Agent に以下のような指示を実行:

実行の仕組み

WASM シミュレーションエンジンはブラウザ上で動作します。Agent が HawkEngine を起動してから POST /v1/backtests でセッションを登録すると、Agent Dashboard が自動検知してシミュレーション → 分析 → 保存まで一貫して実行します。

Agent が engine.start_background(strategy) で WebSocket サーバーをバックグラウンド起動し、engine.wait_ready() で待機
Agent が POST /v1/backtests を送信（セッション登録 + ws_url 指定）
※ API がエンジンへの接続を検証するため、先にエンジンを起動しておく必要があります
Agent Dashboard（ブラウザ）が自動的にセッションを検知し、WASM エンジンを起動して WS 接続
シミュレーション完了後、ブラウザが全分析データ（resultStats、ticketTraces + MFE/MAE、時系列データ）を自動計算し、サーバーに保存
Agent が GET /v1/backtests/{id}/results で包括的な分析データを取得

Agent Dashboard を開いておく必要があります — WASM の実行環境として機能します
手動操作は不要 — ブラウザが QUEUED セッションを 3 秒間隔で検知し、自動的に開始します
同一マシン上で実行 — ブラウザと Agent は同じマシン上で動作する必要があります (ws://127.0.0.1:8787)

# ── あなたの AI Agent への指示テンプレート ──

あなたはトレーディング戦略を自律的に開発・改善するエージェントです。

## 参照ドキュメント
以下の 2 つを事前に読み込んでください。
1. Agent Mode API Manual … REST/WS の仕様、Analysis Data の構造
   https://app.hawk-backtester.com/agent-manual/
2. hawk-bt リファレンス  … Strategy クラスの書き方、HawkEngine の設定
   https://app.hawk-backtester.com/py-engine/

## 手順
1. 戦略コード生成
   hawk-bt の Strategy クラスを継承し、async def step(ctx) にロジックを実装。
   特定のデータに過剰適合せず、汎用的に勝てる戦略を目指すこと。

2. データセット選択
   GET /v1/data/datasets でデータセット一覧を取得し、
   GET /v1/data/features で特徴量 (volatility, trend_strength, regime_hint 等) を確認。
   戦略の検証に適したデータセットを選択すること。

3. バックテスト実行
   hawk-bt の HawkEngine をバックグラウンドで起動し、
   engine.wait_ready() 後に POST /v1/backtests でセッション登録。
   thread.join() でシミュレーション完了を待ち、結果を取得。

4. 結果評価
   analysis.outcome (totalReturn, maxDrawdown, returnOverMaxDD),
   analysis.attribution (profitFactor, winRate),
   analysis.action (totalOrders, medianHoldingTime) を総合的に評価。
   単一指標ではなく、リスク調整後リターンを重視すること。

5. 戦略改善
   評価結果から具体的な改善点を特定し、戦略コードを修正。
   手順 3 に戻り、改善ループを繰り返す。

6. 保存
   目標水準を達成したら POST /v1/backtests/{session_id}/save で保存。

## 制約
- 1 イテレーションごとに strategy_note に変更意図を記録すること

Security»

API Key

生成時に一度だけ表示されます。必ずコピーして安全に保管してください。
有効期限は 90 日間です。期限切れ後は Dashboard から再生成してください。
Revoke すると即座に無効化されます。

レートリミット

API リクエスト: 300 回/分 (IP ベース)
認証失敗: 同一 IP から 10 回失敗すると 15 分間ロックアウトされます。

WebSocket 接続

hawk-bt の WS サーバーは 127.0.0.1:8787 にバインドされます。外部ネットワークには公開されません。
接続時に Origin ヘッダー検証を行い、許可リスト外のオリジンからの接続は 403 Forbidden で拒否されます。
Agent とブラウザが同一マシン上で実行されている必要があります。

API Reference»

Base: /v1/

Data API

GET /v1/data/datasets

データセット一覧 (summary_stats, regime_hint 付き)

Response

{
  "datasets": [{
    "dataset_id": 123,
    "symbol": "EURUSD",
    "timeframe": "1H",
    "rows": 5000,
    "summary_stats": {
      "mean": 1.0892, "volatility": 0.0045,
      "hurst_exponent": 0.52, "trend_strength": 0.65, ...
    },
    "regime_hint": "trend"
  }]
}

GET /v1/data/datasets/{id}

データセット詳細

Response

{
  "dataset_id": 123,
  "symbol": "EURUSD",
  "name": "EURUSD_1H_2024",
  "timeframe": "1H",
  "rows": 5000,
  "file_path": "ohlc/eurusd_1h.csv",
  "close_series": [1.0892, 1.0895, ...]  // optional: max 2000点にダウンサンプル
}

GET /v1/data/features?dataset_id=123

特徴量一覧 (カテゴリ分類付き)

Response

{
  "features": [{
    "dataset_id": 123,
    "target_type": "close",
    "features": {
      "volatility": { "value": 0.0045, "category": "volatility" }, ...
    }
  }]
}

Backtest API

POST /v1/backtests

セッション登録 + 自動起動信号

ブラウザ（Agent Dashboard）が QUEUED セッションを自動検知し、シミュレーションを開始します。

Request

{
  "dataset_id": 123,
  "iteration": 1,
  "strategy_note": "RSI(14) + SMA crossover, SL=2%",
  "seed": 42,
  "ws_url": "ws://127.0.0.1:8787",  // HawkEngine の WS アドレス (省略時デフォルト)
  "config": {
    "leverage": 25,
    "initial_assets": 10000
  }
}

Response (201)

{ "session_id": "550e8400-...", "status": "queued" }

GET /v1/backtests/{session_id}/results

結果取得 (推奨) — ブラウザが保存した包括的な分析データを取得

ブラウザがシミュレーション完了後に自動的に全分析データ (outcome, attribution, ticketTraces, timeSeries 等) を計算・保存します。
Agent は on_result でシミュレーション完了を検知した後、このエンドポイントで結果を取得してください。

Response

{
  "session_id": "...",
  "status": "succeeded",
  "analysis": {
    "outcome":      { ... },    // → Analysis Data Format
    "exposure":     { ... },
    "attribution":  { ... },
    "action":       { ... },
    "ticketTraces": [ ... ],    // MFE/MAE 付きトレード明細
    "timeSeries":   { ... },    // equity, drawdown, exposure 等 (max 2000点)
    "totalSteps":   5000,
    "initialAssets": 10000
  }
}

POST /v1/backtests/{session_id}/save

セッションを SimulationResult としてフル保存

Request

Field	Type	Required	Description
title	string	-	保存タイトル (省略時: `Agent #N: strategy_note`)
memo	string	-	メモ (省略時: strategy_note)
strategy_name	string	-	戦略名 (例: `"SMA_Crossover_v2"`)

{
  "title": "Best Strategy #3",
  "memo": "PF 1.8, DD -3.2%",
  "strategy_name": "SMA_Crossover_v2"
}

データセットはセッション作成時の dataset_id から自動的に引き継がれます。
レバレッジはセッション作成時の config.leverage から自動的に保存されます。
これらを変更する必要はありません — POST /v1/backtests で正しく設定してください。

Response

{ "result_id": "a1b2c3d4-..." }

Status API

GET /v1/agent/status

Agent Mode 状態 + 直近セッション

GET /v1/agent/dashboard-data?limit=30

Dashboard 用タイムライン (max 50)

WebSocket Protocol»

WS 通信 (INIT・STEP_NEXT・注文・結果受信) はすべて hawk-bt が自動処理します。
Agent が意識するのは以下の 2 点のみです。

Config

シミュレーション設定はブラウザ側 (Agent Dashboard) から WASM に適用されます。
POST /v1/backtests の config フィールドで指定可能。

Field	Type	Description
leverage	float	レバレッジ倍率 (0 = 無制限)
commission	float	1注文あたりの手数料率
ticketLimitMargin	float	必要証拠金率
maxTicketLimits	int	最大同時ポジション数 (0 = 無制限)

HawkEngine: single_run モード

Agent Mode では single_run=True を必ず指定してください。
デフォルト (single_run=False) では、シミュレーション完了後もプロセスが次のブラウザ接続を待ち続けます。 single_run=True を指定すると、1 回のシミュレーション完了後にプロセスが終了し、Agent の自律ループが継続できます。

engine = HawkEngine(
    host="127.0.0.1", port=8787,
    single_run=True,   # Agent Mode: 1回で終了
    on_result=my_callback,
)

# バックグラウンド起動 → セッション登録 → 完了待ち
thread = engine.start_background(strategy)
engine.wait_ready()          # WS サーバー起動を待つ
requests.post(...)           # POST /v1/backtests でセッション登録
thread.join()                # シミュレーション完了を待つ

Analysis Result

シミュレーション完了後、ブラウザが全分析データを自動計算し、サーバーに保存します。

hawk-bt の on_result コールバックで BacktestResult (balance/equity 配列) を受信
同時にブラウザ側で resultStats, ticketTraces (MFE/MAE 付き), 時系列データ (equity, drawdown, exposure 等) を計算
ブラウザが POST /v1/backtests/report で包括的な分析データをサーバーに保存
Agent は GET /v1/backtests/{session_id}/results で全データを取得可能

詳細な分析データは Analysis Data Format を参照。

Analysis Data Format»

シミュレーション完了後に受信する分析結果 JSON。

outcome

Field	Type	Note
totalSteps	int	総ステップ数
endingAssets	float	最終キャッシュ
endingEquity	float	最終評価額
totalReturn	float	0.075 = 7.5%
maxDrawdown	float	負値
returnOverMaxDD	float	リターン/最大DD
vsBuyHold	float	B&H比差額

exposure

Field	Type	Note
avgGrossExposure	float	平均グロスエクスポージャー
maxGrossExposure	float	最大グロスエクスポージャー
avgNetExposure	float	平均ネットエクスポージャー
timeInMarket	float	保有時間割合
longRatio	float	ロング比率
shortRatio	float	ショート比率
exposureEfficiency	float	totalReturn / avgGrossExposure

attribution

Field	Type	Note
longPnL	float	ロング累積損益
shortPnL	float	ショート累積損益
costPnL	float	取引コスト合計
totalPnL	float	longPnL + shortPnL + costPnL
longContrib	float	longPnL / totalPnL
shortContrib	float	shortPnL / totalPnL
costContrib	float	costPnL / totalPnL
profitFactor	float	総利益/総損失
costBurden	float	\|costPnL\| / \|longPnL + shortPnL\|
winRate	float	0.58 = 58%
winCount	int	勝ちトレード数
lossCount	int	負けトレード数
totalTickets	int	winCount + lossCount

action

Field	Type	Note
totalOrders	int	総注文数
buyCount	int	買い注文数
sellCount	int	売り注文数
buySellRatio	float	buyCount / (buyCount + sellCount)
ordersPer1000	float	1000ステップあたりの注文数
medianHoldingTime	float	保有時間の中央値 (ms)
p90HoldingTime	float	保有時間の90パーセンタイル (ms)
medianTicketSize	float	取引サイズの中央値
partialCloseCount	int	部分決済回数

ticketTraces

各トレードの詳細 + MFE/MAE (Max Favorable/Adverse Excursion)。

Field	Type	Note
ticketId	int	チケット ID
side	string	"long" or "short"
entryTime	float	エントリー時刻 (ms)
exitTime	float	決済時刻 (ms)
entryPrice	float	エントリー価格
exitPrice	float	決済価格
units	float	取引数量
lifetime	float	保有時間 (exitTime - entryTime)
exitReason	int	0=SL, 1=TP, 2=Strategy, 5=Force
pnl	float	損益 (units * price diff)
pnlPct	float	損益率 (%)
mfe	float	Max Favorable Excursion (金額)
mae	float	Max Adverse Excursion (金額)

timeSeries

時系列データ (最大 2000 点にダウンサンプル)。

Field	Type	Note
timestamps	float[]	タイムスタンプ (ms)
equity	float[]	評価額 (含み損益込み)
assets	float[]	キャッシュ残高
buyAndHold	float[]	Buy & Hold 比較曲線
drawdown	float[]	ドローダウン (負値)
netExposure	float[]	ネットエクスポージャー
grossExposure	float[]	グロスエクスポージャー
marginRatio	float[]	証拠金使用率
cumulativeLongPnL	float[]	累積ロング損益
cumulativeShortPnL	float[]	累積ショート損益
ticketLongCount	float[]	累積ロングチケット数
ticketShortCount	float[]	累積ショートチケット数
tokenLongCount	float[]	累積ロングトークン数
tokenShortCount	float[]	累積ショートトークン数

totalSteps / initialAssets

"totalSteps": 5000,       // シミュレーション総ステップ数
"initialAssets": 10000     // 初期資産額

Example Code»

以下は Concept の各ステップに対応するコード例です。
あなたの AI Agent がこれらを順番に実行し、自律的にループを回します。

Step 1 — 戦略コード生成

# hawk-bt の Strategy を継承して戦略を定義
from hawk_bt import Strategy, Context
from collections import deque

class MyStrategy(Strategy):
    def __init__(self):
        self.prices = deque(maxlen=50)

    def _sma(self, n):
        if len(self.prices) < n: return None
        return sum(list(self.prices)[-n:]) / n

    async def step(self, ctx: Context):
        s = ctx.state.snapshot
        self.prices.append(s.price)

        fast = self._sma(20)
        slow = self._sma(50)
        if fast is None or slow is None: return

        if fast > slow and s.tickets_num == 0:
            await ctx.engine.place_ticket(
                side="buy", units=10,
                take_profit=5.0, stop_loss=3.0,
            )

Step 2 — データセット選択 & バックテスト実行

import requests, time
from hawk_bt import HawkEngine, configure_logging

# ログ出力設定 (任意): 1=WARNING, 2=INFO (default), 3=DEBUG
configure_logging(verbosity=2)

API  = "https://your-server/v1"
AUTH = {"Authorization": "Bearer hawk_YOUR_KEY"}

# データセット選択
ds = requests.get(f"{API}/data/datasets", headers=AUTH).json()
ds_id = ds["datasets"][0]["dataset_id"]

# ① エンジンをバックグラウンド起動 (WS サーバーを先に立てる)
engine = HawkEngine(
    host="127.0.0.1", port=8787,
    single_run=True,
)
thread = engine.start_background(MyStrategy())
engine.wait_ready()  # WS サーバー起動完了を待つ

# ② セッション登録 (API がエンジンへの接続を検証するため、先にエンジン起動が必要)
session = requests.post(f"{API}/backtests", headers=AUTH, json={
    "dataset_id": ds_id,
    "iteration": 1,
    "strategy_note": "SMA crossover 20/50",
    "ws_url": "ws://127.0.0.1:8787",
    "config": {"leverage": 25, "initial_assets": 10000},
}).json()
sid = session["session_id"]

# ③ シミュレーション完了を待つ
thread.join()

# ブラウザが分析データを保存するまで少し待つ
time.sleep(2)

# 結果取得 — ブラウザが全分析データを自動計算・保存済み
result = requests.get(
    f"{API}/backtests/{sid}/results", headers=AUTH
).json()
analysis = result["analysis"]

Step 3 — 結果を評価

# サマリー指標
print(f"Return:        {analysis['outcome']['totalReturn']:.2%}")
print(f"Max Drawdown:  {analysis['outcome']['maxDrawdown']:.2%}")
print(f"Profit Factor: {analysis['attribution']['profitFactor']}")
print(f"Win Rate:      {analysis['attribution']['winRate']}")
print(f"Total Orders:  {analysis['action']['totalOrders']}")

# トレード明細 (MFE/MAE 付き)
for t in analysis.get("ticketTraces", [])[:5]:
    print(f"  {t['side']} pnl={t['pnl']:.2f} ({t['pnlPct']:.1f}%)  MFE={t['mfe']:.2f}  MAE={t['mae']:.2f}")

# 時系列データ (equity, drawdown, exposure 等)
ts = analysis.get("timeSeries", {})
print(f"Time series points: {len(ts.get('equity', []))}")
print(f"Final equity:  {ts['equity'][-1]:.2f}")
print(f"Final B&H:     {ts['buyAndHold'][-1]:.2f}")
print(f"Min drawdown:  {min(ts['drawdown']):.2%}")

Step 4 — 戦略を改善 / 保存

# 目標達成 → 保存
# dataset_id, leverage はセッション作成時の値が自動的に保存される
requests.post(
    f"{API}/backtests/{sid}/save",
    headers=AUTH,
    json={
        "title": "SMA crossover v1",
        "memo": "PF 1.8, DD -3.2%",
        "strategy_name": "SMA_Crossover",   // 戦略名 (任意)
    }
)

# 未達 → 評価結果をもとに戦略コードを修正し、Step 2 へ戻る