Alation

What is the Alation AI Agent SDK?

The Alation AI Agent SDK is a Python library designed to connect AI agents with the Alation Data Catalog. It empowers agents to retrieve contextual information, search for metadata using natural language, and fetch catalog objects in bulk, effectively bridging the gap between AI applications and enterprise data governance.

How to use the project?

To use the SDK, you need Python 3.10+ and access to an Alation Data Catalog instance with valid credentials. You can install the desired package (alation-ai-agent-sdk, alation-ai-agent-langchain, or alation-ai-agent-mcp) and use it to build applications that interact with your Alation catalog. For example, you can integrate it into a LangChain agent to allow the agent to query the data catalog for information.

Key Features

• Retrieve Context: Fetches contextual metadata from the Alation Data Catalog.
• Natural Language Search: Allows searching for metadata using natural language queries.
• Bulk Data Fetching: Capable of retrieving bulk objects from the catalog.
• Framework Integration: Provides seamless integration with AI frameworks like LangChain and the Model Context Protocol (MCP).
• Flexible Authentication: Supports authentication via refresh tokens or client ID/secrets.

Use Cases

• Data-Aware AI Agents: Building AI agents that can understand and reason about an organization's data assets by querying the Alation Data Catalog.
• Automated Data Governance: Developing workflows that leverage AI to interact with and manage the data catalog.
• Enhanced RAG: Augmenting Retrieval-Augmented Generation (RAG) pipelines with trusted metadata from a centralized catalog.
• MCP Tool Development: Exposing Alation's capabilities as a tool for any MCP-compatible client.

FAQ from the project

• What is required to use this SDK?

You need Python 3.10 or higher, access to an Alation Data Catalog instance, and a valid refresh token or client ID and secret for authentication.

• What are the main components?

The SDK is composed of a Core SDK for basic API interaction, a specific integration for the LangChain framework (alation-ai-agent-langchain), and an MCP server implementation (alation-ai-agent-mcp).

• Is the SDK open source?

Yes, the SDK is licensed under the Apache 2.0 License. However, it requires a connection to the Alation Data Catalog, which is a commercial product.

Alation AI Agent SDK

The Alation AI Agent SDK enables AI agents to access and leverage metadata from the Alation Data Catalog.

Overview

This SDK empowers AI agents to:

• Retrieve contextual information from Alation's Data Catalog
• Use natural language to search for relevant metadata
• Fetch bulk objects from catalog
• Customize response formats using flexible signature specifications
• Integrate seamlessly with AI frameworks like LangChain and MCP

Components

The project is organized into multiple components:

• Core SDK - Foundation with API client and context tools
• LangChain Integration - Adapters for the LangChain framework
• MCP Integration - Server implementation for Model Context Protocol

Core SDK (alation-ai-agent-sdk)

The core SDK provides the foundation for interacting with the Alation API. It handles authentication, request formatting, and response parsing.

Learn more about the Core SDK

LangChain Integration (alation-ai-agent-langchain)

This component integrates the SDK with the LangChain framework, enabling the creation of sophisticated AI agents that can reason about your data catalog.

Learn more about the LangChain Integration

MCP Integration (alation-ai-agent-mcp)

The MCP integration provides an MCP-compatible server that exposes Alation's context capabilities to any MCP client.

Learn more about the MCP Integration

Getting Started

Prerequisites

• Python 3.10 or higher
• Access to an Alation Data Catalog instance
• A valid refresh token or client_id and secret. For more details, refer to the Authentication Guide.

Installation

# Install core SDK
pip install alation-ai-agent-sdk

# Install LangChain integration
pip install alation-ai-agent-langchain

# Install MCP integration
pip install alation-ai-agent-mcp

Usage

The library needs to be configured with your Alation instance credentials. Depending on your authentication mode, you can use either UserAccountAuthParams or ServiceAccountAuthParams.

User Account Authentication

from alation_ai_agent_sdk import AlationAPI, UserAccountAuthParams

# Initialize the SDK with User Account Authentication
auth_params = UserAccountAuthParams(
    user_id=12345,  # Your numeric user ID
    refresh_token="your_refresh_token"
)
alation_api = AlationAPI(
    base_url="https://your-alation-instance.com",
    auth_method="user_account",
    auth_params=auth_params
)

Service Account Authentication

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
)

Supported Tools

alation_context

A retrieval tool that pulls contextual information from the Alation catalog based on natural language queries.

Functionality

• Accepts user questions in natural language
• Performs query rewrites to optimize search results
• Returns relevant catalog data in JSON format
• Can return multiple object types in a single response

Usage

response = alation_ai_sdk.get_context(
    "What certified data set is used to make decisions on providing credit for customers?"
)

Input Parameters

• question (string): The natural language query
• signature (optional dict): The configuration controlling which objects and their fields

Returns

• JSON-formatted response of relevant catalog objects

get_data_products

A retrieval tool that pulls data products from the Alation catalog based on product ID or natural language queries.

Functionality

• Accepts product IDs for direct lookup
• Accepts user queries in natural language for discovery
• Returns relevant data products in JSON format
• Can return single or multiple results

Usage

response = alation_ai_sdk.get_data_products(
    "12345"  # Example product ID
)

response = alation_ai_sdk.get_data_products(
    "Show me all data products related to sales"
)

Input Parameters

• product_id (string, optional): The ID of the product for direct lookup
• query (string, optional): A natural language query to discover data products

Returns

• JSON-formatted response of relevant data products

Bulk Object Retrieval

Retrieve catalog objects without conversational queries:

# Get tables from a specific datasource
bulk_signature = {
    "table": {
        "fields_required": ["name", "description", "columns"],
        "search_filters": {
            "fields": {"ds": [123]}  # Specific datasource
        },
        "limit": 100,
        "child_objects": {
            "columns": {
                "fields": ["name", "data_type", "description"]
            }
        }
    }
}

response = sdk.bulk_retrieval(signature=bulk_signature)

Shape the SDK to your needs

The SDK's alation-context tool supports customizing response content using signatures. This powerful feature allows you to specify which fields to include and how to filter the catalog results. For instance:

# Define a signature for searching only tables that optionally
# include joins and filters if relevant to the user question
signature = {
    "table": {
        "fields_required": ["name", "title", "description"],
        "fields_optional": ["common_joins", "common_filters"]
    }
}

# Use the signature with your query
response = sdk.get_context(
    "What are our sales tables?",
    signature
)

For more information about signatures, refer to Using Signatures.

Guides and Example Agents

General

• Planning an Integration - Practical considerations for getting the most out of your agents and the Alation Data Catalog.
• Using Signatures - How to customize your agent with concrete examples.
• Supported Object Types and Fields - See what's available.

Core SDK

Direct usage examples for the Alation AI Agent SDK:

• Basic Usage Example - Simple example showing SDK initialization and context queries.
• QA Chatbot Example - Interactive chatbot demonstrating conversation context and signature usage.

Model Context Protocol (MCP)

Enable agentic experiences with the Alation Data Catalog.

• MCP Integration - Getting the Alation MCP server up and running.
• Integration with Code Editors
• Testing with MCP Inspector - Steps for debugging and verification.
• Claude Desktop Integration - Leverage the Alation MCP server within Claude Desktop.
• LibreChat Integration - Create assistants and agents alike.

LangChain

Harness the SDK to build complex agents and workflows.

• LangChain Integration - How to integrate the SDK into your LangChain agents.
• Basic Usage Example - A simple example.
• Multi Agent Example - A multi agent workflow with several SDK integration points.

Integrating with other toolkits

The number of published agent frameworks and toolkits appears to be increasing every day. If you don't happen to see the framework or toolkit you're using here, it's still possible to adapt alation-ai-agent-sdk to your needs. It may be as simple as writing a wrapping function where a decorator is applied.

While we want to reach as many developers as possible and make it as convenient as possible, we anticipate a long tail distribution of toolkits and won't be able to write adapters for every case. If you'd like support for a specific toolkit, please create an issue to discuss.