Plug a Knowledge Space into an AI Agent

A .indx archive is a portable knowledge space: structure, relationships, and semantic metadata packed into one file. This guide makes it as easy to plug into an AI agent as a USB drive — load it once, hand it to whichever framework you use, and your agent can search, explore, and cite your documents.

from indx.agent import connect

kb = connect("ai-ready/handbook.indx")   # load the "USB drive"
tools = kb.openai()                       # plug into your framework — done

Every framework is one method call on the same kb. Pick yours below.

What your agent gets

connect() exposes three read-only tools, the same retrieval path the CLI and SDK use:

| Tool | What it does | When the agent calls it | |---|---|---| | indx_search | Semantic search → ranked text chunks with source, type, and score | To ground and cite an answer | | indx_overview | Describes the space: counts, document types, sample summaries | To learn what the space is about first | | indx_get_document | Fetches one document’s full text + metadata | To read a promising source in full |

Each result is flat and JSON-primitive — exactly what a model reads cleanly out of a tool call.

Install

The connector layer lives behind extras, so a bare pip install indx stays light. Install the adapter for your framework — or indx[agent] for all of them:

pip install "indx[agent]"           # every framework adapter + the MCP server
# …or just the one you need:
pip install "indx[langchain]"       # LangChain
pip install "indx[openai-agents]"   # OpenAI Agents SDK
pip install "indx[pydantic-ai]"     # Pydantic AI
pip install "indx[claude-agent]"    # Claude Agent SDK
pip install "indx[mcp]"             # the universal MCP server (Mastra, Cursor, Claude Desktop…)

You also need a built archive. Any build produces one — even fully offline:

indx ./docs --out ./ai-ready --offline   # or your cloud/local stack

Plug it in

Load the archive once, then call the method for your framework. Every call returns native objects for that framework — no indx types leak through.

LangChain

from indx.agent import connect

kb = connect("ai-ready/handbook.indx")

# Agentic path: StructuredTools for a tool-calling agent.
tools = kb.langchain()

# Classic RAG path: a BaseRetriever for any retrieval chain.
retriever = kb.langchain_retriever(k=5)
docs = retriever.invoke("how long is data retained?")

OpenAI Agents SDK

from agents import Agent, Runner
from indx.agent import connect

kb = connect("ai-ready/handbook.indx")

agent = Agent(name="Researcher", tools=kb.openai())
result = Runner.run_sync(agent, "What's our remote-work policy? Cite the source.")
print(result.final_output)

Pydantic AI

from pydantic_ai import Agent
from indx.agent import connect

kb = connect("ai-ready/handbook.indx")

agent = Agent("openai:gpt-5-mini", tools=kb.pydantic_ai())
print(agent.run_sync("Summarize the onboarding guide.").output)

Claude Agent SDK

from claude_agent_sdk import ClaudeAgentOptions, query
from indx.agent import connect

kb = connect("ai-ready/handbook.indx")

options = ClaudeAgentOptions(mcp_servers={"indx": kb.claude()})
async for message in query(prompt="Find our incident-response runbook.", options=options):
    print(message)

kb.claude() builds an in-process MCP server — no subprocess, no socket.

Any agent, any language: the MCP server

Model Context Protocol is the universal connector. One command turns a knowledge space into a live endpoint that any MCP client speaks — including the TypeScript Mastra framework, Cursor, and Claude Desktop — with no Python glue on the client side.

indx mcp ai-ready/handbook.indx

Point your client at the command. For Claude Desktop / Cursor, add it to the MCP servers config:

{
  "mcpServers": {
    "indx": { "command": "indx", "args": ["mcp", "ai-ready/handbook.indx"] }
  }
}

The server advertises indx_search, indx_overview, and indx_get_document.

Choose a transport with --transport (stdio default, or sse / streamable-http for networked clients), and a client-facing name with --name.

No framework? Raw tool specs

For the bare Chat Completions or Messages API, emit the tool specs and dispatch calls yourself:

from indx.agent import connect

kb = connect("ai-ready/handbook.indx")

tools = kb.openai_schema()        # OpenAI function-tool specs
# tools = kb.anthropic_schema()   # Anthropic tool specs

# When the model asks for a tool call, run it and feed the result back:
result = kb.call("indx_search", {"query": "data retention", "k": 5})

Tuning

connect() takes a few options that flow into every adapter:

| Option | Default | Effect | |---|---|---| | name | archive stem | The label shown to the agent and used as the MCP server name. | | default_k | 5 | Hits returned when the agent omits k. | | with_context | False | Include each hit’s neighbor chunks in hit.context for wider grounding. |

kb = connect("ai-ready/handbook.indx", name="company-handbook", default_k=8, with_context=True)

Vendor-neutral models with LiteLLM

indx connectors give your agent vendor-neutral tools. LiteLLM gives it vendor-neutral models — the same provider/model string reaches on-prem runtimes (Ollama, vLLM) and every managed cloud (AWS Bedrock, Azure OpenAI, GCP Vertex, Anthropic, OpenAI). Together they decouple your agent from any single vendor on both sides.

Build side — indx enrichment. indx ships a litellm LLM and embedder, so the knowledge space itself can be built against any provider:

indx ./docs --out ./ai-ready --llm litellm:bedrock/anthropic.claude-3-5-sonnet-20240620-v1:0 \
                             --embedder litellm:azure/my-embedding-deployment

Agent side — the reasoning model. Each framework can drive its model through LiteLLM while calling the very same indx tools:

OpenAI Agents SDK — Agent(model=LitellmModel("anthropic/claude-3-5-sonnet"), tools=kb.openai()).
Pydantic AI — point the agent at a LiteLLM-compatible model string.
Claude Agent SDK — run a LiteLLM proxy and set ANTHROPIC_BASE_URL to it, so the SDK reaches Bedrock/Vertex/Azure-hosted models while kb.claude() supplies the search tools.

The connector is unchanged across all of these — kb is the same object no matter which vendor powers the model.