Skip to content
LiPy

LlamaIndex Recipes and Practical Examples

Worked LlamaIndex examples, from a basic RAG chatbot to document comparison, SQL, extraction and multi-step agents.

Verified against llama-index-core 0.14.26 (checked 2026-11-19). Agents use the workflow-based FunctionAgent, whose run() is asynchronous — each recipe exposes an async entry point and calls it with asyncio.run(...). Model names are examples.


  1. Basic RAG Chatbot
  2. Research paper analyser
  3. Code Documentation Assistant
  4. Multi-Document Comparison Engine
  5. Real-time news analysis agent
  6. Data Extraction Pipeline
  7. Conversational SQL Agent
  8. Knowledge Graph Builder
  9. Multi-Step Reasoning Agent
  10. Customer Support Triage Agent
  11. Cited answers over filtered documents
  12. Text-to-SQL with NLSQLTableQueryEngine

"""
simple_rag_chatbot.py
A basic RAG chatbot that answers questions about documents
"""
import os
from llama_index.core import (
VectorStoreIndex,
SimpleDirectoryReader,
Document,
)
from llama_index.llms.openai import OpenAI
from llama_index.embeddings.openai import OpenAIEmbedding
def setup_rag_chatbot(documents_dir: str = "./documents"):
"""Set up a RAG chatbot with conversation memory."""
# Load documents
documents = SimpleDirectoryReader(
input_dir=documents_dir
).load_data()
if not documents:
raise ValueError(f"No documents found in {documents_dir}")
print(f"Loaded {len(documents)} documents")
# Setup embedding and LLM
embed_model = OpenAIEmbedding(
model="text-embedding-3-large"
)
llm = OpenAI(model="gpt-6-luna")
# Create index
index = VectorStoreIndex.from_documents(
documents,
embed_model=embed_model,
show_progress=True,
)
# A chat engine keeps the conversation history and condenses
# follow-up questions before retrieving (query engines are stateless)
chat_engine = index.as_chat_engine(
chat_mode="condense_plus_context",
llm=llm,
similarity_top_k=3,
)
return chat_engine
def run_chatbot():
"""Run interactive chatbot."""
chat_engine = setup_rag_chatbot()
print("=" * 50)
print("RAG Chatbot Ready! Type 'exit' to quit.")
print("=" * 50)
while True:
user_input = input("\nYou: ").strip()
if user_input.lower() == "exit":
print("Goodbye!")
break
if not user_input:
continue
response = chat_engine.chat(user_input)
print(f"\nAssistant: {response.response}")
print("\nSources:")
for node in response.source_nodes:
print(f" - {node.node.get_content()[:100]}...")
if __name__ == "__main__":
run_chatbot()

The chatbot reads from a mounted folder and takes input from the terminal, so the container needs a TTY. A minimal image:

# Dockerfile
FROM python:3.13-slim
WORKDIR /app
RUN pip install --no-cache-dir "llama-index==0.14.26"
COPY simple_rag_chatbot.py .
CMD ["python", "simple_rag_chatbot.py"]

and a Compose file that mounts the documents and keeps the terminal open:

# docker-compose.yml for RAG chatbot
services:
chatbot:
build: .
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
volumes:
- ./documents:/app/documents
- ./data:/app/data
stdin_open: true
tty: true

"""
research_paper_analyzer.py
Analyze research papers with citation tracking
"""
from llama_index.core import (
VectorStoreIndex,
Document,
)
from llama_index.readers.file import PDFReader # pip install llama-index-readers-file
from llama_index.core.tools import QueryEngineTool, FunctionTool
from llama_index.core.agent.workflow import FunctionAgent
import asyncio
from llama_index.llms.openai import OpenAI
import os
from pathlib import Path
class ResearchPaperAnalyzer:
"""Analyze research papers using LlamaIndex."""
def __init__(self, papers_dir: str):
self.papers_dir = papers_dir
self.llm = OpenAI(model="gpt-6-luna")
self.indexes = {}
self.query_engines = {}
def load_papers(self):
"""Load all PDF papers from directory."""
pdf_reader = PDFReader()
for pdf_file in Path(self.papers_dir).glob("*.pdf"):
paper_name = pdf_file.stem
print(f"Loading {paper_name}...")
# Load PDF
try:
documents = pdf_reader.load_data(str(pdf_file))
# Create index
index = VectorStoreIndex.from_documents(
documents,
show_progress=True,
)
# Store index and engine
self.indexes[paper_name] = index
self.query_engines[paper_name] = index.as_query_engine()
print(f"✓ {paper_name} loaded successfully")
except Exception as e:
print(f"✗ Error loading {paper_name}: {e}")
def create_agent(self):
"""Create agent for paper analysis."""
# Create tools for each paper
tools = []
for paper_name, query_engine in self.query_engines.items():
tool = QueryEngineTool.from_defaults(
query_engine=query_engine,
name=f"analyze_{paper_name}",
description=f"Analyse {paper_name}",
)
tools.append(tool)
# Analysis tool
def compare_papers(aspect: str, paper_names: list[str]) -> dict:
"""Compare the named papers on a specific aspect."""
results = {}
for paper_name in paper_names:
if paper_name in self.query_engines:
response = self.query_engines[paper_name].query(
f"What does this paper say about {aspect}?"
)
results[paper_name] = str(response)
return results
tools.append(FunctionTool.from_defaults(
fn=compare_papers,
name="compare_papers",
description="Compare multiple papers on a topic",
))
# Create agent
agent = FunctionAgent(
tools=tools,
llm=self.llm,
)
return agent
async def analyze(self, query: str) -> str:
"""Analyse query across papers."""
agent = self.create_agent()
response = await agent.run(user_msg=query)
return str(response)
# Usage
if __name__ == "__main__":
analyzer = ResearchPaperAnalyzer("./papers")
analyzer.load_papers()
# Analyse
result = asyncio.run(analyzer.analyze(
"Compare the methodology across papers"
))
print(f"\nAnalysis Result:\n{result}")

"""
code_doc_assistant.py
Generate documentation from source code
"""
from llama_index.core import (
VectorStoreIndex,
Document,
)
from pathlib import Path
import ast
class CodeDocumentationAssistant:
"""Generate documentation from code."""
def __init__(self, repo_path: str):
self.repo_path = repo_path
self.documents = []
def extract_code_structure(self, python_file: Path) -> str:
"""Extract functions and classes from Python file."""
with open(python_file, 'r') as f:
try:
tree = ast.parse(f.read())
except SyntaxError:
return ""
structure = []
for node in ast.walk(tree):
if isinstance(node, ast.FunctionDef):
doc = ast.get_docstring(node)
args = [arg.arg for arg in node.args.args]
structure.append(
f"Function: {node.name}({', '.join(args)})\n"
f"Docstring: {doc or 'No docstring'}"
)
elif isinstance(node, ast.ClassDef):
doc = ast.get_docstring(node)
structure.append(
f"Class: {node.name}\n"
f"Docstring: {doc or 'No docstring'}"
)
return "\n\n".join(structure)
def index_repository(self):
"""Index all Python files in repository."""
repo = Path(self.repo_path)
for py_file in repo.rglob("*.py"):
structure = self.extract_code_structure(py_file)
if structure:
doc = Document(
text=structure,
metadata={
"file": str(py_file.relative_to(repo)),
"source": "code",
}
)
self.documents.append(doc)
# Create index
if self.documents:
self.index = VectorStoreIndex.from_documents(
self.documents,
show_progress=True,
)
self.query_engine = self.index.as_query_engine()
else:
raise ValueError("No Python files found")
def generate_docs(self, query: str) -> str:
"""Generate documentation based on query."""
response = self.query_engine.query(query)
return str(response)
# Usage
if __name__ == "__main__":
assistant = CodeDocumentationAssistant("./myproject")
assistant.index_repository()
# Generate documentation
docs = assistant.generate_docs(
"What are the main classes and their purposes?"
)
print(docs)

"""
multi_document_comparison.py
Compare and contrast multiple documents
"""
from llama_index.core import (
VectorStoreIndex,
Document,
)
from llama_index.core.query_engine import (
SubQuestionQueryEngine,
)
from llama_index.core.question_gen import LLMQuestionGenerator
from llama_index.core.tools import QueryEngineTool
from llama_index.llms.openai import OpenAI
class MultiDocumentComparison:
"""Compare content across multiple documents."""
def __init__(self, documents_dict: dict):
"""
Initialize with documents.
documents_dict: {"doc_name": [Document, Document, ...]}
"""
self.documents_dict = documents_dict
self.indexes = {}
self.query_engines = {}
self.llm = OpenAI(model="gpt-6-luna")
def create_indexes(self):
"""Create indexes for each document group."""
for doc_name, docs in self.documents_dict.items():
print(f"Indexing {doc_name}...")
index = VectorStoreIndex.from_documents(
docs,
show_progress=True,
)
self.indexes[doc_name] = index
self.query_engines[doc_name] = index.as_query_engine()
def create_comparison_engine(self):
"""Create sub-question engine for comparison."""
tools = [
QueryEngineTool.from_defaults(
query_engine=engine,
name=f"{doc_name}_engine",
description=f"Query {doc_name}",
)
for doc_name, engine in self.query_engines.items()
]
self.comparison_engine = SubQuestionQueryEngine.from_defaults(
query_engine_tools=tools,
# explicit: the default generator needs llama-index-question-gen-openai,
# which cannot be installed alongside current releases
question_gen=LLMQuestionGenerator.from_defaults(llm=self.llm),
llm=self.llm,
)
def compare(self, aspect: str) -> str:
"""Compare documents on specific aspect."""
query = f"Compare how each document addresses {aspect}"
response = self.comparison_engine.query(query)
return str(response)
def contrast(self, aspect: str) -> str:
"""Contrast documents on specific aspect."""
query = f"What are the key differences in how documents address {aspect}?"
response = self.comparison_engine.query(query)
return str(response)
# Usage
if __name__ == "__main__":
# Create sample documents
docs = {
"Approach_A": [
Document(text="Approach A uses machine learning..."),
Document(text="Key advantages of A..."),
],
"Approach_B": [
Document(text="Approach B uses statistical methods..."),
Document(text="Key advantages of B..."),
],
}
comparison = MultiDocumentComparison(docs)
comparison.create_indexes()
comparison.create_comparison_engine()
# Compare
print("Comparison:")
print(comparison.compare("implementation strategy"))
print("\nContrast:")
print(comparison.contrast("implementation strategy"))

"""
news_analysis_agent.py
Analyze news in real-time with agent
"""
# pip install feedparser nltk
# python -c "import nltk; nltk.download('vader_lexicon')" # one-off download for the sentiment scorer
from llama_index.core.agent.workflow import FunctionAgent
import asyncio
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI
import feedparser
class NewsAnalysisAgent:
"""Analyse news using agents."""
def __init__(self):
self.llm = OpenAI(model="gpt-6-luna")
def fetch_rss_feed(self, feed_url: str, limit: int = 5) -> str:
"""Fetch latest articles from RSS feed."""
feed = feedparser.parse(feed_url)
articles = []
for entry in feed.entries[:limit]:
articles.append({
"title": entry.title,
"summary": entry.summary,
"link": entry.link,
})
return str(articles)
def search_news_topic(self, topic: str) -> str:
"""Search for news on specific topic."""
# In real implementation, use news API
return f"Recent articles about {topic}..."
def sentiment_analysis(self, text: str) -> str:
"""Analyse sentiment of text."""
# Simplified sentiment analysis
from nltk.sentiment import SentimentIntensityAnalyzer
sia = SentimentIntensityAnalyzer()
scores = sia.polarity_scores(text)
return f"Sentiment scores: {scores}"
def create_agent(self):
"""Create news analysis agent."""
tools = [
FunctionTool.from_defaults(
fn=self.fetch_rss_feed,
name="fetch_rss",
description="Fetch articles from RSS feed",
),
FunctionTool.from_defaults(
fn=self.search_news_topic,
name="search_news",
description="Search for news on topic",
),
FunctionTool.from_defaults(
fn=self.sentiment_analysis,
name="analyze_sentiment",
description="Analyse sentiment of text",
),
]
agent = FunctionAgent(
tools=tools,
llm=self.llm,
)
return agent
async def analyze_news(self, query: str) -> str:
"""Analyse news based on query."""
agent = self.create_agent()
response = await agent.run(user_msg=query)
return str(response)
# Usage
if __name__ == "__main__":
analyzer = NewsAnalysisAgent()
result = asyncio.run(analyzer.analyze_news(
"Fetch the latest tech news and analyse the sentiment"
))
print(f"\nAnalysis:\n{result}")

"""
data_extraction_pipeline.py
Extract structured data from unstructured text
"""
from llama_index.core import Document
from llama_index.core.output_parsers import PydanticOutputParser
from llama_index.llms.openai import OpenAI
from pydantic import BaseModel, Field
from typing import List
from pathlib import Path
class Person(BaseModel):
name: str = Field(description="Person's name")
role: str = Field(description="Professional role")
skills: List[str] = Field(description="List of skills")
experience_years: int = Field(description="Years of experience")
class ExtractionPipeline:
"""Extract structured data from documents."""
def __init__(self):
self.llm = OpenAI(model="gpt-6-luna")
self.parser = PydanticOutputParser(output_cls=Person)
def extract_from_text(self, text: str) -> Person:
"""Extract person information from text."""
prompt = f"""Extract person information from this text:
{text}
{self.parser.get_format_string()}"""
response = self.llm.complete(prompt)
parsed = self.parser.parse(str(response))
return parsed
def batch_extract(self, documents: List[Document]) -> List[Person]:
"""Extract from multiple documents."""
results = []
for doc in documents:
try:
person = self.extract_from_text(doc.text)
results.append(person)
except Exception as e:
print(f"Error extracting from document: {e}")
return results
def save_results(self, results: List[Person], output_file: str):
"""Save extracted data to CSV."""
import csv
with open(output_file, 'w', newline='') as f:
writer = csv.DictWriter(
f,
fieldnames=['name', 'role', 'skills', 'experience_years']
)
writer.writeheader()
for person in results:
writer.writerow({
'name': person.name,
'role': person.role,
'skills': ', '.join(person.skills),
'experience_years': person.experience_years,
})
# Usage
if __name__ == "__main__":
pipeline = ExtractionPipeline()
# Sample text
text = """
Alice Smith is a Senior Software Engineer with 8 years of experience.
She specializes in Python, JavaScript, and AWS. She's an expert in
building scalable distributed systems.
"""
result = pipeline.extract_from_text(text)
print(f"Extracted: {result}")

With a tool-calling model, llm.structured_predict(Person, PromptTemplate("Extract the person from: {text}"), text=text) does the same job without hand-written format instructions and is more reliable.


"""
sql_agent.py
Query databases using natural language
"""
from llama_index.core.agent.workflow import FunctionAgent
import asyncio
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI
import sqlite3
from typing import List
class SQLAgent:
"""Query databases conversationally."""
def __init__(self, db_path: str):
self.db_path = db_path
self.llm = OpenAI(model="gpt-6-luna")
# Open read-only: the keyword filter below is a convenience, not a security boundary.
# check_same_thread=False because the agent runs sync tools in a worker thread.
self.connection = sqlite3.connect(
f"file:{db_path}?mode=ro", uri=True, check_same_thread=False
)
self.cursor = self.connection.cursor()
def get_schema(self) -> str:
"""Get database schema."""
self.cursor.execute(
"SELECT name FROM sqlite_master WHERE type='table';"
)
tables = self.cursor.fetchall()
schema = []
for table in tables:
table_name = table[0]
self.cursor.execute(f"PRAGMA table_info({table_name})")
columns = self.cursor.fetchall()
col_info = []
for col in columns:
col_info.append(f"{col[1]} ({col[2]})")
schema.append(f"{table_name}: {', '.join(col_info)}")
return "\n".join(schema)
def execute_query(self, query: str) -> str:
"""Execute SQL query safely."""
try:
# Validate query (prevent DROP, DELETE, etc.)
unsafe_keywords = ["DROP", "DELETE", "TRUNCATE", "GRANT"]
if any(kw in query.upper() for kw in unsafe_keywords):
return "Query contains unsafe operations"
self.cursor.execute(query)
results = self.cursor.fetchall()
return str(results[:10]) # Limit results
except Exception as e:
return f"Query error: {str(e)}"
def translate_to_sql(self, question: str) -> str:
"""Translate natural language to SQL."""
schema = self.get_schema()
prompt = f"""Given this database schema:
{schema}
Translate this question to SQL:
{question}
Return only the SQL query."""
response = self.llm.complete(prompt)
return str(response).strip()
def create_agent(self):
"""Create SQL agent."""
tools = [
FunctionTool.from_defaults(
fn=self.translate_to_sql,
name="translate_sql",
description="Translate natural language to SQL",
),
FunctionTool.from_defaults(
fn=self.execute_query,
name="execute_sql",
description="Execute SQL query",
),
FunctionTool.from_defaults(
fn=self.get_schema,
name="get_schema",
description="Get database schema",
),
]
agent = FunctionAgent(
tools=tools,
llm=self.llm,
system_prompt="You are a helpful database assistant. Help users query the database.",
)
return agent
async def query(self, question: str) -> str:
"""Query database conversationally."""
agent = self.create_agent()
response = await agent.run(user_msg=question)
return str(response)
# Usage
if __name__ == "__main__":
agent = SQLAgent("./database.db")
result = asyncio.run(agent.query("How many users registered last month?"))
print(f"Result: {result}")

For a ready-made alternative, see Text-to-SQL with NLSQLTableQueryEngine below.


"""
knowledge_graph_builder.py
Extract and build knowledge graphs from documents
"""
from llama_index.core import Document, PromptTemplate
from llama_index.llms.openai import OpenAI
from pydantic import BaseModel
from typing import List
class Entity(BaseModel):
name: str
entity_type: str # person, organization, concept, etc.
class Relationship(BaseModel):
source: str
target: str
relationship_type: str
class KnowledgeGraph(BaseModel):
entities: List[Entity]
relationships: List[Relationship]
class KnowledgeGraphBuilder:
"""Build knowledge graphs from text."""
def __init__(self):
self.llm = OpenAI(model="gpt-6-luna")
self.graph = {
"entities": {},
"relationships": []
}
def extract_entities_and_relations(self, text: str) -> KnowledgeGraph:
"""Extract entities and relationships from text."""
try:
return self.llm.structured_predict(
KnowledgeGraph,
PromptTemplate(
"Extract the entities (people, organisations, places, concepts) "
"and the relationships between them from this text:\n{text}"
),
text=text,
)
except Exception as e:
print(f"Extraction failed: {e}")
return KnowledgeGraph(entities=[], relationships=[])
def add_documents(self, documents: List[Document]):
"""Add documents to knowledge graph."""
for doc in documents:
kg = self.extract_entities_and_relations(doc.text)
# Add entities
for entity in kg.entities:
self.graph["entities"][entity.name] = entity.entity_type
# Add relationships
for rel in kg.relationships:
self.graph["relationships"].append({
"source": rel.source,
"target": rel.target,
"type": rel.relationship_type,
})
def visualize(self) -> str:
"""Generate DOT format for visualization."""
lines = ["digraph KnowledgeGraph {"]
# Add nodes
for entity, etype in self.graph["entities"].items():
lines.append(f' "{entity}" [label="{entity}", type="{etype}"];')
# Add edges
for rel in self.graph["relationships"]:
lines.append(
f' "{rel["source"]}" -> "{rel["target"]}" '
f'[label="{rel["type"]}"];'
)
lines.append("}")
return "\n".join(lines)
def save_graph(self, output_file: str):
"""Save knowledge graph."""
with open(output_file, 'w') as f:
f.write(self.visualize())
# Usage
if __name__ == "__main__":
builder = KnowledgeGraphBuilder()
docs = [
Document(text="Alice works at TechCorp in San Francisco."),
Document(text="TechCorp was founded in 2010."),
]
builder.add_documents(docs)
# Visualize
graph_dot = builder.visualize()
print(graph_dot)
# Save
builder.save_graph("knowledge_graph.dot")

To query the graph rather than just draw it, use PropertyGraphIndex, which runs similar extraction during ingestion and supports graph-aware retrieval; see property graphs.


"""
multi_step_reasoning_agent.py
Agent that can reason through complex problems
"""
from llama_index.core.agent.workflow import FunctionAgent
import asyncio
from llama_index.core.tools import FunctionTool
from llama_index.llms.openai import OpenAI
class MultiStepReasoningAgent:
"""Agent for multi-step reasoning."""
def __init__(self):
self.llm = OpenAI(model="gpt-6-luna")
self.reasoning_steps = []
# Step 1: Information gathering
def research_topic(self, topic: str) -> str:
"""Research a topic."""
return f"Research data about {topic}..."
# Step 2: Analysis
def analyze_data(self, data: str) -> str:
"""Analyse gathered data."""
return f"Analysis of data: {data[:100]}..."
# Step 3: Synthesis
def synthesize_findings(self, findings: list) -> str:
"""Synthesize findings into conclusions."""
return f"Synthesized conclusion from {len(findings)} findings"
# Step 4: Decision making
def make_recommendation(self, conclusions: str) -> str:
"""Make recommendation based on conclusions."""
return f"Recommendation: {conclusions[:100]}..."
def create_agent(self):
"""Create multi-step reasoning agent."""
tools = [
FunctionTool.from_defaults(
fn=self.research_topic,
name="research",
description="Research and gather information",
),
FunctionTool.from_defaults(
fn=self.analyze_data,
name="analyze",
description="Analyse gathered data",
),
FunctionTool.from_defaults(
fn=self.synthesize_findings,
name="synthesize",
description="Synthesize findings",
),
FunctionTool.from_defaults(
fn=self.make_recommendation,
name="recommend",
description="Make recommendations",
),
]
system_prompt = """You are a strategic advisor. When solving problems:
1. First research and gather information
2. Then analyse the data deeply
3. Synthesize findings into key conclusions
4. Finally, make clear recommendations
Use the tools in this order and explain your reasoning at each step."""
agent = FunctionAgent(
tools=tools,
llm=self.llm,
system_prompt=system_prompt,
)
return agent
async def solve(self, problem: str) -> str:
"""Solve complex problem with multi-step reasoning."""
agent = self.create_agent()
response = await agent.run(user_msg=problem)
return str(response)
# Usage
if __name__ == "__main__":
agent = MultiStepReasoningAgent()
problem = "How should a startup enter the AI market?"
result = asyncio.run(agent.solve(problem))
print(f"Solution:\n{result}")

Triage is a fixed sequence of three independent classifications, so it does not need an agent loop at all: run the three LLM calls concurrently. (Earlier versions of this recipe ran an agent and then repeated every call by hand.)

"""
support_triage_agent.py
Triage customer support tickets
"""
import asyncio
from llama_index.llms.openai import OpenAI
from enum import Enum
from dataclasses import dataclass
class Priority(Enum):
LOW = 1
MEDIUM = 2
HIGH = 3
CRITICAL = 4
class Department(Enum):
BILLING = "billing"
TECHNICAL = "technical"
SALES = "sales"
GENERAL = "general"
@dataclass
class TriagedTicket:
ticket_id: str
priority: Priority
department: Department
suggested_response: str
class SupportTriageAgent:
"""Triage support tickets using AI."""
def __init__(self):
self.llm = OpenAI(model="gpt-6-luna")
async def assess_urgency(self, ticket: str) -> str:
"""Assess urgency of ticket."""
prompt = f"""Assess the urgency of this support ticket:
{ticket}
Return: LOW, MEDIUM, HIGH, or CRITICAL"""
response = await self.llm.acomplete(prompt)
return str(response).strip().upper()
async def categorize_issue(self, ticket: str) -> str:
"""Categorize issue type."""
prompt = f"""Categorize this support issue:
{ticket}
Return one of: BILLING, TECHNICAL, SALES, GENERAL"""
response = await self.llm.acomplete(prompt)
return str(response).strip().upper()
async def draft_response(self, ticket: str) -> str:
"""Draft initial response to customer."""
prompt = f"""Write a professional initial response to this support ticket:
{ticket}
Keep it brief (2-3 sentences) and empathetic."""
response = await self.llm.acomplete(prompt)
return str(response).strip()
async def triage(self, ticket_id: str, ticket_text: str) -> TriagedTicket:
"""Triage a support ticket: classify urgency and department, then draft a reply."""
urgency, category, suggestion = await asyncio.gather(
self.assess_urgency(ticket_text),
self.categorize_issue(ticket_text),
self.draft_response(ticket_text),
)
return TriagedTicket(
ticket_id=ticket_id,
priority=Priority.__members__.get(urgency, Priority.MEDIUM),
department=Department.__members__.get(category, Department.GENERAL),
suggested_response=suggestion,
)
# Usage
if __name__ == "__main__":
agent = SupportTriageAgent()
ticket = """
I'm unable to access my account and it's been down for 2 hours.
This is affecting my work. Please help ASAP!
"""
result = asyncio.run(agent.triage("TICKET-001", ticket))
print(f"Ticket ID: {result.ticket_id}")
print(f"Priority: {result.priority.name}")
print(f"Department: {result.department.value}")
print(f"Suggested Response: {result.suggested_response}")

Per-department answers with source references

Section titled “Per-department answers with source references”

A common requirement: answer only from the documents a caller may see, and show which documents were used. This recipe tags documents with metadata at load time, restricts retrieval with MetadataFilters, and returns the answer with numbered sources from CitationQueryEngine.

"""
cited_answers.py
Answer from one department's documents and return numbered sources
"""
from dataclasses import dataclass
from llama_index.core import Document, VectorStoreIndex
from llama_index.core.query_engine import CitationQueryEngine
from llama_index.core.vector_stores import FilterOperator, MetadataFilter, MetadataFilters
from llama_index.llms.openai import OpenAI
@dataclass
class CitedAnswer:
text: str
sources: list[dict]
class DepartmentAssistant:
def __init__(self, documents: list[Document]):
self.index = VectorStoreIndex.from_documents(documents)
self.llm = OpenAI(model="gpt-6-luna")
def ask(self, question: str, department: str, top_k: int = 4) -> CitedAnswer:
filters = MetadataFilters(
filters=[MetadataFilter(key="department", operator=FilterOperator.EQ, value=department)]
)
engine = CitationQueryEngine.from_args(
self.index,
llm=self.llm,
similarity_top_k=top_k,
citation_chunk_size=256,
filters=filters, # passed to the retriever
)
response = engine.query(question)
sources = [
{
"number": i,
"file": node.node.metadata.get("file_name"),
"score": round(node.score, 3) if node.score is not None else None,
"excerpt": node.node.get_content()[:120],
}
for i, node in enumerate(response.source_nodes, start=1)
]
return CitedAnswer(text=str(response), sources=sources)
if __name__ == "__main__":
documents = [
Document(text="Staff receive 25 days of paid holiday a year.",
metadata={"department": "hr", "file_name": "leave.md"}),
Document(text="Production deployments need two approvals.",
metadata={"department": "engineering", "file_name": "deploy.md"}),
]
assistant = DepartmentAssistant(documents)
answer = assistant.ask("How many days of holiday do I get?", department="hr")
print(answer.text)
for source in answer.sources:
print(source)

Notes:

  • The filter is applied in the retriever, so documents from other departments never reach the prompt. Do not rely on the prompt to hide them.
  • The numbers in the answer ([1], [2]) refer to the order of response.source_nodes. The model chooses where to place them, so validate that each cited number exists before displaying it.
  • Which filter operators work depends on the vector store. The default in-memory store supports all of them; see retrievers.
  • Each citation node’s text starts with Source N:, so strip that prefix if you show excerpts.
  • The same engine can be used as a QueryEngineTool so an agent can cite sources too.

Natural-language questions over a read-only database

Section titled “Natural-language questions over a read-only database”

NLSQLTableQueryEngine shows the LLM the table schemas, asks for a SQL query, runs it and has the LLM write the answer from the rows. Compared with the hand-built agent above, the prompting and result handling are done for you. It needs SQLAlchemy, which llama-index-core already depends on.

"""
text_to_sql.py
Ask questions about a SQLite database in plain English
"""
import asyncio
from llama_index.core import SQLDatabase
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.core.query_engine import NLSQLTableQueryEngine
from llama_index.core.tools import QueryEngineTool
from llama_index.llms.openai import OpenAI
from sqlalchemy import create_engine
llm = OpenAI(model="gpt-6-luna")
# mode=ro makes SQLite refuse writes, whatever SQL the model produces
engine = create_engine("sqlite:///file:shop.db?mode=ro&uri=true")
sql_database = SQLDatabase(engine, include_tables=["customers", "orders"])
sql_engine = NLSQLTableQueryEngine(
sql_database=sql_database,
tables=["customers", "orders"],
llm=llm,
synthesize_response=True, # False returns the raw rows instead of a written answer
)
response = sql_engine.query("How many orders has each customer placed?")
print(response)
print(response.metadata["sql_query"]) # the SQL that was run
print(response.metadata.get("result")) # the rows; absent if the SQL failed
# As a tool, alongside document search
agent = FunctionAgent(
tools=[
QueryEngineTool.from_defaults(
query_engine=sql_engine,
name="shop_database",
description="Orders and customers. Use for counts, totals and lookups.",
)
],
llm=llm,
)
async def main():
print(await agent.run(user_msg="Which country has the highest order total?"))
asyncio.run(main())

Notes:

  • The model writes the SQL, so the database account is the security boundary. Use a read-only user (or mode=ro for SQLite as above) and include_tables to limit what the model can see.
  • With many tables, the schema prompt grows; SQLTableRetrieverQueryEngine retrieves the relevant table schemas per question instead of sending all of them.
  • Always log response.metadata["sql_query"]. When an answer is wrong, the generated SQL is the first thing to read.
  • Column names and types come from the database. Adding a comment or a descriptive table name helps the model more than prompt tweaks.

These recipes are starting points; adapt the prompts, models and storage to your data.