Llamaindex Knowledge Patch

LlamaIndex Knowledge Patch

Use this skill when writing, reviewing, migrating, or debugging LlamaIndex applications. Inspect the application's installed distributions and lockfile before applying package-specific advice because core and integration packages are released independently.

Prefer project code, installed-package metadata, and tests when they disagree with this guidance. Load only the reference files relevant to the current task.

Reference index

Breaking migrations first

Replace removed configuration abstractions

Do not build new code around ServiceContext or LLMPredictor. Use Settings for process-wide defaults, or pass the LLM, embedding model, and transformations directly when configurations must coexist.

from llama_index.core import Settings

Settings.llm = llm
Settings.embed_model = embed_model

Audit custom readers, nodes, output parsers, tools, models, validators, serialization, and integrations for Pydantic v2 behavior.

Upgrade the package family coherently

Do not assign one release number to every llama-index-* distribution. Resolve core and integrations together under their actual independent versions and constraints, test the resulting environment, and preserve its lockfile.

from importlib.metadata import version

core_version = version("llama-index-core")
starter_version = version("llama-index")

The v0.12 transition drops Python 3.8. Check each selected distribution's metadata because newer packages may require a later interpreter.

Redesign legacy pipelines as workflows

A workflow is not a renamed QueryPipeline DAG. Model control flow with typed events, asynchronous @step methods, branches or loops, Context, streaming, and checkpointable execution. Use llama_index.core.workflow inside core applications; standalone workflow applications can use the workflows import surface from llama-index-workflows.

Treat current agent execution as asynchronous

Import current workflow agents from llama_index.core.agent.workflow. A call to agent.run(...) or workflow.run(...) returns an awaitable handler, not a finished response. Keep that handler if live events are needed, then await the same object for the final result.

handler = agent.run("What is 12 times 34?")
async for event in handler.stream_events():
    ...
result = await handler

Legacy provider-specific agent, runner, and worker examples do not describe this execution model.

Ingestion and persistence quick reference

Own document updates explicitly

Use IngestionPipeline when an application needs transformation caching, document update strategies, or direct vector-store insertion. VectorStoreIndex.from_documents remains useful for simple construction, but it does not replace an explicit update lifecycle.

Stable document.doc_id and node.ref_doc_id values drive duplicate, update, and deletion decisions. A strategy that deletes records absent from the input requires a complete authoritative inventory; do not apply it to a partial crawl.

Keep pipeline cache and document state distinct

Cache identity includes both a node and its transformation. A custom transformation whose behavior changes without changing its stable serialized settings or hash can reuse stale output.

pipeline.persist("./pipeline-state")
pipeline.load("./pipeline-state")

This cache is separate from docstore state. Use pipeline.arun() for async execution. Use process-based num_workers only when transformations and client objects are picklable and multiprocessing is actually beneficial.

Verify both sides of persisted indexes

StorageContext.persist() saves local stores; it does not necessarily copy an external vector collection. The remote collection may likewise lack node text, mappings, or document state held locally.

from llama_index.core import StorageContext, load_index_from_storage

index.storage_context.persist(persist_dir="./storage")
storage_context = StorageContext.from_defaults(persist_dir="./storage")
index = load_index_from_storage(storage_context)

On restore, verify the remote collection, embedding compatibility, and expected index ID. Rebuild or explicitly validate persisted vector indexes after an embedding model or embedding configuration change.

Agents and workflows quick reference

Select agents by tool interface

Use FunctionAgent when the selected LLM provides compatible native tool calling, ReActAgent for text-parsed reasoning and actions, and CodeActAgent for code-action scenarios. Plain synchronous or asynchronous callables can be tools; type hints and docstrings define their schemas. Use FunctionTool when metadata or adaptation must be explicit.

from llama_index.core.agent.workflow import FunctionAgent

def multiply(a: float, b: float) -> float:
    """Multiply two numbers."""
    return a * b

agent = FunctionAgent(tools=[multiply], llm=llm)

Separate memory, run state, and resources

Create conversation Memory explicitly and pass it to run. Keep per-run, serializable execution state in asynchronous ctx.store; inject live clients, indexes, models, and configuration as workflow resources rather than placing them in checkpointable state.

from llama_index.core.memory import Memory

memory = Memory.from_defaults(session_id="session-123", token_limit=40000)
response = await agent.run("...", memory=memory)

For dynamic fan-out, emit work with Context.send_event and join with Context.collect_events; completion order may differ from input order. Call workflow.validate() in tests or at startup to catch invalid typed event graphs before execution.

Upgrade verification checklist

After changing core, integrations, embeddings, agents, or workflows:

1. Resolve actual package constraints and retain the lockfile.
2. Run ingestion against representative new, updated, and deleted documents.
3. Reload persistence with the real external vector collection available.
4. Exercise synchronous and asynchronous retrieval and reranking paths.
5. Stream agent or workflow events and await the final handler result.
6. Validate workflow graphs and checkpoint only serializable run state.
7. Recheck node counts, boundaries, citation identities, and metadata values.
8. Pin integration defaults that must not drift with package upgrades.