Data and Tool Integrations

Purpose and Scope

LlamaIndex applications usually combine the core framework with extension packages that know how to talk to external systems. A data integration pulls content from a source such as a directory, Google Docs, Slack, Notion, or another service and converts it into LlamaIndex documents. A tool integration exposes an action that an agent can call, such as searching a service, loading content, or routing work through another component. This page helps you choose where each type fits before you install packages or wire them into an agent or retrieval workflow.

Sources: llama-index-integrations/README.md, docs/api_reference/api_reference/readers/index.md, docs/api_reference/api_reference/tools/index.md

The repository separates the foundation from optional integrations. The integrations README states that building LLM applications with LlamaIndex involves the core package plus the integrations required by the application, and that integrations are categorized by type with each category packaged as its own Python package. That split is important operationally: start from the stable core contracts, then add the smallest set of integration packages needed for your data sources, tools, callbacks, models, or deployment target. It also keeps connector dependencies from becoming mandatory for every installation.

Sources: llama-index-integrations/README.md

Relevant Source Files

llama-index-integrations/README.md - Establishes the monorepo-level integration model: applications use llama-index-core together with type-categorized integration packages, each published as its own Python package.
docs/api_reference/api_reference/readers/index.md - Defines the reader API reference entry point and the core reader types BaseReader and BasePydanticReader.
docs/api_reference/api_reference/tools/index.md - Defines the tool API reference entry point and the core tool types AsyncBaseTool, BaseToolAsyncAdapter, BaseTool, ToolMetadata, and ToolOutput.
llama-index-core/llama_index/core/tools/tool_spec/load_and_search/README.md - Documents the LoadAndSearchToolSpec pattern, including installation, agent usage, and the generated load and read tools.

Core Primitives

A Reader is the data-loading primitive. Official framework docs describe a data connector, also called a Reader, as a component that ingests data from different data sources and formats into a simple Document representation made of text and metadata. The API reference page for readers exposes BaseReader and BasePydanticReader, which are the core type names to look for when evaluating whether a connector behaves like a first-class LlamaIndex loader. In practice, readers are the first bridge between external content and later indexing, retrieval, query engines, or chat engines.

Sources: docs/api_reference/api_reference/readers/index.md

A Tool is the action primitive. Tools are what agents and tool-aware workflows call when the model decides that it needs an external capability. The tool API reference page centers on BaseTool, AsyncBaseTool, BaseToolAsyncAdapter, ToolMetadata, and ToolOutput. Those names reveal the contract: tools can be synchronous or asynchronous, can carry metadata that describes how they should be called, and return structured output rather than only free-form text. Tool integrations should therefore be judged not only by the service they connect to, but also by whether their metadata and output shape are suitable for agent planning.

Sources: docs/api_reference/api_reference/tools/index.md

The integration package family sits around these primitives. A reader package should ultimately produce documents that the core indexing and retrieval modules can consume. A tool package should ultimately produce one or more tool objects that an agent, workflow, or query routing component can invoke. Utility integrations follow the same packaging philosophy but may support adjacent concerns, such as authentication helpers, service-specific clients, observability adapters, or framework glue. The shared design principle is that integration packages extend the system at typed seams rather than replacing the core application architecture.

Sources: llama-index-integrations/README.md

System-to-Code Mapping

User decision	Core contract to inspect	Source-backed names	What it means in an application
Load external data before indexing	Reader API	`BaseReader`, `BasePydanticReader`	Use a connector that returns documents suitable for indexing and retrieval.
Let an agent call an external action	Tool API	`BaseTool`, `AsyncBaseTool`, `BaseToolAsyncAdapter`	Pass tool objects into an agent or workflow so the LLM can request actions.
Describe tool behavior to a model	Tool metadata and output	`ToolMetadata`, `ToolOutput`	Keep names, descriptions, schemas, and returned values clear enough for tool selection and debugging.
Turn a large tool result into searchable context	Load-and-search tool spec	`LoadAndSearchToolSpec`, `load`, `read`	Split a tool call into loading data into an index and querying that index afterward.

This mapping is the safest way to compare integrations across the repository and the LlamaHub ecosystem. Do not start by asking only whether a connector mentions a vendor name. Ask which core contract it implements, what package must be installed, and where the output enters the rest of your application. If the component is a reader, its job is to normalize external content into documents. If it is a tool, its job is to expose an action with metadata and output that an agent can reason about.

Sources: docs/api_reference/api_reference/readers/index.md, docs/api_reference/api_reference/tools/index.md

Reader Integration Flow

A typical reader flow starts with an integration package and ends with indexed data. Official docs show the pattern with a reader import, a reader instance, and a load_data call that returns documents. After that, the same documents can be fed into an index, queried through a query engine, or used in a chat engine. The source evidence for this page gives the core API reference entry point rather than every reader implementation, so the durable lesson is the interface boundary: reader integrations should be selected for their ability to produce the common document representation expected by downstream LlamaIndex components.

Sources: docs/api_reference/api_reference/readers/index.md, llama-index-integrations/README.md

from llama_index.readers.google import GoogleDocsReader
 
loader = GoogleDocsReader()
documents = loader.load_data(document_ids=[...])

Because readers are integration packages, installation is usually package-specific. The official connector docs describe LlamaHub as the catalog for data loaders, while the repository integration README explains that integrations are categorized by type and distributed as their own Python packages. That means two readers can share the same BaseReader-style role while requiring very different service credentials, optional dependencies, or runtime permissions. Treat the reader API as the application-facing contract and the package README or module guide as the service-facing setup guide.

Sources: llama-index-integrations/README.md, docs/api_reference/api_reference/readers/index.md

Tool Integration Flow

A tool integration becomes most useful when an agent can choose it at the right moment and interpret its result. The core tool API reference names both synchronous and asynchronous base classes, plus an adapter type. This matters when you mix integrations: one package may expose a normal BaseTool, while another may be asynchronous and better suited to an async workflow or agent runtime. ToolMetadata and ToolOutput are equally important because they shape the communication between the model, the framework, and your code. Poor descriptions or ambiguous outputs make otherwise capable tools difficult for agents to use reliably.

Sources: docs/api_reference/api_reference/tools/index.md

The LoadAndSearchToolSpec README shows a concrete tool-composition pattern. It wraps another tool so an agent can perform separate loading and reading of data. The README explains why: some tools return information that is larger than, or close to, the model context window. Instead of forcing that entire result into one prompt, the wrapper loads the returned data into an index and then exposes a reading step that searches the index for a query. This turns oversized tool output into a retrievable local knowledge source inside the agent interaction.

Sources: llama-index-core/llama_index/core/tools/tool_spec/load_and_search/README.md

pip install llama-index-tools-wikipedia

from llama_index.core.tools.tool_spec.load_and_search import LoadAndSearchToolSpec
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.tools.wikipedia.base import WikipediaToolSpec
from llama_index.llms.openai import OpenAI
 
wiki_spec = WikipediaToolSpec()
tool = wiki_spec.to_tool_list()[1]
 
agent = FunctionAgent(
    tools=LoadAndSearchToolSpec.from_defaults(tool).to_tool_list(),
    llm=OpenAI(model='gpt-4.1'),
)
 
await agent.run('who is ben affleck married to')

The generated behavior is intentionally simple: load calls the wrapped function and loads the data into an index, while read searches that index for the specified query. That division is a practical pattern for agents that need to inspect large external results without losing context budget. It also illustrates how tool specs can be higher-order components: they do not merely connect to a service, they reshape an existing tool into a more agent-friendly interaction model.

Sources: llama-index-core/llama_index/core/tools/tool_spec/load_and_search/README.md

Compact API Reference

Component	Kind	Source-backed contract	Use when
`BaseReader`	Reader base type	Reader API member	You need a connector that loads external data into LlamaIndex documents.
`BasePydanticReader`	Reader base type	Reader API member	You want a reader integrated with Pydantic-style configuration or validation patterns.
`BaseTool`	Tool base type	Tool API member	You expose a callable capability to an agent or tool-aware workflow.
`AsyncBaseTool`	Async tool base type	Tool API member	The tool performs asynchronous work or runs inside async agent execution.
`BaseToolAsyncAdapter`	Adapter	Tool API member	You need to adapt tool behavior across sync and async boundaries.
`ToolMetadata`	Tool description data	Tool API member	You need the model and framework to understand a tool name, description, or schema.
`ToolOutput`	Tool result data	Tool API member	You need a structured result from a tool call.
`LoadAndSearchToolSpec`	Tool spec	Load-and-search README	You want to wrap a large-result tool into `load` and `read` tools for agent use.

Use this reference as a checklist during integration selection. First, identify whether your problem is loading data, invoking an action, or adding supporting utility behavior. Second, find the integration package in the appropriate category and confirm the install command and credentials. Third, inspect whether the package exposes one of the core reader or tool surfaces shown above. Finally, test the component in the smallest possible flow: load a few documents, call a single tool, or wrap one existing tool with LoadAndSearchToolSpec before embedding it in a larger agent application.

Sources: docs/api_reference/api_reference/readers/index.md, docs/api_reference/api_reference/tools/index.md, llama-index-core/llama_index/core/tools/tool_spec/load_and_search/README.md

Next Steps

After choosing a connector, continue to the data workflow pages that explain documents, nodes, ingestion pipelines, and indexes. After choosing a tool, continue to the tool and agent pages so you can decide whether the tool belongs in a simple agent, a workflow-based agent, or a larger multi-agent pattern. If your selected integration is hosted outside the core package, keep its package README close: the LlamaIndex contract tells you how it plugs in, while the integration package tells you which service credentials, dependencies, and operational constraints it needs.

Sources: llama-index-integrations/README.md

Ask a question...