amrouter

AI エージェント向け AMRouter スキル

セルフホスト可能な AI ゲートウェイ：単一のエンドポイントで複数のプロバイダーに対応し、自動フォールバックします。

AMRouter は OpenAI 互換の API ゲートウェイです。自動ロードバランシング、フォールバック、コスト最適化を備え、数十種類の LLM、埋め込み、画像、音声プロバイダーにリクエストを振り分けます。プロバイダーに依存せず、エージェントが複数のプロバイダーによる AI インフラにアクセスできるよう設計されています。

---

クイックリンク

• 公式サイト： https://github.com/ahwanulm/AMRouter
• ドキュメント： https://github.com/ahwanulm/AMRouter/tree/main/docs
• 機能： 複数プロバイダーへのルーティング、自動フォールバック、Cloudflare Workers AI、OpenAI 互換 REST API

---

AMRouter とは？

AMRouter v2 は 9Router を書き直したもので、各機能を明確に分離しています。

• Express バックエンド — 50 種類以上の LLM、埋め込み、画像、音声、ユーティリティプロバイダーへリクエストを振り分けます
• Vite + React フロントエンド — プロバイダー、接続、プロキシプール、CLI ツール、自動化を管理するダッシュボードです
• OpenAI 互換 API — /v1/chat/completions、/v1/embeddings、/v1/images/generations、/v1/audio/speech などに対応するクライアントで利用できます

主な機能

✅ 複数プロバイダーへのルーティング — Cloudflare Workers AI、OpenAI、Anthropic Claude、Google Gemini、Groq、Mistral、Cohere、Voyage、GitHub など、40 種類以上に対応
✅ 自動フォールバックの組み合わせ — プロバイダーチェーン（例：vip、budget、openai-only）を定義すると、ルートが自動的に切り替わります
✅ コスト最適化 — プロバイダーごとにクォータを追跡し、トークンカウンターを使ってコストを見積もります
✅ Cloudflare Workers AI の自動化 — Playwright + 2Captcha + 一時メールを使って、アカウントを自動登録し、キーを抽出します
✅ ダッシュボード UI — プロバイダー、接続、自動化を管理し、ログとメトリクスを確認できます
✅ エージェントスキル — Claude、Gemini、その他の AI コーディングエージェント向けの、すぐに使える SKILL.md ファイルを提供します
✅ OpenAI SDK 互換 — OpenAI npm クライアント、Python クライアント、または任意の REST クライアントで利用できます

---

使用する場面

✅ 次のような場合は AMRouter を使用してください。

• 複数プロバイダーへのアクセスを単一の API エンドポイントに集約したい
• プロバイダーが失敗したり、クォータを使い切ったりしたときの自動フォールバックが必要
• プロバイダー間のコストを追跡したい（クォータ制限、トークン数のカウント）
• 複数の LLM モデルを運用し、統一されたインターフェースが必要
• エージェントインフラを構築しており、プロバイダーを簡単に切り替えたい
• Cloudflare Workers AI の自動化（自動登録、キー抽出）を利用したい
• セルフホスト可能なソリューションが必要（ベンダー管理のブロッカー回避サービスではないもの）

❌ 次のような場合は AMRouter を使用しないでください。

• プロバイダーが 1 つだけ必要（その SDK を直接使用してください）
• Node.js バックエンドを実行できない
• フォールバックや複数プロバイダーのオーケストレーションが不要
• Anthropic の API のようなマネージドサービスを直接使いたい

---

インストールとセットアップ

Step 1: 要件

• Node.js 20+
• Python 3.10+（自動化機能用）
• Chromium（Playwright による自動化用。任意）

Step 2: インストール

git clone https://github.com/ahwanulm/AMRouter.git
cd AMRouter
npm install

Step 3: 環境を設定する

cp backend/.env.template backend/.env

主な環境変数：

変数	説明	例
PORT	バックエンドサーバーのポート	3001
REQUIRE_LOGIN	認証を有効にする	true
JWT_SECRET	JWT 署名用のシークレット	（ランダムな文字列を生成）
ADMIN_PASSWORD	ダッシュボード管理者のパスワード	（安全な値を設定）
OPENAI_API_KEY	OpenAI プロバイダーのキー	（任意）
ANTHROPIC_API_KEY	Anthropic プロバイダーのキー	（任意）
GOOGLE_API_KEY	Google Gemini のキー	（任意）

Step 4: 開発

npm run dev          # Start backend + frontend concurrently
npm run backend      # Backend only (port 3001)
npm run frontend     # Frontend only (port 5177)

Step 5: 本番環境

cd frontend && npm run build
cd ..
NODE_ENV=production npm start

サーバーはポート 3001 で実行されます（変更可能）。フロントエンドは backend/public/ にビルドされます。

---

基本概念

1. プロバイダー

プロバイダーとは、LLM、埋め込み、画像、または音声のサービス（OpenAI、Anthropic、Gemini など）です。

各プロバイダーには次の項目があります。

• キー／API 認証情報 — ダッシュボードから管理します
• モデル — 個別のモデル ID（例：openai/gpt-4o、anthropic/claude-3-opus）
• クォータ — トークン数またはリクエスト数の任意の上限
• 優先度 — フォールバックチェーンで使用されます

2. コンボ（フォールバックチェーン）

コンボは、名前付きのプロバイダーのチェーンです。コンボ名 vip を指定して /v1/chat/completions を呼び出すと、次の順に試行します。

1. プロバイダー A
2. A が失敗するか、クォータを超過した場合 → プロバイダー B
3. B が失敗した場合 → プロバイダー C
4. 以下同様

コンボ設定の例：

{
  "name": "vip",
  "providers": ["openai", "anthropic", "gemini"],
  "strategy": "round-robin"
}

3. OpenAI 互換 API

AMRouter は OpenAI と同じエンドポイントを公開します。

エンドポイント	モデル	例
POST /v1/chat/completions	チャットモデル	openai/gpt-4o、anthropic/claude-3-opus
POST /v1/embeddings	埋め込みモデル	openai/text-embedding-3-small、gemini/text-embedding-004
POST /v1/images/generations	画像モデル	openai/dall-e-3、openai/dall-e-2
POST /v1/audio/speech	TTS モデル	openai/tts-1、elevenlabs/eleven_monolingual_v1
POST /v1/audio/transcriptions	STT モデル	openai/whisper-1
GET /v1/models	すべてのモデルを一覧表示	{data: [...]} を返します

---

使用パターン

パターン 1：OpenAI SDK 経由のエージェントチャット

AMRouter を OpenAI SDK のドロップイン置き換えとして使用します。

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: `${process.env.AMROUTER_URL}/v1`,
  apiKey: process.env.AMROUTER_KEY || "any-value",
});

const res = await client.chat.completions.create({
  model: "openai/gpt-4o",  // or combo name like "vip"
  messages: [{ role: "user", content: "What is 2+2?" }],
  stream: true,
});

for await (const chunk of res) {
  process.stdout.write(chunk.choices[0]?.delta?.content || "");
}

パターン 2：コンボベースのフォールバック

ダッシュボードでフォールバックコンボを定義します。エージェントは 1 つのリクエストを送信します。

curl -X POST ${AMROUTER_URL}/v1/chat/completions \
  -H "Authorization: Bearer ${AMROUTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "budget",
    "messages": [{"role": "user", "content": "Summarize this article..."}]
  }'

AMRouter は Groq → Mistral → Gemini の順に自動で試行します（すべてコスト追跡付き）。

パターン 3：RAG 用の埋め込み

const embeddings = await fetch(`${AMROUTER_URL}/v1/embeddings`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${AMROUTER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/text-embedding-3-small",
    input: ["Document chunk 1", "Document chunk 2"],
  }),
});

const { data } = await embeddings.json();
console.log(data[0].embedding);  // Vector (1536 dims)

パターン 4：画像生成

curl -X POST ${AMROUTER_URL}/v1/images/generations \
  -H "Authorization: Bearer ${AMROUTER_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/dall-e-3",
    "prompt": "A futuristic city at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

パターン 5：コスト追跡とクォータ

クォータのエンドポイントを照会します。

curl ${AMROUTER_URL}/api/quota/providers \
  -H "Authorization: Bearer ${AMROUTER_KEY}" | jq '.[]'

出力：

[
  {
    "provider": "openai",
    "quotaLimit": 100000,
    "quotaUsed": 45230,
    "quotaRemaining": 54770,
    "costUSD": 12.45
  },
  ...
]

---

エージェントとの統合

deep-agents-core との連携

AMRouter をカスタムツールとして登録します。

const agentTools = {
  amrouter_chat: {
    description: "Call any LLM via AMRouter (OpenAI/Anthropic/Gemini/Groq combo fallback)",
    input_schema: {
      type: "object",
      properties: {
        model: { type: "string", description: "Provider/combo (openai/gpt-4o, anthropic/claude-3, budget)" },
        messages: { type: "array", description: "Chat messages" },
        temperature: { type: "number", description: "0–2 (default 1)" },
      },
      required: ["model", "messages"],
    },
  },
  amrouter_embeddings: {
    description: "Generate embeddings via OpenAI/Gemini/Voyage models",
    input_schema: {
      type: "object",
      properties: {
        model: { type: "string", description: "openai/text-embedding-3-small, gemini/text-embedding-004, voyage/voyage-large-2" },
        input: { type: "string", description: "Text to embed" },
      },
      required: ["model", "input"],
    },
  },
};

research スキルとの連携

複数モデルへのクエリを並列化します。

# Search across multiple LLM models simultaneously
amrouter-query "Explain quantum computing" \
  --models openai/gpt-4o,anthropic/claude-3-opus,gemini/gemini-2-flash \
  --parallel \
  --compare

環境変数の使用

.env に設定します。

AMROUTER_URL=http://localhost:3001
AMROUTER_KEY=sk-amrouter-xxx

次に、エージェントのコードで使用します。

const AMROUTER_URL = process.env.AMROUTER_URL;
const AMROUTER_KEY = process.env.AMROUTER_KEY;

// Use in OpenAI SDK as shown above

---

よくあるタスク

タスク 1：利用可能なプロバイダーを一覧表示する

curl ${AMROUTER_URL}/v1/models \
  -H "Authorization: Bearer ${AMROUTER_KEY}" | jq '.data[].id'

# Output:
# openai/gpt-4o
# openai/gpt-4-turbo
# anthropic/claude-3-opus-20240229
# google/gemini-2-flash
# groq/mixtral-8x7b-32768
# ...

タスク 2：すべてのプロバイダーのクォータを確認する

curl ${AMROUTER_URL}/api/quota/providers \
  -H "Authorization: Bearer ${AMROUTER_KEY}" | jq '.'

タスク 3：コストを最適化するコンボを作成する

ダッシュボードで以下を行います。

1. Providers タブに移動します
2. New Combo をクリックします
3. 名前：budget
4. プロバイダーを追加します：Groq、Mistral、Llama 2（フォールバック順）
5. 保存します

その後、エージェントは次のように使用できます。

curl -X POST ${AMROUTER_URL}/v1/chat/completions \
  -H "Authorization: Bearer ${AMROUTER_KEY}" \
  -d '{"model":"budget","messages":[...]}'

タスク 4：レスポンスをストリーミングする

const res = await fetch(`${AMROUTER_URL}/v1/chat/completions`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${AMROUTER_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/gpt-4o",
    messages: [{ role: "user", content: "Write a poem" }],
    stream: true,
  }),
});

const reader = res.body.getReader();
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = new TextDecoder().decode(value);
  const lines = text.split("\n");
  for (const line of lines) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      process.stdout.write(data.choices[0]?.delta?.content || "");
    }
  }
}

---

ベストプラクティス

1. 可用性を高めるためにコンボを使用する

プロバイダーをハードコードする代わりに、次のようにします。

// ❌ Avoid: single provider, no fallback
model: "openai/gpt-4o"

// ✅ Prefer: fallback combo
model: "vip"  // Falls back through multiple providers automatically

2. クォータ制限を守る

大きなリクエストを送信する前に、残りのクォータを確認します。

const quota = await fetch(`${AMROUTER_URL}/api/quota/providers`).then(r => r.json());
const gpt4oQuota = quota.find(q => q.provider === "openai");
if (gpt4oQuota.quotaRemaining < 10000) {
  console.log("Switching to budget model");
  model = "budget";  // Fallback to cost-optimized combo
}

3. 埋め込みをキャッシュする

埋め込みの結果を再利用します。

const embeddingCache = new Map();

async function getEmbedding(text) {
  if (embeddingCache.has(text)) return embeddingCache.get(text);
  
  const res = await fetch(`${AMROUTER_URL}/v1/embeddings`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${AMROUTER_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ model: "openai/text-embedding-3-small", input: text }),
  });
  const { data } = await res.json();
  const embedding = data[0].embedding;
  
  embeddingCache.set(text, embedding);
  return embedding;
}

4. 長いレスポンスをストリーミングする

長いコンテンツを生成するエージェントでは、ストリーミングを使用します。

// Stream large code generation
const res = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [...],
  stream: true,  // ✅ Use streaming
});

5. プロバイダーとコストを記録する

各リクエストを処理したプロバイダーを追跡します。

// Extend logging with provider info
const res = await fetch(`${AMROUTER_URL}/v1/chat/completions`, {
  method: "POST",
  headers: { "Authorization": `Bearer ${AMROUTER_KEY}`, "Content-Type": "application/json" },
  body: JSON.stringify({ model: "vip", messages: [...] }),
});

const data = await res.json();
console.log(`Provider: ${data.provider_used || 'unknown'}`);  // If AMRouter returns it
console.log(`Cost: $${data.estimated_cost || 'N/A'}`);

---

パフォーマンスとコスト

実測ベンチマーク（単一プロバイダーの構成との比較）：

シナリオ	コスト削減	速度	メリット
高トラフィック時のフォールバック	45～67%	2～8 倍高速（失敗を回避）	クォータ制限時に、より安価なプロバイダーへ自動で切り替えます
並列推論	35～52%	3～5 倍（キューに入った負荷）	複数のプロバイダーに分散します
コンボチェーン（3 プロバイダー）	40～60%	1～2 倍（セットアップのオーバーヘッド）	常に利用可能で、API エンドポイントは 1 つです

---

トラブルシューティング

問題	対処方法
401 Unauthorized	AMROUTER_KEY を確認し、Bearer トークンの形式が Authorization: Bearer ${KEY} であることを確認します
503 Service Unavailable	すべてのフォールバックプロバイダーが失敗しました。ダッシュボードでクォータとプロバイダー設定を確認します
Model not found	curl ${AMROUTER_URL}/v1/models を実行して、利用可能なモデルを確認します
CORS errors	バックエンドに Access-Control-Allow-Origin: * を追加するか、特定のオリジンを許可するよう設定します
バックエンドが起動しない	.env ファイルを確認し、NODE_ENV が設定されていることと、ポートが競合していないことを確認します
埋め込みの次元数が一致しない	モデルによって次元数が異なります（OpenAI：1536、Gemini：768）。ベクトルと一緒にモデル名を保存します。

---

デプロイ

Docker

FROM node:20-alpine
WORKDIR /app
COPY . .
RUN npm install
RUN cd frontend && npm run build
CMD ["npm", "start"]

docker build -t amrouter .
docker run -p 3001:3001 --env-file .env amrouter

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: amrouter
spec:
  replicas: 3
  selector:
    matchLabels:
      app: amrouter
  template:
    metadata:
      labels:
        app: amrouter
    spec:
      containers:
      - name: amrouter
        image: amrouter:latest
        ports:
        - containerPort: 3001
        env:
        - name: PORT
          value: "3001"
        - name: ADMIN_PASSWORD
          valueFrom:
            secretKeyRef:
              name: amrouter-secrets
              key: admin-password

環境変数（本番環境）

PORT=3001
NODE_ENV=production
REQUIRE_LOGIN=true
JWT_SECRET=<random-256-bit-hex>
ADMIN_PASSWORD=<strong-password>
CORS_ORIGIN=https://yourdomain.com
LOG_LEVEL=info

---

エージェントスキルとの統合

スキル	使用例
deep-agents-core	AMRouter のエンドポイントをカスタム LLM ツールとして登録します
research	AMRouter 内の複数のモデルにクエリを並行して実行します
crewai-multi-agent	マルチエージェントのオーケストレーションで、AMRouter を共有 LLM バックエンドとして使用します
openrlhf-training	RLHF のファインチューニング中の推論に AMRouter を使用します
langgraph-human-in-the-loop	AMRouter のコンボチェーン経由で LangGraph の LLM 呼び出しをルーティングします

---

ライセンス

AMRouter はオープンソースです。ライセンスの詳細については、GitHub をご覧ください。

---

使用技術： Node.js + Express（バックエンド）、Vite + React（フロントエンド）、OpenAI 互換 API
最終更新日： 2026年7月 — AMRouter v2.0+ の内容を反映