LlamaIndex Expert Skill
LlamaIndex is an MIT-licensed Python framework for building LLM applications over your data. In 2026, it has evolved from a RAG indexing library into an event-driven workflow framework with integrated production runtime (llama-deploy), agent orchestration (AgentWorkflow), knowledge graph construction (PropertyGraphIndex), and OpenTelemetry-native observability.
The framework is organized around seven core primitives: Reader (data loaders), Document/Node (chunked content model), Index (data structures over Nodes), Retriever (relevant Node selection), Query Engine (retriever + synthesis), Agent (LLM with tools), and Workflow (event-driven orchestration).
Key Principles
These principles govern every decision when building with LlamaIndex. Read them before proceeding to the reference guides.
- Decouple retrieval chunks from synthesis chunks. The embedding representation that retrieves well differs from the context representation that generates well. Use
SentenceWindowNodeParser + MetadataReplacementNodePostProcessor for this pattern.
- Rerank before you generate. Hybrid retrieval + reranker is the minimum viable production RAG configuration.
- Agents are Workflows.
FunctionAgent and AgentWorkflow are pre-configured Workflows. Drop to raw Workflow when you need custom control flow.
- Graphs are not just vector stores.
PropertyGraphIndex adds structural path traversal that vector similarity cannot provide — combine both for maximum retrieval quality.
- Evaluate in the same process. Span-attached evaluation preserves the connection between the output and the retrieval context that produced it.
Where to Start
The pipeline has 9 phases from Ingest to Deploy. If you're joining mid-stream with existing work, find your entry point:
| You already have... |
Start at phase |
What to do |
| Nothing — blank project |
Ingest |
Set up data loading, then proceed through the full pipeline |
| Documents in a directory |
Chunk |
Choose a chunking strategy, build your index |
| A working vector index |
Retrieve |
Add hybrid search, reranking, metadata filters |
| An existing RAG pipeline to harden |
Deploy |
Add observability, llama-deploy, production debugging |
| A need to measure and improve quality |
Evaluate |
Set up evaluators, ParamTuner, span-attached scoring |
| Nothing — comparing frameworks |
See Framework Routing Guide |
Don't start the pipeline — pick the right tool first |
Pipeline Mode
Different tasks need different levels of rigor. Match your scope to a mode:
| Mode |
When |
Phases to run |
Skip |
| Quick |
Single query, one source, exploration |
Ingest → Chunk → Index → Retrieve |
Reranking, metadata filters, observability, evaluation |
| Full |
Production RAG, multiple sources, compliance |
Ingest → Chunk → Index → Retrieve → Agent/Workflow → Deploy → Evaluate |
Nothing — run all phases |
| Evaluate |
Benchmarking, regression testing |
Ingest → Chunk → Index → Evaluate |
Retrieve, Agent, Workflow, Deploy (run offline) |
| Graph |
Knowledge graph construction |
Ingest → Chunk → Graph → Retrieve |
Agent, Workflow, Deploy (query via graph index directly) |
Rule of thumb: if you're shipping to users, run Full mode. If you're exploring, run Quick. If you're measuring, run Evaluate.
Quick Reference
| Phase |
Task |
Approach |
Reference |
| Ingest |
Load data |
SimpleDirectoryReader("./data").load_data() |
references/architecture.md |
| Chunk |
Parse documents into nodes |
SentenceSplitter(chunk_size=1024) |
references/rag-strategies.md |
| Index |
Build vector index |
VectorStoreIndex.from_documents(docs) |
references/rag-strategies.md |
| Retrieve |
Hybrid search + rerank |
BM25Retriever + CohereRerank |
references/rag-strategies.md |
| Agent |
Multi-agent orchestration |
AgentWorkflow(agents=[...]) |
references/agent-patterns.md |
| Workflow |
Event-driven pipeline |
class MyFlow(Workflow): @step |
references/workflows.md |
| Graph |
Knowledge graph |
PropertyGraphIndex.from_documents(docs) |
references/property-graph-index.md |
| Evaluate |
RAG evaluation |
FaithfulnessEvaluator().evaluate_response(...) |
references/evaluation-observability.md |
| Deploy |
Production deployment |
deploy_workflow(workflow=MyFlow()) |
references/production-deployment.md |
When to Use This Skill
Load this skill any time you are:
- Building a RAG pipeline over enterprise or personal data
- Comparing LlamaIndex with LangChain, Haystack, or DSPy
- Designing multi-agent systems with handoff between specialist agents
- Deploying an LLM application to production with observability
- Constructing knowledge graphs from unstructured documents
- Debugging common LlamaIndex failures (retrieval miss, handoff bug, async issues)
When NOT to Use LlamaIndex — Framework Routing Guide
This skill is part of a portfolio of framework skills. When deciding which framework fits, use this routing table:
| Scenario |
Reach for |
Why |
| I have documents I need to query |
LlamaIndex |
Data ingestion, hybrid retrieval, reranking, and knowledge graphs are first-class primitives |
| I have agents I need to orchestrate |
LangGraph |
State-machine semantics, time-travel debugging, and human-in-the-loop pauses are the core design |
| I have a tool I need to wrap as an agent |
PydanticAI |
Type-safe agent definitions with dependency injection, minimal abstraction over LLM calls |
| Data-heavy RAG over PDFs, SQL, Slack, 200+ sources |
LlamaIndex |
LlamaHub connectors, LlamaParse for documents, hybrid retrieval out of the box |
| Complex multi-agent state machines with checkpoints |
LangGraph |
Graph topology control — supervisor, subgraphs, hierarchical teams, built-in checkpointer |
| Agent-centric app where type safety matters more than data pipelines |
PydanticAI |
Agents as Pydantic models, DI, structured outputs — the data layer is your code |
| Document parsing quality matters (tables, charts, handwriting) |
LlamaIndex |
LlamaParse is purpose-built for this |
| Production NLP search pipelines |
Haystack |
Pipeline composition model is more mature for search-specific workloads |
| Optimization-driven prompt programming |
DSPy |
Compiled prompt programs, not retrieval pipelines |
Reference Files
| Reference |
Load when |
File |
| Core Architecture |
Understanding the 7 primitives, Settings, data flow |
references/architecture.md |
| RAG Strategies |
Building RAG pipelines from basic to advanced |
references/rag-strategies.md |
| Agent Patterns |
Multi-agent orchestration with AgentWorkflow |
references/agent-patterns.md |
| Workflows |
Event-driven step composition and durable execution |
references/workflows.md |
| Production & Deployment |
llama-deploy, debugging, failure modes |
references/production-deployment.md |
| Property Graph Index |
Knowledge graph construction and hybrid retrieval |
references/property-graph-index.md |
| Evaluation & Observability |
Metrics, tracing, span-attached scoring |
references/evaluation-observability.md |
| Integration Ecosystem |
Vector stores, LlamaHub, LlamaParse, ecosystem |
references/integration-ecosystem.md |
| FAQ & Troubleshooting |
Common errors and their fixes |
references/faq-and-troubleshooting.md |
| Worked RAG Example |
Complete end-to-end pipeline from ingest to deploy |
references/example-rag-pipeline.md |
| Evaluation Workflow |
ParamTuner, evaluators, batch scoring, best practices |
references/evaluation-workflow.md |
Template Files
| Template |
When to use |
File |
| Basic RAG |
Single-source query, getting started |
templates/basic-rag.py |
| Agentic RAG |
Multi-source data with agent routing |
templates/agentic-rag.py |
| Custom Workflow |
Custom control flow, branching logic |
templates/custom-workflow.py |
| Production Deploy |
Wrapping a workflow as a microservice |
templates/production-deploy.py |
Scripts
| Script |
Purpose |
File |
| check-setup |
Verify LlamaIndex installation and configuration |
scripts/check-setup.py |
Troubleshooting — Structured Recovery Guide
When something goes wrong, find your symptom and follow the recovery path:
Retrieval & Answer Quality
| Symptom |
Likely cause |
Immediate fix |
Permanent fix |
Reference |
| Answers are poor or hallucinated |
No reranker on hybrid retrieval |
Add CohereRerank(top_n=5) as node_postprocessor |
Reranking is mandatory for any production RAG |
references/rag-strategies.md |
| Retrieval misses obvious content |
Default chunking breaks semantics |
Switch to SemanticSplitterNodeParser(breakpoint_percentile_threshold=95) |
Tune chunk size with ParamTuner |
references/rag-strategies.md |
| Wrong tenant's data returned |
Missing metadata filters |
Add MetadataFilters(filters=[ExactMatchFilter(key="tenant_id", ...)]) |
Always wire metadata filters at retriever level |
references/rag-strategies.md |
| Only one type of query works well |
Single retrieval strategy |
Combine BM25 + vector via hybrid retriever |
Add RouterQueryEngine for query-type routing |
references/rag-strategies.md |
Agent & Workflow Failures
| Symptom |
Likely cause |
Immediate fix |
Permanent fix |
Reference |
| Agent waits silently after handoff |
AgentWorkflow handoff bug |
Extend FunctionAgent.take_step to re-locate last user message |
Apply the handoff fix on all production agents |
references/agent-patterns.md |
| Workflow doesn't run |
Forgot await |
Add await before w.run(...) and all step calls |
All step methods are async coroutines |
references/workflows.md |
| Step executes but result is lost |
State not persisted |
Use ctx.store.edit_state() for shared state |
Only ctx.store survives across steps |
references/workflows.md |
| Crash loses all progress |
No checkpoint snapshots |
Add Context.to_dict() save on step completion |
Durable workflows need explicit checkpointing |
references/workflows.md |
Deployment & Observability
| Symptom |
Likely cause |
Immediate fix |
Permanent fix |
Reference |
| llama-deploy deployed but requests time out |
Redis not running |
Start redis-server |
Redis is mandatory — control plane won't route without it |
references/production-deployment.md |
| Spans missing in observability UI |
Instrumentation called too late |
Move instrument() call before workflow instantiation |
Always instrument before creating any Workflow object |
references/production-deployment.md |
| Wrong data returned (cross-tenant) |
Missing metadata filters |
Add tenant filter to all retrievers |
Filter at retriever level, not in post-processing |
references/production-deployment.md |
Recovery Workflow
For any failure, follow this cycle:
- Identify the symptom from the tables above
- Apply the immediate fix — this gets you running
- Implement the permanent fix — this prevents recurrence
- Verify with evaluation — run
FaithfulnessEvaluator on a held-out query set
- Document the fix — add the root cause to
references/faq-and-troubleshooting.md
1---2name: llamaindex3description: Expert skill for building LLM applications with the LlamaIndex framework — RAG pipelines, multi-agent orchestration, event-driven workflows, knowledge graph construction, production deployment, and evaluation. Use when working with LlamaIndex or comparing RAG and agent orchestration frameworks.4license: MIT5---67# LlamaIndex Expert Skill89LlamaIndex is an MIT-licensed Python framework for building LLM applications over your data. In 2026, it has evolved from a RAG indexing library into an event-driven workflow framework with integrated production runtime (llama-deploy), agent orchestration (AgentWorkflow), knowledge graph construction (PropertyGraphIndex), and OpenTelemetry-native observability.1011The framework is organized around seven core primitives: **Reader** (data loaders), **Document/Node** (chunked content model), **Index** (data structures over Nodes), **Retriever** (relevant Node selection), **Query Engine** (retriever + synthesis), **Agent** (LLM with tools), and **Workflow** (event-driven orchestration).1213## Key Principles1415> These principles govern every decision when building with LlamaIndex. Read them before proceeding to the reference guides.16171. **Decouple retrieval chunks from synthesis chunks.** The embedding representation that retrieves well differs from the context representation that generates well. Use `SentenceWindowNodeParser` + `MetadataReplacementNodePostProcessor` for this pattern.182. **Rerank before you generate.** Hybrid retrieval + reranker is the minimum viable production RAG configuration.193. **Agents are Workflows.** `FunctionAgent` and `AgentWorkflow` are pre-configured Workflows. Drop to raw `Workflow` when you need custom control flow.204. **Graphs are not just vector stores.** `PropertyGraphIndex` adds structural path traversal that vector similarity cannot provide — combine both for maximum retrieval quality.215. **Evaluate in the same process.** Span-attached evaluation preserves the connection between the output and the retrieval context that produced it.2223## Where to Start2425The pipeline has 9 phases from Ingest to Deploy. If you're joining mid-stream with existing work, find your entry point:2627| You already have... | Start at phase | What to do |28|---|---|---|29| Nothing — blank project | **Ingest** | Set up data loading, then proceed through the full pipeline |30| Documents in a directory | **Chunk** | Choose a chunking strategy, build your index |31| A working vector index | **Retrieve** | Add hybrid search, reranking, metadata filters |32| An existing RAG pipeline to harden | **Deploy** | Add observability, llama-deploy, production debugging |33| A need to measure and improve quality | **Evaluate** | Set up evaluators, ParamTuner, span-attached scoring |34| Nothing — comparing frameworks | See Framework Routing Guide | Don't start the pipeline — pick the right tool first |3536## Pipeline Mode3738Different tasks need different levels of rigor. Match your scope to a mode:3940| Mode | When | Phases to run | Skip |41|------|------|---------------|------|42| **Quick** | Single query, one source, exploration | Ingest → Chunk → Index → Retrieve | Reranking, metadata filters, observability, evaluation |43| **Full** | Production RAG, multiple sources, compliance | Ingest → Chunk → Index → Retrieve → Agent/Workflow → Deploy → Evaluate | Nothing — run all phases |44| **Evaluate** | Benchmarking, regression testing | Ingest → Chunk → Index → Evaluate | Retrieve, Agent, Workflow, Deploy (run offline) |45| **Graph** | Knowledge graph construction | Ingest → Chunk → Graph → Retrieve | Agent, Workflow, Deploy (query via graph index directly) |4647Rule of thumb: if you're shipping to users, run Full mode. If you're exploring, run Quick. If you're measuring, run Evaluate.4849## Quick Reference5051| Phase | Task | Approach | Reference |52|-------|------|----------|-----------|53| Ingest | Load data | `SimpleDirectoryReader("./data").load_data()` | `references/architecture.md` |54| Chunk | Parse documents into nodes | `SentenceSplitter(chunk_size=1024)` | `references/rag-strategies.md` |55| Index | Build vector index | `VectorStoreIndex.from_documents(docs)` | `references/rag-strategies.md` |56| Retrieve | Hybrid search + rerank | `BM25Retriever` + `CohereRerank` | `references/rag-strategies.md` |57| Agent | Multi-agent orchestration | `AgentWorkflow(agents=[...])` | `references/agent-patterns.md` |58| Workflow | Event-driven pipeline | `class MyFlow(Workflow): @step` | `references/workflows.md` |59| Graph | Knowledge graph | `PropertyGraphIndex.from_documents(docs)` | `references/property-graph-index.md` |60| Evaluate | RAG evaluation | `FaithfulnessEvaluator().evaluate_response(...)` | `references/evaluation-observability.md` |61| Deploy | Production deployment | `deploy_workflow(workflow=MyFlow())` | `references/production-deployment.md` |6263## When to Use This Skill6465Load this skill any time you are:66- Building a RAG pipeline over enterprise or personal data67- Comparing LlamaIndex with LangChain, Haystack, or DSPy68- Designing multi-agent systems with handoff between specialist agents69- Deploying an LLM application to production with observability70- Constructing knowledge graphs from unstructured documents71- Debugging common LlamaIndex failures (retrieval miss, handoff bug, async issues)7273## When NOT to Use LlamaIndex — Framework Routing Guide7475This skill is part of a portfolio of framework skills. When deciding which framework fits, use this routing table:7677| Scenario | Reach for | Why |78|----------|-----------|-----|79| I have documents I need to query | **LlamaIndex** | Data ingestion, hybrid retrieval, reranking, and knowledge graphs are first-class primitives |80| I have agents I need to orchestrate | **LangGraph** | State-machine semantics, time-travel debugging, and human-in-the-loop pauses are the core design |81| I have a tool I need to wrap as an agent | **PydanticAI** | Type-safe agent definitions with dependency injection, minimal abstraction over LLM calls |82| Data-heavy RAG over PDFs, SQL, Slack, 200+ sources | **LlamaIndex** | LlamaHub connectors, LlamaParse for documents, hybrid retrieval out of the box |83| Complex multi-agent state machines with checkpoints | **LangGraph** | Graph topology control — supervisor, subgraphs, hierarchical teams, built-in checkpointer |84| Agent-centric app where type safety matters more than data pipelines | **PydanticAI** | Agents as Pydantic models, DI, structured outputs — the data layer is your code |85| Document parsing quality matters (tables, charts, handwriting) | **LlamaIndex** | LlamaParse is purpose-built for this |86| Production NLP search pipelines | **Haystack** | Pipeline composition model is more mature for search-specific workloads |87| Optimization-driven prompt programming | **DSPy** | Compiled prompt programs, not retrieval pipelines |8889## Reference Files9091| Reference | Load when | File |92|-----------|-----------|------|93| Core Architecture | Understanding the 7 primitives, Settings, data flow | `references/architecture.md` |94| RAG Strategies | Building RAG pipelines from basic to advanced | `references/rag-strategies.md` |95| Agent Patterns | Multi-agent orchestration with AgentWorkflow | `references/agent-patterns.md` |96| Workflows | Event-driven step composition and durable execution | `references/workflows.md` |97| Production & Deployment | llama-deploy, debugging, failure modes | `references/production-deployment.md` |98| Property Graph Index | Knowledge graph construction and hybrid retrieval | `references/property-graph-index.md` |99| Evaluation & Observability | Metrics, tracing, span-attached scoring | `references/evaluation-observability.md` |100| Integration Ecosystem | Vector stores, LlamaHub, LlamaParse, ecosystem | `references/integration-ecosystem.md` |101| FAQ & Troubleshooting | Common errors and their fixes | `references/faq-and-troubleshooting.md` |102| Worked RAG Example | Complete end-to-end pipeline from ingest to deploy | `references/example-rag-pipeline.md` |103| Evaluation Workflow | ParamTuner, evaluators, batch scoring, best practices | `references/evaluation-workflow.md` |104105## Template Files106107| Template | When to use | File |108|----------|-------------|------|109| Basic RAG | Single-source query, getting started | `templates/basic-rag.py` |110| Agentic RAG | Multi-source data with agent routing | `templates/agentic-rag.py` |111| Custom Workflow | Custom control flow, branching logic | `templates/custom-workflow.py` |112| Production Deploy | Wrapping a workflow as a microservice | `templates/production-deploy.py` |113114## Scripts115116| Script | Purpose | File |117|--------|---------|------|118| check-setup | Verify LlamaIndex installation and configuration | `scripts/check-setup.py` |119120## Troubleshooting — Structured Recovery Guide121122When something goes wrong, find your symptom and follow the recovery path:123124### Retrieval & Answer Quality125126| Symptom | Likely cause | Immediate fix | Permanent fix | Reference |127|---------|-------------|---------------|---------------|-----------|128| Answers are poor or hallucinated | No reranker on hybrid retrieval | Add `CohereRerank(top_n=5)` as `node_postprocessor` | Reranking is mandatory for any production RAG | `references/rag-strategies.md` |129| Retrieval misses obvious content | Default chunking breaks semantics | Switch to `SemanticSplitterNodeParser(breakpoint_percentile_threshold=95)` | Tune chunk size with ParamTuner | `references/rag-strategies.md` |130| Wrong tenant's data returned | Missing metadata filters | Add `MetadataFilters(filters=[ExactMatchFilter(key="tenant_id", ...)])` | Always wire metadata filters at retriever level | `references/rag-strategies.md` |131| Only one type of query works well | Single retrieval strategy | Combine BM25 + vector via hybrid retriever | Add RouterQueryEngine for query-type routing | `references/rag-strategies.md` |132133### Agent & Workflow Failures134135| Symptom | Likely cause | Immediate fix | Permanent fix | Reference |136|---------|-------------|---------------|---------------|-----------|137| Agent waits silently after handoff | AgentWorkflow handoff bug | Extend `FunctionAgent.take_step` to re-locate last user message | Apply the handoff fix on all production agents | `references/agent-patterns.md` |138| Workflow doesn't run | Forgot `await` | Add `await` before `w.run(...)` and all step calls | All step methods are async coroutines | `references/workflows.md` |139| Step executes but result is lost | State not persisted | Use `ctx.store.edit_state()` for shared state | Only `ctx.store` survives across steps | `references/workflows.md` |140| Crash loses all progress | No checkpoint snapshots | Add `Context.to_dict()` save on step completion | Durable workflows need explicit checkpointing | `references/workflows.md` |141142### Deployment & Observability143144| Symptom | Likely cause | Immediate fix | Permanent fix | Reference |145|---------|-------------|---------------|---------------|-----------|146| llama-deploy deployed but requests time out | Redis not running | Start `redis-server` | Redis is mandatory — control plane won't route without it | `references/production-deployment.md` |147| Spans missing in observability UI | Instrumentation called too late | Move `instrument()` call before workflow instantiation | Always instrument before creating any Workflow object | `references/production-deployment.md` |148| Wrong data returned (cross-tenant) | Missing metadata filters | Add tenant filter to all retrievers | Filter at retriever level, not in post-processing | `references/production-deployment.md` |149150### Recovery Workflow151152For any failure, follow this cycle:1531. **Identify the symptom** from the tables above1542. **Apply the immediate fix** — this gets you running1553. **Implement the permanent fix** — this prevents recurrence1564. **Verify with evaluation** — run `FaithfulnessEvaluator` on a held-out query set1575. **Document the fix** — add the root cause to `references/faq-and-troubleshooting.md`
theheavenlyd3mon