Connect your own agent to PageIndex to find and read documents. Configure your framework with PageIndex’s instructions and retrieval tools, then choose the documents or folder for each question. For a ready-to-run document-QA agent, use LLM Integration.

1. Set up the PageIndex client — connect your library or index a document.
2. Connect your agent — configure instructions and tools for your framework.
3. Choose documents or a folder — prepare the context and question.
4. Add citations — choose a citation format for your agent’s answers.

Set up the PageIndex client

Only the index side needs configuring — your agent framework brings its own model.

import os
from pageindex import PageIndexClient
 
os.environ["PAGEINDEX_API_KEY"] = "your-pageindex-key"
 
client = PageIndexClient(index="cloud")

import os
from pageindex import PageIndexClient
 
os.environ["OPENAI_API_KEY"] = "your-openai-key"
 
client = PageIndexClient(
    index="gpt-5.6-luna",     # model that builds the tree index
)

Use an existing document ID from client.list_documents(), or submit a new document. wait=True blocks until it is ready:

doc_id = client.submit_document("./2023-annual-report.pdf", wait=True)["doc_id"]

See Client Configuration for the full parameter list.

Connect your agent

The system prompt — agent_instructions()

PageIndex’s default system prompt. You can also pass your own system prompt.

instructions = client.agent_instructions()

Define messages as shown below.

from agents import Agent, Runner
 
agent = Agent(
    name="PageIndex",
    instructions=instructions,
    tools=client.as_openai_tools(),
    model="gpt-5.6-sol",
)
 
result = Runner.run_sync(agent, messages)
print(result.final_output)

pip install "anthropic>=0.108.0"

import anthropic
 
anthropic_client = anthropic.Anthropic()
runner_config = dict(
    model="claude-opus-5",
    max_tokens=8192,
    system=instructions,
    tools=client.as_anthropic_tools(),
    max_iterations=10,
    cache_control={"type": "ephemeral"},
)
 
runner = anthropic_client.beta.messages.tool_runner(
    **runner_config,
    messages=messages,
)
final = runner.until_done()
print(final.content[0].text)

pip install claude-agent-sdk

from claude_agent_sdk import query, ClaudeAgentOptions
 
options = ClaudeAgentOptions(
    model="claude-opus-5",
    system_prompt=instructions,
    mcp_servers={"pageindex": client.as_claude_mcp()},
    allowed_tools=["mcp__pageindex"],
)
 
async def input_messages():
    for message in messages:
        yield {
            "type": "user",
            "message": message,
            "parent_tool_use_id": None,
            "session_id": "",
        }
 
async for message in query(prompt=input_messages(), options=options):
    print(message)

tools = client.agent_tools()

agent = Agent(**client.openai_agent_config(model="gpt-5.6-sol"))
 
runner_config = client.anthropic_runner_config(model="claude-opus-5")
 
options = ClaudeAgentOptions(**client.claude_agent_config(), model="claude-opus-5")

Choose documents or a folder

Build the messages used in the integration examples above. First, tell the agent where to look with document_context() or folder_context(). These return text containing the selected documents’ or folder’s metadata and retrieval guidance. Choose one of the following:

context = client.document_context(doc_id)

context = client.document_context([doc_id_1, doc_id_2])

context = client.folder_context("my-folder-id")

context = "\n\n".join(filter(None, [
    client.folder_context("my-folder-id"),
    client.document_context(doc_id),
]))

Put the selected context in its own first user message, then add the question as a second message. All framework examples above use this list:

messages = [
    {"role": "user", "content": context},
    {"role": "user", "content": "Summarize the auditor's concerns."},
]

To let the agent discover documents across your library, omit the context message and pass just the question. folder_context("root") also leaves discovery unrestricted and returns an empty string.

The context steers the agent; it does not restrict tool access to the selected documents or folder. The framework tools retain access to your library. Both context methods raise PageIndexAPIError if a selected document or folder is missing or inaccessible.

Citations

Replace instructions = client.agent_instructions() in Connect your agent with the following, before creating the agent or runner:

instructions = client.agent_instructions() + "\n\n" + client.citation_prompt(format="cite")

Choose the citation format with format=: