コンテンツにスキップ

エージェント統合ガイド

AIエージェントの方へ: お使いのフレームワークがMCPをサポートしている場合はMCPを使用し、それ以外の場合はREST APIを使用してください。セットアップについてはクイックスタートをご覧ください。

概要

asiai は、2つの仕組みを通じてMacのLLM推論インフラストラクチャをAIエージェントに公開します：

  • MCPサーバー — Model Context Protocolによるネイティブツール統合。MCPをサポートするAIエージェント（Claude Code、Cursor、Cline、その他のMCP対応クライアント）に最適です。
  • REST API — 標準的なHTTP/JSONエンドポイント。エージェントフレームワーク、スウォームオーケストレーター、およびHTTP対応のあらゆるシステム（CrewAI、AutoGen、LangGraph、カスタムエージェント）に最適です。

どちらも同じ機能にアクセスできます：

  • システムヘルス（CPU、RAM、GPU、サーマル、スワップ）の監視
  • 実行中の推論エンジンとロードされたモデルの検出
  • GPU可観測性と推論アクティビティシグナルを使用したパフォーマンス問題の診断
  • プログラムによるモデルのベンチマークとリグレッションの追跡
  • ハードウェアに基づく最適なモデル/エンジンの推奨の取得

ローカルアクセスには認証は不要です。すべてのインターフェースはデフォルトで 127.0.0.1 にバインドされます。

どの統合方法を使うべきですか？

基準 MCP REST API
エージェントがMCPをサポートしている MCPを使用 —
スウォーム / マルチエージェントオーケストレーター — REST APIを使用
ポーリング / スケジュール監視 — REST APIを使用
Prometheus / Grafana統合 — REST APIを使用
インタラクティブAIアシスタント（Claude Code、Cursor） MCPを使用 —
Dockerコンテナ内のエージェント — REST APIを使用
カスタムスクリプトまたは自動化 — REST APIを使用

クイックスタート

asiai のインストール

# Homebrew（推奨）
brew tap druide67/tap && brew install asiai

# pip（MCPサポート付き）
pip install "asiai[mcp]"

# pip（REST APIのみ）
pip install asiai

オプションA: MCPサーバー（MCP対応エージェント向け）

# MCPサーバーを起動（stdioトランスポート — Claude Code、Cursorなどで使用）
asiai mcp

手動でサーバーを起動する必要はありません — MCPクライアントが自動的に asiai mcp を起動します。詳細は下記のMCPセットアップをご覧ください。

オプションB: REST API（HTTPベースのエージェント向け）

# フォアグラウンド（開発用）
asiai web --no-open

# バックグラウンドデーモン（本番環境）
asiai daemon start web

APIは http://127.0.0.1:8899 で利用可能です。ポートは --port で設定できます：

asiai daemon start web --port 8642

リモートアクセス（別マシンのAIエージェントやDockerコンテナから）の場合：

asiai daemon start web --host 0.0.0.0

注意: エージェントがDocker内で実行されている場合、127.0.0.1 にはアクセスできません。ホストのネットワークIP（例：192.168.0.16）またはDocker Desktop for Macの host.docker.internal を使用してください。

動作確認

# REST API
curl http://127.0.0.1:8899/api/status

# MCP（利用可能なツールの一覧）
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | asiai mcp

MCP (Model Context Protocol)

asiai は推論監視をネイティブツールとして公開するMCPサーバーを実装しています。MCP対応のクライアントは直接接続してこれらのツールを使用できます — HTTPのセットアップやURL管理は不要です。

セットアップ

ローカル（同一マシン）

MCPクライアント設定（例：Claude Codeの ~/.claude/settings.json）に追加してください：

{
  "mcpServers": {
    "asiai": {
      "command": "asiai",
      "args": ["mcp"]
    }
  }
}

asiai が仮想環境にインストールされている場合：

{
  "mcpServers": {
    "asiai": {
      "command": "/path/to/.venv/bin/asiai",
      "args": ["mcp"]
    }
  }
}

リモート（SSH経由の別マシン）

{
  "mcpServers": {
    "asiai": {
      "command": "ssh",
      "args": [
        "-o", "ServerAliveInterval=30",
        "-o", "ServerAliveCountMax=3",
        "your-mac-host",
        "cd /path/to/asiai && .venv/bin/asiai mcp"
      ]
    }
  }
}

SSEトランスポート（ネットワーク）

HTTPベースのMCPトランスポートを好む環境の場合：

asiai mcp --transport sse --host 127.0.0.1 --port 8900

MCPツールリファレンス

すべてのツールはJSONを返します。読み取り専用ツールは2秒未満で応答します。run_benchmark のみがアクティブな操作です。

ツール 説明 パラメータ
check_inference_health クイックヘルスチェック — エンジンの稼働/停止状態、メモリプレッシャー、サーマル、GPU使用率 —
get_inference_snapshot フルシステム状態のスナップショット（履歴用にSQLiteに保存） —
list_models 全エンジンにロードされた全モデル（VRAM、量子化、コンテキスト長） —
detect_engines 3層検出：設定、ポートスキャン、プロセス検出。非標準ポートのエンジンも自動検出 —
run_benchmark モデルのベンチマークまたはクロスモデル比較を実行。レート制限：60秒に1回 model（任意）、runs（1〜10、デフォルト3）、compare（文字列リスト、任意、modelと排他、最大8）
get_recommendations ハードウェアに応じたモデル/エンジンの推奨 —
diagnose 診断チェック（システム、エンジン、デーモンヘルス）を実行 —
get_metrics_history SQLiteからの過去のシステムメトリクス hours（1〜168、デフォルト24）
get_benchmark_history 過去のベンチマーク結果 hours（1〜720、デフォルト24）、model（任意）、engine（任意）
compare_engines 指定モデルに対するエンジン比較のランキングと判定；履歴からのマルチモデル比較をサポート model（必須）
refresh_engines MCPサーバーを再起動せずにエンジンを再検出 —

MCPリソース

ツールを呼び出さずに利用可能な静的データエンドポイント：

URI 説明
asiai://status 現在のヘルスステータス（メモリ、サーマル、GPU）
asiai://models 全エンジンのロード済みモデル
asiai://system ハードウェア情報（チップ、RAM、コア数、OS、稼働時間）

MCPセキュリティ

  • sudo不要: MCPモードでは電力メトリクスが無効化されます（power=False が強制）
  • レート制限: ベンチマークは60秒に1回に制限
  • 入力クランプ: hours は1〜168、runs は1〜10にクランプ
  • デフォルトでローカル: stdioトランスポートはネットワーク露出なし；SSEは 127.0.0.1 にバインド

MCPの制限事項

  • 再接続なし: SSH接続が切断された場合（ネットワーク問題、Macのスリープ）、MCPサーバーは停止し、クライアントは手動で再接続する必要があります。無人監視には、ポーリングによるREST APIの方が堅牢です。
  • シングルクライアント: stdioトランスポートは一度に1つのクライアントにのみ対応します。複数クライアントの同時アクセスが必要な場合は、SSEトランスポートを使用してください。

REST APIリファレンス

asiai のAPIは読み取り専用です — 監視とレポートのみで、エンジンの制御は行いません。モデルのロード/アンロードには、エンジン固有のコマンド（ollama pull、lms load など）を使用してください。

すべてのエンドポイントはHTTP 200でJSONを返します。エンジンに到達できない場合でも、そのエンジンの "running": false を含むHTTP 200のレスポンスが返されます — API自体は失敗しません。

エンドポイント 通常のレスポンスタイム 推奨タイムアウト
GET /api/status 500ms未満（10秒キャッシュ） 2秒
GET /api/snapshot 1〜3秒（ライブ収集） 10秒
GET /api/metrics 500ms未満 2秒
GET /api/history 500ms未満 5秒
GET /api/engine-history 500ms未満 5秒

GET /api/status

クイックヘルスチェック。10秒キャッシュ。レスポンスタイム500ms未満。

レスポンス：

{
  "hostname": "mac-mini",
  "chip": "Apple M4 Pro",
  "ram_gb": 64.0,
  "cpu_percent": 12.3,
  "memory_pressure": "normal",
  "gpu_utilization_percent": 45.2,
  "engines": {
    "ollama": {
      "running": true,
      "models_loaded": 2,
      "port": 11434
    },
    "lmstudio": {
      "running": true,
      "models_loaded": 1,
      "port": 1234
    }
  },
  "asiai_version": "1.0.1",
  "uptime_seconds": 86400
}

GET /api/snapshot

フルシステム状態。/api/status のすべてに加え、詳細なモデル情報、GPUメトリクス、サーマルデータを含みます。

レスポンス：

{
  "system": {
    "hostname": "mac-mini",
    "chip": "Apple M4 Pro",
    "cores_p": 12,
    "cores_e": 4,
    "gpu_cores": 20,
    "ram_total_gb": 64.0,
    "ram_used_gb": 41.2,
    "ram_percent": 64.4,
    "swap_used_gb": 0.0,
    "memory_pressure": "normal",
    "cpu_percent": 12.3,
    "thermal_state": "nominal",
    "gpu_utilization_percent": 45.2,
    "gpu_renderer_percent": 38.1,
    "gpu_tiler_percent": 12.4,
    "gpu_memory_allocated_bytes": 8589934592
  },
  "engines": [
    {
      "name": "ollama",
      "running": true,
      "port": 11434,
      "models": [
        {
          "name": "qwen3.5:latest",
          "size_params": "35B",
          "size_vram_bytes": 21474836480,
          "quantization": "Q4_K_M",
          "context_length": 32768
        }
      ]
    }
  ],
  "timestamp": "2026-03-09T14:30:00Z"
}

GET /api/metrics

Prometheus互換メトリクス。Prometheus、Datadog、またはその他の互換ツールでスクレイプできます。

レスポンス (text/plain)：

# HELP asiai_cpu_percent CPU usage percentage
# TYPE asiai_cpu_percent gauge
asiai_cpu_percent 12.3

# HELP asiai_ram_used_gb RAM used in GB
# TYPE asiai_ram_used_gb gauge
asiai_ram_used_gb 41.2

# HELP asiai_gpu_utilization_percent GPU utilization percentage
# TYPE asiai_gpu_utilization_percent gauge
asiai_gpu_utilization_percent 45.2

# HELP asiai_engine_up Engine availability (1=up, 0=down)
# TYPE asiai_engine_up gauge
asiai_engine_up{engine="ollama"} 1
asiai_engine_up{engine="lmstudio"} 1

# HELP asiai_models_loaded Number of models loaded per engine
# TYPE asiai_models_loaded gauge
asiai_models_loaded{engine="ollama"} 2

GET /api/history?hours=N

SQLiteからの過去のシステムメトリクス。デフォルト：hours=24。最大：hours=2160（90日）。

レスポンス：

{
  "points": [
    {
      "timestamp": "2026-03-09T14:00:00Z",
      "cpu_percent": 15.2,
      "ram_used_gb": 40.1,
      "ram_percent": 62.7,
      "swap_used_gb": 0.0,
      "memory_pressure": "normal",
      "thermal_state": "nominal",
      "gpu_utilization_percent": 42.0,
      "gpu_renderer_percent": 35.0,
      "gpu_tiler_percent": 10.0,
      "gpu_memory_allocated_bytes": 8589934592
    }
  ],
  "count": 144,
  "hours": 24
}

GET /api/engine-history?engine=X&hours=N

エンジン固有のアクティビティ履歴。推論パターンの検出に便利です。

パラメータ：

パラメータ 必須 デフォルト 説明
engine はい — エンジン名（ollama、lmstudioなど）
hours いいえ 24 時間範囲

レスポンス：

{
  "engine": "ollama",
  "points": [
    {
      "timestamp": "2026-03-09T14:00:00Z",
      "running": true,
      "tcp_connections": 3,
      "requests_processing": 1,
      "kv_cache_usage_percent": 45.2
    }
  ],
  "count": 144,
  "hours": 24
}

メトリクスの解釈

システムヘルスの閾値

メトリクス 正常 警告 危険
memory_pressure normal warn critical
ram_percent 75%未満 75〜90% 90%超
swap_used_gb 0 0.1〜2.0 2.0超
thermal_state nominal fair serious / critical
cpu_percent 80%未満 80〜95% 95%超

GPUの閾値

メトリクス アイドル 推論中 過負荷
gpu_utilization_percent 0〜5% 20〜80% 90%超（持続）
gpu_renderer_percent 0〜5% 15〜70% 85%超（持続）
gpu_memory_allocated_bytes 1 GB未満 2〜48 GB RAMの90%超

重要: gpu_utilization_percent = 0 はGPUがアイドル状態であることを意味し、故障ではありません。-1.0 はメトリクスが利用できないこと（例：非対応ハードウェアまたは収集失敗）を意味します — 「GPU停止」として扱わないでください。

推論パフォーマンス

メトリクス 優秀 良好 劣化
tok/s（7Bモデル） 80超 40〜80 40未満
tok/s（35Bモデル） 40超 20〜40 20未満
tok/s（70Bモデル） 15超 8〜15 8未満
TTFT 100ms未満 100〜500ms 500ms超

診断デシジョンツリー

生成速度低下（低tok/s）

graph TD
    A["tok/s below expected?"] --> B["Check memory_pressure"]
    A --> C["Check thermal_state"]
    A --> D["Check gpu_utilization_percent"]
    A --> E["Check swap_used_gb"]

    B -->|critical| B1["Models swapping to disk.<br/>Unload models or add RAM."]
    B -->|normal| B2["Continue"]

    C -->|"serious / critical"| C1["Thermal throttling.<br/>Cool down, check airflow."]
    C -->|nominal| C2["Continue"]

    D -->|"< 10%"| D1["GPU not being used.<br/>Check engine config (num_gpu layers)."]
    D -->|"> 90%"| D2["GPU saturated.<br/>Reduce concurrent requests."]
    D -->|"20-80%"| D3["Normal. Check model<br/>quantization and context size."]

    E -->|"> 0"| E1["Model too large for RAM.<br/>Use smaller quantization."]
    E -->|"0"| E2["Check engine version,<br/>try different engine."]

エンジン無応答

graph TD
    A["engine.running == false?"] --> B["Check process: lsof -i :port"]
    A --> C["Check memory_pressure"]
    A --> D["Try: asiai doctor"]

    B -->|No process| B1["Engine crashed. Restart it."]
    B -->|Process exists| B2["Engine hung."]

    C -->|critical| C1["OOM killed.<br/>Unload other models first."]
    C -->|normal| C2["Check engine logs."]

    D --> D1["Comprehensive diagnostics"]

高メモリプレッシャー / VRAMオーバーフロー

graph TD
    A["memory_pressure == warn/critical?"] --> B["Check swap_used_gb"]
    A --> C["Check models loaded"]
    A --> D["Check gpu_memory_allocated_bytes"]

    B -->|"> 2 GB"| B1["VRAM overflow.<br/>Latency 5-50x worse (disk swap).<br/>Unload models or use Q3_K_S."]
    B -->|"< 2 GB"| B2["Manageable.<br/>Monitor closely."]

    C -->|"Multiple large models"| C1["Unload unused models.<br/>ollama rm / lms unload"]
    C -->|"Single model > 80% RAM"| C2["Use smaller quantization."]

    D --> D1["If > 80% of RAM,<br/>next model load triggers swap."]

推論アクティビティシグナル

asiai は複数のシグナルを通じてアクティブな推論を検出します：

GPU使用率

GET /api/snapshot → system.gpu_utilization_percent
  • 5%未満: 推論は実行されていません
  • 20〜80%: アクティブな推論（Apple Siliconユニファイドメモリの通常範囲）
  • 90%超: 大量の推論または複数の同時リクエスト

TCP接続

GET /api/engine-history?engine=ollama&hours=1

アクティブな推論リクエストはそれぞれTCP接続を維持します。tcp_connections のスパイクはアクティブな生成を示します。

エンジン固有メトリクス

/metrics を公開するエンジン（llama.cpp、vllm-mlx）の場合：

  • requests_processing > 0: アクティブな推論
  • kv_cache_usage_percent > 0: モデルにアクティブなコンテキストがあります

相関パターン

最も信頼性の高い推論検出は、複数のシグナルを組み合わせます：

snapshot = get_snapshot()
gpu_active = snapshot["system"]["gpu_utilization_percent"] > 15
engine_busy = any(
    e.get("tcp_connections", 0) > 0
    for e in snapshot.get("engine_status", [])
)
inference_running = gpu_active and engine_busy

コード例

ヘルスチェック（Python、標準ライブラリのみ）

import json
import urllib.request

ASIAI_URL = "http://127.0.0.1:8899"  # Docker: ホストIPまたはhost.docker.internalを使用

def check_health():
    """クイックヘルスチェック。ステータスのdictを返します。"""
    req = urllib.request.Request(f"{ASIAI_URL}/api/status")
    with urllib.request.urlopen(req, timeout=5) as resp:
        return json.loads(resp.read())

def is_healthy(status):
    """ヘルスステータスを解釈します。"""
    issues = []
    if status.get("memory_pressure") != "normal":
        issues.append(f"memory_pressure: {status['memory_pressure']}")
    gpu = status.get("gpu_utilization_percent", 0)
    if gpu > 90:
        issues.append(f"gpu_utilization: {gpu}%")
    engines = status.get("engines", {})
    for name, info in engines.items():
        if not info.get("running"):
            issues.append(f"engine_down: {name}")
    return {"healthy": len(issues) == 0, "issues": issues}

# 使用例
status = check_health()
health = is_healthy(status)
if not health["healthy"]:
    print(f"Issues detected: {health['issues']}")

フルシステム状態

def get_full_state():
    """完全なシステムスナップショットを取得します。"""
    req = urllib.request.Request(f"{ASIAI_URL}/api/snapshot")
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read())

def get_history(hours=24):
    """過去のメトリクスを取得します。"""
    req = urllib.request.Request(f"{ASIAI_URL}/api/history?hours={hours}")
    with urllib.request.urlopen(req, timeout=10) as resp:
        return json.loads(resp.read())

# パフォーマンストレンドの検出
history = get_history(hours=6)
points = history["points"]
if len(points) >= 2:
    recent_gpu = points[-1].get("gpu_utilization_percent", 0)
    earlier_gpu = points[0].get("gpu_utilization_percent", 0)
    if recent_gpu > earlier_gpu * 1.5:
        print("GPU utilization trending up significantly")

ベンチマークカード（共有可能な画像）

CLIで共有可能なベンチマークカード画像を生成できます：

asiai bench --card                    # SVGをローカルに保存（依存関係ゼロ）
asiai bench --card --share            # SVG + PNG（コミュニティAPI経由）
asiai bench --quick --card --share    # クイックベンチ + カード + 共有（約15秒）

モデル、チップ、エンジン比較バーチャート、勝者ハイライト、メトリクスチップを含む1200x630のダークテーマカードです。Reddit、X、Discord、GitHub READMEに最適化されています。

カードはSVGとして ~/.local/share/asiai/cards/ に保存されます。--share を追加すると、PNGダウンロードと共有可能なURLが取得できます — PNGはReddit、X、Discordへの投稿に必要です。

MCP経由

run_benchmark MCPツールは card パラメータでカード生成をサポートします：

{"tool": "run_benchmark", "arguments": {"model": "qwen3.5", "card": true}}

レスポンスには card_path が含まれます — MCPサーバーファイルシステム上のSVGファイルへの絶対パスです。

Webhookアラート（プッシュ通知）

ポーリングの代わりに、状態変化が発生した際にasiai がプッシュ通知を送信するよう設定できます：

# Webhookを追加（Slack、Discord、または任意のURL）
asiai alert add https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# アラートのトリガー：
# - エンジンの停止 / 復帰
# - メモリプレッシャーの遷移（normal → warn → critical）
# - サーマルスロットリングの検出

アラートは遷移時のみ発火し（毎回のチェックではなく）、フラッディング防止のため5分間のクールダウンがあります。継続的なポーリングなしにインフラストラクチャの変化に対応する必要があるスウォームオーケストレーターに最適です。

アラートの一覧と削除：asiai alert list、asiai alert remove <id>。

エージェントの識別

REST APIリクエストにエージェントを識別する User-Agent ヘッダーを含めることを推奨します：

User-Agent: asiai-agent/<framework>/<version>

例：

  • User-Agent: asiai-agent/openclaw/1.2.0
  • User-Agent: asiai-agent/crewai/0.5
  • User-Agent: asiai-agent/custom-orchestrator/1.0

これは必須ではありません — User-Agentヘッダーなしのリクエストも正常に動作します。ただし、以下の点で役立ちます：

  • デバッグ — ログでエージェントリクエストとブラウザアクセスを区別
  • エージェント別分析 — どのエージェントがAPIにアクセスし、頻度やエンドポイントを把握
  • マルチエージェント環境 — 複数のエージェントが同じasiai インスタンスを共有する際の識別

MCPクライアントの場合、識別は自動的です（MCPプロトコルにクライアントメタデータが含まれます）。

エージェント登録（オプション）

登録は完全に任意です — asiai は登録なしで完全に動作します。デフォルトではテレメトリやフォンホームは一切ありません。

登録を選択すると、asiai エージェントネットワークに参加できます：1回のAPI呼び出し、メール不要、個人データ不要 — ハードウェア情報のみです。

curl -X POST https://api.asiai.dev/api/v1/agent-register \
  -H "Content-Type: application/json" \
  -d '{
    "chip": "Apple M4 Pro",
    "ram_gb": 64,
    "engines": ["ollama", "lmstudio"],
    "framework": "my-agent",
    "asiai_version": "1.0.1"
  }'

レスポンス：

{
  "status": "registered",
  "agent_id": "a1b2c3d4e5f6",
  "agent_token": "secret_...",
  "total_agents": 42
}

agent_id と agent_token を ~/.local/share/asiai/agent.json に安全に保存してください。コミュニティAPI呼び出しやベンチマーク提出に必要です。

登録で解放される機能

機能 agent_idなし agent_idあり
ローカルbench/monitor/web はい はい
/api/status、/api/snapshot はい はい
--share ベンチマーク いいえ はい
asiai compare（コミュニティ） いいえ はい
asiai recommend --community いいえ はい
パーセンタイル統計 いいえ はい
エージェントディレクトリ（同じチップのピアを検索） いいえ はい
パフォーマンスアラート（新エンジンがあなたを上回る） いいえ 近日公開

ハートビート

定期的なハートビートで登録をアクティブに保ちます：

curl -X POST https://api.asiai.dev/api/v1/agent-heartbeat \
  -H "Content-Type: application/json" \
  -H "X-Agent-Id: a1b2c3d4e5f6" \
  -H "X-Agent-Token: secret_..." \
  -d '{
    "engines": ["ollama", "lmstudio"],
    "version": "1.0.1",
    "models_loaded": 3,
    "uptime_hours": 72
  }'

プライバシー

  • IPアドレスの保存なし — IPはレート制限にのみ使用され、エージェントレジストリには保存されません
  • 個人データなし — ハードウェア情報（チップ、RAM）、エンジン名、フレームワーク名のみ
  • オプトインのみ — 明示的に登録しない限り、asiai はフォンホームしません
  • トークンセキュリティ — agent_token は保存前にハッシュ化（SHA-256）されます；プレーンテキストは登録時に一度だけ返されます
  • レート制限データ — レート制限テーブルのIPハッシュ（日替わりソルトのSHA-256）は30日後に自動的に削除されます

FAQ

Q: asiai にはroot/sudo権限が必要ですか？ A: いいえ。GPU可観測性は ioreg（権限不要）を使用します。電力メトリクス（ベンチマークの --power フラグ）は sudo powermetrics を必要としますが、これはオプションです。

Q: APIのレスポンスタイムは？ A: /api/status は500ms未満で応答します（10秒キャッシュ）。/api/snapshot は1〜3秒かかります（全エンジンからライブデータを収集）。

Q: asiai をLinuxで実行できますか？ A: いいえ。asiai はmacOS Apple Silicon専用です。sysctl、vm_stat、ioreg、launchd など、すべてmacOS固有のAPIを使用しています。

Q: 複数のMacを監視するには？ A: 各Macで asiai daemon start web --host 0.0.0.0 を実行してください。Prometheusで /api/metrics をスクレイプし、Grafanaで可視化します。

Q: エンジンがクラッシュした場合は？ A: asiai はエンジン障害を自動的に検出します。診断には asiai doctor を使用してください。自動通知のために asiai alert add でWebhookアラートを設定できます。