tierproxy

tierproxy — Python SDK

🚧 プレビューリリース。 ゲートウェイはまだ一般提供されていません。[email protected] からウェイトリストにご登録ください。SDK は動作しますが、稼働中のゲートウェイに対する tierproxy doctor の実行には招待が必要です。

AI/ML パイプライン向けのプレミアムなマルチプロバイダープロキシインフラストラクチャです。コスト、レイテンシ、成功率を二度測定し、Python でコードを書くエンジニアのために構築されています。

インストール

pip install tierproxy

クイックスタート — 5 秒で試す

import tierproxy
r = tierproxy.get("https://example.com", country="US")
print(r.text)

以上です。（最初に TIERPROXY_API_KEY 環境変数を設定してください。）

3 行で永続セッションを作成

from tierproxy import TierProxy
with TierProxy() as g:
    print(g.me.get().client_id)
    r = g.get("https://example.com", country="US", session_id="s1")

リクエストごとに、健全なアップストリームの中から最も安価なものを自動選択

g = TierProxy(routing="cheapest")  # also: "fastest", "most_reliable", "balanced"
g.get("https://example.com")     # picks via /v1/health/upstreams under the hood

コストのガードレール

g = TierProxy(
    monthly_budget_usd=200.0,    # raises BudgetExceededError before going over
)

上級ユーザー向けの設定

import httpx
from tierproxy import TierProxy
from tierproxy.retry import RetryPolicy

g = TierProxy(
    api_key="tp_live_...",
    base_url="https://my-self-hosted-gw:8444",
    timeout=10.0,
    retry_policy=RetryPolicy(max_retries=5, retry_on_status=frozenset({500, 502})),
    http_client=httpx.Client(verify=False),  # custom transport
    user_agent_suffix="my-app/2.3",          # attribution
)

生のモード（Playwright、curl など）

from tierproxy import ProxyURL

p = ProxyURL(api_key="tp_live_...", country="US", mode="username_encoding")
print(p.http_url())  # http://customer-tp_live_...-cc-US:[email protected]:443

エラー処理

SDK のすべてのエラーは tierproxy.TierProxyError を継承し、サポートへの問い合わせに使える request_id を保持します。

from tierproxy import TierProxy, RateLimitError
import time

with TierProxy() as g:
    try:
        resp = g.get("https://example.com/page")
    except RateLimitError as e:
        time.sleep(e.retry_after or 5)
        resp = g.get("https://example.com/page")

HTTP ステータスと例外の対応表については、エラーリファレンスをご覧ください。

AI エージェントとの連携

SDK は、レスポンスモデルを JSON Schema として公開するほか、Anthropic Claude と OpenAI の関数呼び出し向けに、事前構築済みのツール定義も提供します。

import anthropic
from tierproxy import TierProxy, schemas

with TierProxy() as gw:
    anthropic.Anthropic().messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=schemas.anthropic_tools(),
        messages=[{"role": "user", "content": "How much quota is left?"}],
    )

AI 連携ガイドと、MCP サーバーの examples/mcp_claude_desktop.mdをご覧ください。

tierproxy の比較

	tierproxy	Smartproxy SDK	Bright Data SDK	Oxylabs SDK	DataImpulse
マルチプロバイダールーティング	✅	❌	❌	❌	❌
クライアント側のスマートセレクター（コストを考慮）	✅	❌	❌	❌	❌
使用状況のリアルタイムストリーミング（SSE）	✅	❌	❌	❌	❌
MCP サーバー（Claude/Cursor/Cline）	✅	❌	❌	❌	❌
OpenTelemetry を標準搭載	✅	❌	❌	❌	❌
同期・非同期の機能同等性	✅	一部	一部	一部	一部
AI/ML フレームワークのサンプルを同梱	8	0	1	0	0
型安全（Pydantic v2 + mypy strict）	✅	❌	❌	一部	❌
OpenAPI 3.1 仕様	✅	❌	❌	❌	❌
pip でインストール可能な CLI（tierproxy doctor）	✅	❌	❌	❌	❌
リクエストごとのコスト算出（遅延評価）	✅	❌	❌	❌	❌
JA3/JA4 TLS フィンガープリントローテーション	✅	❌	❌	❌	❌
レート制限の学習と自動フェイルオーバー	✅	❌	❌	❌	❌
ライセンス	Apache 2.0	プロプライエタリ	プロプライエタリ	プロプライエタリ	プロプライエタリ

機能

• 5秒で始められるクイックスタート — import tierproxy; tierproxy.get(url, country="US")
• 階層型 API — ワンライナーから上級者向けの調整項目まで、5段階の統合レベル
• スマートルーティング — routing="cheapest" で、リクエストごとに正常なアップストリームを自動選択
• コストのガードレール — monthly_budget_usd= により、予算を超えるリクエストを拒否
• リクエストごとのコスト計上 — client.cost_for(resp) が USD で返します。30秒の遅延キャッシュを使用し、リクエストごとのオーバーヘッドはありません
• クライアント側のレスポンスキャッシュ — cache_ttl=300, cache_max_response_size=262144 による、サイズ上限付き LRU キャッシュ
• 複数プロバイダー間の自動フェイルオーバー — auto_failover=True で、429/5xx の場合に次善のアップストリームへ再試行
• レート制限の学習 — client.rate_limits.get() で、ターゲットドメインごとにゲートウェイが集計した 429 を確認
• JA3/JA4 TLS ローテーション — アップストリームごとのフィンガープリントをランダム化（ゲートウェイ側。tls-fingerprint guide を参照）
• Cookie の永続化 — 複数ステップのクロールを通して、Cookie が session_id に保持されます
• ストリーミングレスポンス — client.get(url, stream=True) がイテレーターを返します（大容量ファイル、SSE）
• ライブ SSE ストリーム — for delta in g.usage.stream() で、月初から現在までのバイト数を逐次取得
• MCP サーバー — tierproxy-mcp により、プロキシを Claude/Cursor/Cline 向けのツールとして公開
• 8つのフレームワーク統合 — LangChain、LlamaIndex、Crawl4AI、Playwright、Firecrawl、Browser-Use、CrewAI
• OpenTelemetry のオプトイン — 分散トレーシングには pip install tierproxy[otel]
• 位置情報 + スティッキーセッション — 国、都市、1〜1440分のセッション固定
• 2種類の URL 構文 — ヘッダー（httpx/requests）とユーザー名エンコーディング（Playwright）
• エンドツーエンドの型安全性 — Pydantic v2 モデル、mypy strict、IDE の完全な自動補完

LangChain/LlamaIndex/Crawl4AI/Playwright の例については examples/ を、 各レベルを実行できるデモについては examples/levels.py を参照してください。

お好みの AI／エージェントフレームワークで使用する

フレームワーク	例	備考
LangChain	with_langchain.py	プロキシ経由の RAG ドキュメントローダー
LlamaIndex	with_llamaindex.py	プロキシ経由の SimpleWebPageReader
Crawl4AI	with_crawl4ai.py	Playwright クローラー + tierproxy
Firecrawl（注目）	with_firecrawl.py	セルフホストの Firecrawl + レジデンシャル IP
Browser-Use（注目）	with_browser_use.py	LLM 駆動の自律型ブラウザー
CrewAI（注目）	with_crewai.py	複数エージェントのスクレイパーチーム + コストを考慮したルーティング
Playwright	with_playwright.py	tierproxy を使用した直接的な Playwright
MCP（Claude/Cursor/Cline/Windsurf）（独自）	mcp_claude_desktop.md	tierproxy-mcp によるネイティブなツール統合

MCP サーバー（Claude Desktop / Cursor / Cline / Windsurf）

pip install tierproxy[mcp]

次に、MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "tierproxy": {
      "command": "tierproxy-mcp",
      "env": { "TIERPROXY_API_KEY": "tp_live_..." }
    }
  }
}

これで AI アシスタントは、fetch_url(url, country="US") を呼び出し、ヘルス状態や使用状況を確認して、正常なアップストリームの中から最も安価なものを経由してルーティングできます。接着コードも、httpx のインポートも、定型コードも不要です。