IdentArk Gateway

identark

AgentGateway Protocol — 安全でスケーラブルな AI エージェント実行インフラストラクチャです。

---

課題

AI エージェントがコードを実行したり、API を呼び出したり、ファイルにアクセスしたりできる場合、エージェントはプロセス内で動作します。そのプロセスには環境があります。通常、その環境には重大な被害につながり得るあらゆるもの、たとえば LLM の API キー、データベースの認証情報、AWS トークンが含まれています。

単純な解決策として、エージェントを REST API と同じバックエンドで実行すると、2 つの問題が同時に発生します。

1. セキュリティ：エージェントがマシン上のあらゆるシークレットにアクセスできます。
2. 信頼性：メモリを大量に消費するエージェントによって API のパフォーマンスが低下します。API を再デプロイすると、実行中のエージェントがすべて停止します。

identark はこの両方を解決します。

---

仕組み

SDK は AgentGateway Protocol を実装しています。これは、エージェントのロジックと外部環境をつなぐシンプルなインターフェースです。すぐに使える実装が 2 つ用意されています。

Gateway	使用場面	認証情報	履歴
DirectGateway	ローカル開発、CI 評価	お使いの API キー	メモリ内
ControlPlaneGateway	IdentArk 上の本番環境	ゼロ — エージェント内にありません	コントロールプレーンの DB

どちらの環境でも、エージェントのコードは同一です。切り替えは 2 行で完了します。

---

クイックスタート

pip install identark[openai]

import asyncio
from openai import AsyncOpenAI
from identark import DirectGateway, Message, Role

async def main():
    gateway = DirectGateway(
        llm_client=AsyncOpenAI(),   # Your API key — not in the agent loop
        model="gpt-4o",
    )

    response = await gateway.invoke_llm(
        new_messages=[Message(role=Role.USER, content="Hello, IdentArk!")]
    )

    print(response.message.content)
    print(f"Cost: ${response.cost_usd:.6f}")

asyncio.run(main())

本番環境への移行

2 行を変更します。エージェントのロジックには手を加えません。

# Before (local)
from identark import DirectGateway
gateway = DirectGateway(llm_client=AsyncOpenAI(), model="gpt-4o")

# After (production — agent holds zero secrets)
from identark import ControlPlaneGateway
gateway = ControlPlaneGateway()  # auto-detects env vars inside a IdentArk sandbox

ガバナンス対象のアクション（支払い、支払いリンク、返金）

エージェントはコントロールプレーンにアクションの実行を依頼します。プロバイダーのキー（Stripe、Paystack、 GitHub、AWS）は IdentArk 内に保持されます。何らかの処理を実行する前に、許可、予算、人による承認が適用され、 同じ冪等性キーが再利用されても、アクションが二重に実行されることはありません。

request = await gateway.request_capability(
    "payments.payment_link.create",
    "paystack",
    {"amount_minor": 1_500_000, "currency": "NGN",
     "customer_email": "[email protected]", "reference": "order-1001"},
    idempotency_key="order-1001-link",
)
# "succeeded" returns the checkout link; "pending_approval" waits for a person.
execution = await gateway.get_capability_execution(request["request_id"])

---

インストール

# Core SDK only
pip install identark

# With OpenAI support
pip install identark[openai]

# With Anthropic support
pip install identark[anthropic]

# With Google Gemini support
pip install identark[gemini]

# With Mistral AI support (EU provider)
pip install identark[mistral]

# All cloud providers
pip install identark[all]

要件： Python 3.10 以降

TypeScript をお使いですか？同等機能を備えた SDK は、ランタイム依存関係がゼロの identark npm package として提供されています。同じ AgentGateway コントラクトと構造化された認証情報セッションを備えています。

---

データ主権

IdentArk は、データを英国または EU 内に保持するプロバイダーを含め、あらゆる LLM プロバイダーと連携できるよう、最初から設計されています。AgentGateway Protocol によって、エージェントのロジックが推論プロバイダーから切り離されているため、プロバイダーの切り替えに必要な変更は1 行です。

Ollama で完全ローカルに実行する（データの外部送信なし）

from openai import AsyncOpenAI
from identark import DirectGateway

gateway = DirectGateway(
    llm_client=AsyncOpenAI(
        base_url="http://localhost:11434/v1",
        api_key="ollama",
    ),
    model="llama3.2",
    provider="local",   # forces $0 cost tracking; inference stays on your machine
)

Ollama をインストールします：brew install ollama && ollama pull llama3.2 && ollama serve

Mistral AI を使用する（EU データレジデンシー）

from openai import AsyncOpenAI
from identark import DirectGateway

gateway = DirectGateway(
    llm_client=AsyncOpenAI(
        base_url="https://api.mistral.ai/v1",
        api_key="your-mistral-api-key",
    ),
    model="mistral-small-latest",   # auto-detected as "mistral" provider
)

Mistral AI はフランスの企業です。すべての推論は EU のデータセンターで実行され、EU のデータ保護法（GDPR）の適用対象となります。英国または EU のデータガバナンス要件により、米国を拠点とするクラウドプロバイダーへの推論トラフィックの送信が禁じられている場合にご利用ください。

実行可能なスクリプトの完全な例は examples/ をご覧ください。

---

AgentGateway Protocol

次の 4 つの非同期メソッドを実装するクラスは、いずれも有効なゲートウェイです。

class AgentGateway(Protocol):
    async def invoke_llm(self, new_messages, tools=None, tool_choice="auto") -> LLMResponse: ...
    async def persist_messages(self, messages) -> None: ...
    async def request_file_url(self, file_path, method="PUT") -> PresignedURL: ...
    async def get_session_cost(self) -> float: ...

このプロトコルに沿ってエージェントを作成します。実装がローカルか本番かは、実行時の詳細にすぎません。

---

機能

• シークレット不要のエージェント — ControlPlaneGateway は API キー、データベース認証情報、クラウドトークンを保持しません
• ステートレス設計 — 会話履歴はエージェントではなくゲートウェイが管理します。データを失わずに停止・再起動できます
• フレームワーク非依存 — LangChain、LlamaIndex、生の API 呼び出し、または任意のカスタムエージェントフレームワークで動作します
• コスト追跡機能を内蔵 — すべての invoke_llm 呼び出しは cost_usd を返し、get_session_cost() は累積合計を返します
• OpenAI と Anthropic — どちらのプロバイダーも DirectGateway ですぐに利用できます
• テスト用の MockGateway — テストスイートで LLM を呼び出す必要はありません。アサーション用にすべての呼び出しを記録できます
• 完全な型注釈 — py.typed マーカーを備えており、mypy の strict モードで動作します

---

エージェントのテスト

from identark.testing import MockGateway
from identark.models import LLMResponse, Message, Role

async def test_my_agent():
    mock = MockGateway()
    mock.queue_response(LLMResponse(
        message=Message(role=Role.ASSISTANT, content="The answer is 42."),
        cost_usd=0.001,
        model="mock",
        finish_reason="stop",
    ))

    result = await my_agent(gateway=mock)

    assert mock.invoke_llm_call_count == 1
    assert mock.total_messages_sent == 1

---

対応プロバイダー

プロバイダー	データの保存場所	DirectGateway	GeminiGateway	ControlPlaneGateway
OpenAI（gpt-4o、gpt-4o-mini、…）	米国	✓	—	✓
Anthropic（Claude モデル）	米国	✓	—	✓
Google Gemini	プロバイダーによって異なります	✓*	✓	ロードマップ
Mistral AI	プロバイダーによって異なります	✓	—	✓
Kimi / Moonshot	プロバイダーによって異なります	✓*	—	✓
Azure OpenAI	設定した Azure リージョン	✓*	—	✓
AWS Bedrock	設定した AWS リージョン	—	—	✓
OpenRouter	プロバイダーによって異なります	✓*	—	✓
Ollama	ローカル 🏠	✓	—	ホスト型ルートではありません
OpenAI 互換エンドポイント全般	プロバイダーによって異なります	✓	—	✓（カスタムエンドポイント）

*OpenAI 互換のクライアント／ベース URL 経由です。ネイティブ Gemini SDK の機能を使用する場合は、GeminiGateway を使用してください。

---

エラー処理

from identark.exceptions import CostCapExceededError, RateLimitError, IdentArkError

try:
    response = await gateway.invoke_llm(new_messages=[...])
except CostCapExceededError as e:
    print(f"Cost cap of ${e.cap_usd} reached. Spent: ${e.consumed_usd}")
except RateLimitError as e:
    await asyncio.sleep(e.retry_after_seconds)
except IdentArkError as e:
    # Catch-all for any SDK error
    raise

例外階層全体：IdentArkError > GatewayError > ControlPlaneError > AuthenticationError | CostCapExceededError | SessionNotFoundError

---

アーキテクチャ

┌─────────────────────────────────────┐
│            Your Agent Code          │
│   (depends only on AgentGateway)    │
└──────────────┬──────────────────────┘
               │
    ┌──────────▼──────────┐
    │    AgentGateway      │  ← Protocol (interface)
    │      Protocol        │
    └──────┬────────┬──────┘
           │        │
  ┌────────▼─┐  ┌───▼──────────────┐
  │  Direct  │  │  ControlPlane    │
  │ Gateway  │  │    Gateway       │
  │          │  │                  │
  │ Local /  │  │   Production     │
  │  Evals   │  │  (zero secrets)  │
  └──────────┘  └────────┬─────────┘
                         │ HTTP
                ┌────────▼─────────┐
                │  IdentArk        │
                │  Control Plane   │
                │  (holds creds)   │
                └──────────────────┘

---

コミュニティ

• ディスカッション：GitHub Discussions — 質問やアイデアを共有できます
• イシュー：GitHub Issues — バグ報告や機能リクエストはこちら
• ライブデモ：identark.io/demo — ブラウザーで IdentArk をお試しください

---

コントリビューション

コントリビューションを歓迎します。大きな変更を提出する前に、イシューを作成してください。

git clone https://github.com/identark/identark.git
cd identark
pip install -e ".[dev]"
pre-commit install
pytest tests/unit/

詳しいガイドラインについては、CONTRIBUTING.md をご覧ください。

---

ロードマップ

• LangChain アダプター（IdentArkChatModel）
• LlamaIndex アダプター（IdentArkLLM）
• ストリーミング対応（invoke_llm_stream）
• CrewAI との統合
• LangGraph との統合（IdentArkNode、IdentArkStreamNode）
• プラグイン可能な推論バックエンド（分散コンピューティング）
• ワンコマンドでコントロールプレーンをデプロイする identark-cli

---

ライセンス

IdentArk SDK は MIT License のもとでライセンスされています。商用プロジェクトやクローズドソースプロジェクトを含め、あらゆる用途で無料で利用できます。LICENSE をご覧ください。

IdentArk コントロールプレーン（ホスト型サービス）はプロプライエタリです。SDK は、完全にセルフホスト可能なものを含む、あらゆる AgentGateway バックエンドで動作します。

---

Built on the control plane pattern described in How We Built Secure, Scalable Agent Sandbox Infrastructure.