Alation AI Agent SDK

Alation AI Agent SDK

Alation AI Agent SDK を使用すると、AI エージェントが Alation Data Catalog のメタデータにアクセスし、活用できます。

概要

この SDK により、AI エージェントは次のことができます。

• Alation Data Catalog と簡単に連携する
• アセットのキュレーション、検索と検出、ロールベースのエージェント、データアナリストエージェントなどのユースケースに対応する
• 自然言語を使って関連するメタデータを検索する
• MCP などの AI フレームワークとシームレスに連携する

コンポーネント

このプロジェクトは、複数のコンポーネントで構成されています。

• コア SDK - API クライアントとコンテキストツールの基盤
• MCP 連携 - Model Context Protocol のサーバー実装
• LangChain 連携 - LangChain フレームワーク用のアダプター

コア SDK（alation-ai-agent-sdk）

コア SDK は、Alation API と連携するための基盤を提供します。認証、リクエストのフォーマット、レスポンスの解析を処理します。

コア SDK の詳細を見る

LangChain 連携（alation-ai-agent-langchain）

このコンポーネントは SDK を LangChain フレームワークと連携させ、データカタログについて推論できる高度な AI エージェントを作成できます。

LangChain 連携の詳細を見る

MCP 連携（alation-ai-agent-mcp）

MCP 連携では、Alation のコンテキスト機能をあらゆる MCP クライアントに公開する、MCP 互換のサーバーを提供します。MCP クライアントへの直接接続に使う従来の STDIO モードと、ウェブアプリケーションや API 連携に使う HTTP モードの両方をサポートしています。

MCP 連携の詳細を見る

はじめに

前提条件

• Python 3.10 以上
• Alation Data Catalog インスタンスへのアクセス
• 有効なリフレッシュトークン、または client_id とシークレット。詳しくは認証ガイドを参照してください。

インストール

pip install uv

# Install the core SDK
uv pip install alation-ai-agent-sdk==1.0.0

# Install LangChain integration
uv pip install alation-ai-agent-langchain==1.0.0

# Install the MCP integration
uv pip install alation-ai-agent-mcp==1.0.0

使用方法

ライブラリを使用するには、Alation インスタンスの認証情報を設定する必要があります。ServiceAccountAuthParams を使用してください。

サービスアカウント認証（推奨）

from alation_ai_agent_sdk import AlationAPI, ServiceAccountAuthParams

# Initialize the SDK with Service Account Authentication
auth_params = ServiceAccountAuthParams(
    client_id="your_client_id",
    client_secret="your_client_secret"
)
alation_api = AlationAPI(
    base_url="https://your-alation-instance.com",
    auth_method="service_account",
    auth_params=auth_params
)

サービスアカウントの認証情報を取得できない場合（管理者のみ）、手順についてはユーザーアカウント認証ガイドを参照してください。

メジャーバージョン 1.x.x

2026年10月23日の更新

1.0.0 は Alation AI Agent SDK の最初の安定版リリースです。

• リクエストで Ai-Surface ヘッダー（デフォルトは sdk）を送信するようになりました。AgentSDKOptions(surface=...) を設定すると、連携元を識別できます
• MCP サーバーには certifi>=2026.10.19 が必要です。また、Docker イメージで OS の CA ストアを更新し、侵害された eMudhra 中間 CA を信頼対象から除外します
• 認証パラメーターオブジェクトの repr() ではシークレットがマスキングされます
• ストリーミングおよび非ストリーミングのレスポンスで、不正なペイロードや空のペイロードをより適切に処理するようになりました

2026年1月2日の更新

破壊的変更：

• 削除されたツール：update_catalog_asset_metadata と check_job_status が SDK から削除されました

この機能が必要な場合は、Alation REST API を直接使用してください。基盤となる API エンドポイント（/integration/v2/custom_field_value/async/ と /api/v1/bulk_metadata/job/）は引き続き利用できます。詳しくはAlation Developer Portalを参照してください。

2025年12月10日 更新

Alation AI Agent SDK のバージョン 1.0.0rc2 が利用可能になりました。

より高機能な Catalog Context Search Agent を優先するため、Context Tool は非推奨になりました。実用面では、Catalog Context Search Agent は同じ契約を共有しているため、移行は簡単に行えるはずです。

移行期間として、非推奨となった Context Tool を今後3か月間SDK の一部として維持することを決定しました。つまり、2026年2月に削除される予定です。

Context Tool を削除する主な理由は、非常によく似た機能を持つツールが2つあることです。両方を LLM に公開すると、モデルは性能の低いほうを選ぶことが多く、結果の品質が低下します。概念的に重複するツールの数を減らすことで、誤ったツールの選択を防ぎます。

Catalog Context Search Agent は、Context Tool と同じ機能をすべて備えているだけでなく、Context Tool の使用時に大きなボトルネックとなっていた signature パラメーターを動的に構築するなど、さらに多くの機能を提供します。

同じ理由から、ローカル MCP サーバーも変更され、Context Tool、Analyze Catalog Question、Signature Create、Bulk Retrieval はデフォルトでは含まれなくなりました。Catalog Context Search Agent は、これらをスコープに含めなくても、必要に応じて内部で呼び出します。

これらの特定のツールを前提とするプロンプトがある場合は、有効にするツールを MCP サーバーに指定する必要があります（デフォルトのセットを上書きします）。これはコマンドライン引数または環境変数で指定できます。

注意：特定の用途に絞って使用する場合は、その用途に必要なツールだけを有効にしてください。

# As command line arguments to the MCP server command
--enabled-tools=alation_context,analyze_catalog_question,bulk_retrieval,generate_data_product,get_custom_fields_definitions,get_data_dictionary_instructions,data_product,get_signature_creation_instructions,catalog_context_search_agent,query_flow_agent,sql_query_agent

# Or as an environment variable
export ALATION_ENABLED_TOOLS='alation_context,analyze_catalog_question,bulk_retrieval,generate_data_product,get_custom_fields_definitions,get_data_dictionary_instructions,data_product,get_signature_creation_instructions,catalog_context_search_agent,query_flow_agent,sql_query_agent'

2025年11月4日 更新

Alation AI Agent SDK のバージョン 1.0.0rc1 が利用可能になりました。

重要：破壊的変更により、認証モードとして user_account はサポートされなくなりました。service_account または bearer_token モードへの移行をおすすめします。

新しいメジャーバージョンには、移行する価値のある、いくつかの注目すべき変更が含まれています。

• Alation Agent Studio との統合
• リモート MCP サーバー
• Catalog Search Context Agent
• ストリーミングと Chat ID のサポート

Alation Agent Studio との統合

Alation Agent Studio では、ビジネスに必要なエージェントを作成し、活用するための優れたサポートを利用できます。カタログのキュレーションの改善から、データ中心のクエリエージェントの構築まで、Agent Studio を使えば、エージェントの作成、調整、エンタープライズ全体へのデプロイを簡単に行えます。より複雑なシナリオの構成要素として、そのまま使用したり、組み合わせたりできる専門ツールも多数含まれています。また、作成した高精度エージェントは、SDK または MCP サーバー内でツールとして利用できます（custom_agent を参照）。

リモート MCP サーバー

SDK のインストールやアップグレードを行う負担を負わずに、MCP サーバーの柔軟性を利用したいという声が多くのお客様から寄せられています。リモート MCP サーバーを使えば、そうした作業は不要です。MCP に特化した認証設定を一度行えば、お気に入りの MCP クライアントに次のようなリモート MCP サーバーを追加するだけで利用できます：https://<your_instance>/ai/mcp

注意：MCP クライアントやプラットフォームは急速に進化しています。認証フローやパスパラメーターなどの扱いは、すべてのクライアントで同じようにサポートされているわけではありません。問題が発生した場合は、Issue を登録してください。調査のうえ、対応方針を検討します。動的なクライアント登録はサポートしていないため、client_id と client_secret を渡せる MCP クライアントを使用してください。

まずはこちら

リモート MCP サーバーが解決する課題のひとつは、ツールを動的に一覧表示することです。この動的な仕組みは、さまざまな場面で役立ちます。たとえば、現在のユーザーが利用できないツールを除外したり、SDK がまだ認識していない新しいツールを一覧表示したりできます。

また、ツールは静的ではなく遅延して解決されるため、ツールの API コントラクトも動的にできます。これにより、静的な統合で問題を引き起こす可能性がある、クライアントとサーバーのバージョン不一致を回避できます。

今後も SDK のサポートを継続し、定期的に新しいバージョンをリリースしますが、より壊れにくく堅牢な統合をお求めの場合は、出発点としてリモート MCP サーバーとの直接統合をご検討ください。

カタログ検索コンテキストエージェント

Agent SDK の初期には、ツールは Alation Context のひとつだけでした。特定の質問に最適に回答するため、適切なオブジェクトとそのプロパティを動的に選択できる強力な方法を提供していました。強力な signature パラメーターにより、ユーザーの質問がない場合（Bulk Retrieval）にも適していました。一方で、LLM が生成した signature パラメーターが無効だったり、まったく誤っていたりすることによる、かなりの摩擦も確認されました。また、signature をまったく指定しない利用も予想以上に多く、その場合はしばしば結果の質が低くなっていました。

こうした問題に対処するため、これらのツール（alation_context、bulk_retrieval）のコレクションから、必要に応じて一連のチェックとヒューリスティックを実行し、カスタムフィールドを活用するための signature を動的に作成するエージェントへ移行しました。これが新しい catalog_search_context_agent です。

これにより、ツール同士をうまく連携させるために必要な指示が減り、同時に呼び出しの精度も向上するはずです。

ストリーミングとチャット ID のサポート

ストリーミング

すべてのツールがストリーミングオプションをサポートするようになりました。主に、HTTP モードで動作するローカル MCP サーバーで役立ちます。MCP クライアントがストリーミングをサポートしている場合、ツールやエージェントの内部処理の一部が表示され、内部で何が行われているかをより把握しやすくなります。

デフォルトでは SDK のストリーミングは無効ですが、ユースケースに応じて有効にできます。有効にするには、AlationAIAgentSDK コンストラクターに sdk_options=AgentSDKOptions(enable_streaming=True) 引数を渡します。ストリーミング時は、内部のジェネレーターを正しく処理するために、結果をループ処理するか、そこから値を yield する必要があります。

チャット ID

ほとんどのツールとエージェントは、呼び出し時に chat_id パラメーターを受け付けます。このパラメーターを含めると、ツールの呼び出しは、同じ chat_id を参照する以前の呼び出しと関連付けられます。chat_id に対応するツールは、レスポンスに chat_id を含めます。

サポート対象のツール

• alation_context
• bulk_retrieval
• data_quality_tool
• get_custom_fields_definitions
• get_data_products
• get_data_sources_tool
• get_signature_creation_instructions
• lineage

サポート対象のエージェント

• catalog_context_search_agent
• custom_agent
• query_flow_agent
• sql_query_agent

ガイドとエージェントの例

一般

• 認証 - アクセス方法。
• ツール管理 - 特定のツールを有効または無効にする設定。

集約コンテキスト／一括取得ツール

• 統合の計画 - エージェントとAlation Data Catalogを最大限に活用するための実践的な検討事項です。
• シグネチャの使用 - 具体例を使ってエージェントをカスタマイズする方法です。
• サポートされているオブジェクトタイプとデフォルトのオブジェクトフィールド - サポートされているオブジェクトを確認できます。
• サポートされているオブジェクトフィールド - サポートされている各オブジェクトの包括的なリファレンスです。

その他のツール

• データ品質：SQLクエリの確認 - SQLクエリ内のデータ品質の問題を特定します。
• リネージュ - 上流および下流のグラフを解決します。

コアSDK

Alation AI Agent SDKを直接使用する例です：

• 基本的な使用例 - SDKの初期化とコンテキストクエリを示すシンプルな例です。
• QAチャットボットの例 - 会話コンテキストとシグネチャの使用方法を実演する対話型チャットボットです。

Model Context Protocol (MCP)

Alation Data Catalogを使ったエージェント型のエクスペリエンスを実現します。

• MCP統合 - Alation MCPサーバーを起動して使用する方法です。
• コードエディターとの統合 - コードエディターでツールを直接使用します。
• MCP Inspectorでのテスト - デバッグと検証の手順です。
• Claude Desktopとの統合 - Claude Desktop内でAlation MCPサーバーを活用します。
• LibreChatとの統合 - アシスタントやエージェントを作成します。

LangChain

SDKを活用して、複雑なエージェントやワークフローを構築します。

• LangChainとの統合 - SDKをLangChainエージェントに統合する方法です。
• 基本的な使用例 - シンプルな例です。
• マルチエージェントの例 - SDKとの統合ポイントを複数備えたマルチエージェントワークフローです。

他のツールキットとの統合

公開されているエージェントフレームワークやツールキットの数は、日々増えているようです。ここに使用中のフレームワークやツールキットが見当たらない場合でも、alation-ai-agent-sdkをニーズに合わせて調整できます。デコレーターを適用するラッパー関数を作成するだけで済む場合もあります。

できるだけ多くの開発者に利用してもらい、できる限り手軽に使えるようにしたいと考えていますが、ツールキットにはロングテールの分布があると見込んでおり、すべてのケースに対応するアダプターを作成することはできません。特定のツールキットのサポートをご希望の場合は、issueを作成してご相談ください。