Build a Text2SQL Agent with Neocarta and LangGraph

# Neo4j connection
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_DATABASE=neo4j

# Embedding model (used by the Neocarta MCP server for semantic search)
EMBEDDING_MODEL=text-embedding-3-small

# LLM provider key — set the one matching your AGENT_MODEL
OPENAI_API_KEY=sk-...

# LLM model (any LiteLLM model ID; defaults to openai/gpt-4o-mini)
AGENT_MODEL=openai/gpt-4o-mini

# GCP project for BigQuery MCP execution
GCP_PROJECT_ID=my-gcp-project

gcloud beta services mcp enable bigquery.googleapis.com --project=PROJECT_ID

import httpx
from google.auth import default
from google.auth.transport.requests import Request

class GoogleAuth(httpx.Auth):
    def __init__(self):
        self.credentials, _ = default()

    def auth_flow(self, request):
        self.credentials.refresh(Request())
        request.headers["Authorization"] = f"Bearer {self.credentials.token}"
        yield request

gcloud beta services mcp disable bigquery.googleapis.com --project=PROJECT_ID

import os
from langchain.agents import create_agent
from langchain.tools import BaseTool
from langchain_litellm import ChatLiteLLM
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.graph.state import CompiledStateGraph

SYSTEM_PROMPT = """You are a Text2SQL agent and are tasked with answering
questions about our BigQuery dataset on ecommerce.

Use the metadata graph to collect relevant schema to inform your SQL queries.

Rules:
* Always ensure that tables are qualified with project and dataset names
* Always ensure you have the appropriate BigQuery schema from the Metadata Graph before write a query
* Return query results to the user in a readable format"""

def create_text2sql_agent(mcp_tools: list[BaseTool]) -> CompiledStateGraph:
    model = ChatLiteLLM(model=os.getenv("AGENT_MODEL", "gpt-4o-mini"))
    return create_agent(
        model=model,
        tools=mcp_tools,
        system_prompt=SYSTEM_PROMPT,
        checkpointer=InMemorySaver(),
    )

from langchain_mcp_adapters.client import MultiServerMCPClient

sql_metadata_graph_mcp_params = {
    "transport": "stdio",
    "command": "uv",
    "args": ["run", "neocarta-mcp"],
    "env": {
        "NEO4J_URI": os.getenv("NEO4J_URI"),
        "NEO4J_USERNAME": os.getenv("NEO4J_USERNAME"),
        "NEO4J_PASSWORD": os.getenv("NEO4J_PASSWORD"),
        "NEO4J_DATABASE": os.getenv("NEO4J_DATABASE"),
        "EMBEDDING_MODEL": os.getenv("EMBEDDING_MODEL", "text-embedding-3-small"),
        "OPENAI_API_KEY": os.getenv("OPENAI_API_KEY"),
    },
}

bigquery_mcp_params = {
    "transport": "http",
    "url": "https://bigquery.googleapis.com/mcp",
    "auth": GoogleAuth(),
    "headers": {"Content-Type": "application/json"},
}

client = MultiServerMCPClient({
    "sql_metadata_graph": sql_metadata_graph_mcp_params,
    "bigquery": bigquery_mcp_params,
})

make agent
# or equivalently:
python run_agent.py

> Which customers placed the largest orders last quarter?

Calling tools: ['get_context_by_table_hybrid_search']
[{'name': 'get_context_by_table_hybrid_search', 'args': {'text_content': 'customers orders'}, ...}]

Agent: I found the relevant tables. Let me generate the SQL query.

Calling tools: ['execute_sql']

Agent: Here are the customers with the largest orders last quarter:

| customer_id | customer_name      | total_order_value |
|-------------|--------------------|--------------------|
| C-00412     | Northwind Traders  | $284,500.00        |
| C-00089     | Contoso Ltd        | $198,320.00        |
| C-00231     | Fabrikam Inc       | $176,900.00        |