Langgraph Structured Unstructured Tool

LangGraph Structured & Unstructured Tool Skill

Purpose

Set up retrieval tools for AI agents using official databricks_langchain classes. This skill focuses on TOOL CONFIGURATION, not agent implementation.

When to Use

• Setting up Vector Search retrieval for RAG
• Configuring Genie tools for structured data queries
• Combining multiple retrieval tools for agents
• Adding UCFunctionToolkit for governance and tracing

Prerequisites

• Python 3.10+
• databricks-langchain>=0.13.0
• Databricks workspace with Vector Search and/or Genie spaces configured

Installation

pip install "databricks-langchain>=0.13.0"

Or with uv:

uv add "databricks-langchain>=0.13.0"

Tool Types Overview

Pattern 1: VectorSearchRetrieverTool (Basic)

Basic semantic search over a Vector Search index.

from databricks_langchain import VectorSearchRetrieverTool

vs_tool = VectorSearchRetrieverTool(
    index_name="catalog.schema.docs_index",
    name="search_docs",
    description="Search documentation for relevant information about the product",
    num_results=5,
    columns=["text", "source", "title"]
)

# Use as a tool
result = vs_tool.invoke("How do I configure authentication?")
print(result)

Parameters

Pattern 2: VectorSearchRetrieverTool (With Filters)

Add filters and hybrid search for more precise retrieval.

from databricks_langchain import VectorSearchRetrieverTool

# Filtered retrieval
python_docs_tool = VectorSearchRetrieverTool(
    index_name="catalog.schema.docs_index",
    name="search_python_docs",
    description="Search Python-specific documentation",
    num_results=5,
    columns=["text", "source", "title", "language"],
    filters={"language": "python"}
)

# Hybrid search (combines keyword + semantic)
hybrid_tool = VectorSearchRetrieverTool(
    index_name="catalog.schema.docs_index",
    name="hybrid_search",
    description="Search documentation using hybrid retrieval",
    num_results=10,
    query_type="HYBRID"  # Options: "ANN" (default), "HYBRID"
)

Filter Examples

# Single value filter
filters={"category": "api"}

# Multiple values (OR)
filters={"category": ["api", "sdk"]}

# Multiple fields (AND)
filters={"category": "api", "language": "python"}

Pattern 3: GenieAgent (Structured Queries)

Query structured data via Databricks Genie spaces.

from databricks_langchain import GenieAgent

genie_tool = GenieAgent(
    genie_space_id="your_genie_space_id",
    genie_agent_name="sales_analyst",
    description="Analyzes sales data, revenue trends, and customer metrics. Use for questions about sales numbers, quarterly reports, and business KPIs.",
    include_context=True
)

# Query structured data
result = genie_tool.invoke("What was total revenue last quarter?")
print(result)

Parameters

Finding Genie Space ID

# From the Genie UI URL:
# https://<workspace>.databricks.com/genie/rooms/<SPACE_ID>
genie_space_id = "01xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Pattern 4: Multiple Genie Spaces

Configure multiple Genie tools for different data domains.

from databricks_langchain import GenieAgent

# Sales data
sales_tool = GenieAgent(
    genie_space_id="sales_space_id",
    genie_agent_name="sales_data",
    description="Query sales metrics, revenue, and customer transactions"
)

# Product data
product_tool = GenieAgent(
    genie_space_id="product_space_id",
    genie_agent_name="product_data",
    description="Query product catalog, inventory, and pricing information"
)

# HR data
hr_tool = GenieAgent(
    genie_space_id="hr_space_id",
    genie_agent_name="hr_data",
    description="Query employee data, headcount, and organizational metrics"
)

# Combine all tools
genie_tools = [sales_tool, product_tool, hr_tool]

Pattern 5: Combined Tools for Agents

Combine unstructured and structured retrieval tools and bind to an LLM.

from databricks_langchain import (
    VectorSearchRetrieverTool,
    GenieAgent,
    ChatDatabricks
)

# Unstructured retrieval (documentation, knowledge base)
docs_tool = VectorSearchRetrieverTool(
    index_name="catalog.schema.docs_index",
    name="search_docs",
    description="Search product documentation and knowledge base articles"
)

# Structured retrieval (business data)
sales_tool = GenieAgent(
    genie_space_id="sales_space_id",
    genie_agent_name="sales_data",
    description="Query sales data, revenue metrics, and customer analytics"
)

# Bind tools to LLM
llm = ChatDatabricks(endpoint="databricks-meta-llama-3-1-70b-instruct")
llm_with_tools = llm.bind_tools([docs_tool, sales_tool])

# Now use in your agent
response = llm_with_tools.invoke("What's our Q3 revenue and what docs explain our pricing model?")

Pattern 6: UCFunctionToolkit (With MLflow Tracing)

Wrap Unity Catalog functions as tools with automatic MLflow RETRIEVER span tracing.

from databricks_langchain import UCFunctionToolkit

# Create toolkit from existing UC functions
toolkit = UCFunctionToolkit(
    function_names=[
        "catalog.schema.search_docs",
        "catalog.schema.query_sales",
        "catalog.schema.lookup_customer"
    ]
)

# Get tools (automatically traced)
tools = toolkit.tools

# Bind to LLM
from databricks_langchain import ChatDatabricks

llm = ChatDatabricks(endpoint="databricks-meta-llama-3-1-70b-instruct")
llm_with_tools = llm.bind_tools(tools)

Benefits of UCFunctionToolkit

• Automatic MLflow tracing: All invocations logged with RETRIEVER spans
• Governance: Functions governed by Unity Catalog permissions
• Versioning: Functions can be versioned and managed
• Shared: Functions reusable across agents

Pattern 7: Custom UC Function Tool

Create a custom UC function and use it as a tool.

from databricks_langchain import DatabricksFunctionClient, UCFunctionToolkit

# Initialize client
client = DatabricksFunctionClient()

# Define function
def lookup_customer(customer_id: str) -> str:
    """Look up customer information by ID.

    Args:
        customer_id: The unique customer identifier

    Returns:
        Customer details as a formatted string
    """
    # Your implementation here
    from databricks.sdk import WorkspaceClient
    w = WorkspaceClient()
    # Query customer data...
    return f"Customer {customer_id}: Premium tier, Active since 2023"

# Create UC function
client.create_python_function(
    func=lookup_customer,
    catalog="main",
    schema="tools"
)

# Use with UCFunctionToolkit
toolkit = UCFunctionToolkit(
    function_names=["main.tools.lookup_customer"]
)

tools = toolkit.tools

Pattern 8: Full Tool Setup Example

Complete example combining all tool types.

from databricks_langchain import (
    VectorSearchRetrieverTool,
    GenieAgent,
    UCFunctionToolkit,
    ChatDatabricks
)

# === UNSTRUCTURED TOOLS ===

# Product documentation
product_docs = VectorSearchRetrieverTool(
    index_name="main.docs.product_index",
    name="search_product_docs",
    description="Search product documentation, user guides, and FAQs",
    num_results=5,
    columns=["content", "title", "url"]
)

# Technical documentation with filters
api_docs = VectorSearchRetrieverTool(
    index_name="main.docs.technical_index",
    name="search_api_docs",
    description="Search API documentation and code examples",
    num_results=5,
    columns=["content", "endpoint", "example"],
    filters={"type": "api"},
    query_type="HYBRID"
)

# === STRUCTURED TOOLS ===

# Sales analytics
sales_genie = GenieAgent(
    genie_space_id="sales_genie_space_id",
    genie_agent_name="sales_analytics",
    description="Query sales metrics, revenue data, and customer transactions"
)

# Product analytics
product_genie = GenieAgent(
    genie_space_id="product_genie_space_id",
    genie_agent_name="product_analytics",
    description="Query product usage, feature adoption, and engagement metrics"
)

# === UC FUNCTION TOOLS ===

uc_toolkit = UCFunctionToolkit(
    function_names=[
        "main.tools.lookup_customer",
        "main.tools.get_subscription_status"
    ]
)

# === COMBINE ALL TOOLS ===

all_tools = [
    product_docs,
    api_docs,
    sales_genie,
    product_genie,
    *uc_toolkit.tools
]

# === BIND TO LLM ===

llm = ChatDatabricks(endpoint="databricks-meta-llama-3-1-70b-instruct")
llm_with_tools = llm.bind_tools(all_tools)

# Ready to use in your agent!

Troubleshooting

Common Issues

Verifying Setup

# Check databricks-langchain version
import databricks_langchain
print(databricks_langchain.__version__)  # Should be >= 0.13.0

# Test Vector Search connection
from databricks_langchain import VectorSearchRetrieverTool
try:
    tool = VectorSearchRetrieverTool(
        index_name="catalog.schema.index",
        name="test",
        description="test"
    )
    print("VectorSearchRetrieverTool: OK")
except Exception as e:
    print(f"Error: {e}")

# Test Genie connection
from databricks_langchain import GenieAgent
try:
    tool = GenieAgent(
        genie_space_id="your_space_id",
        genie_agent_name="test",
        description="test"
    )
    print("GenieAgent: OK")
except Exception as e:
    print(f"Error: {e}")

References

• Databricks Agent Tools Overview
• Unstructured Retrieval Tools
• Custom Tools
• databricks-langchain API Reference
• Genie Spaces