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. Citations — include source references in your agent’s answers.

Set up the PageIndex client

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

export PAGEINDEX_API_KEY="your-pageindex-key"

from pageindex import PageIndexClient
 
client = PageIndexClient(index="cloud")

export OPENAI_API_KEY="your-openai-key"

from pageindex import PageIndexClient
 
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=16000,
    system=instructions,
    tools=client.as_anthropic_tools(),
)
 
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

import asyncio
 
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 def main():
    async for message in query(prompt=input_messages(), options=options):
        print(message)
 
asyncio.run(main())

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()

Answers then cite their sources with <cite doc="report.pdf" page="12"/> tags.

Block-level citations — cloud only. Local citations stop at the page. On cloud, a citation also carries a block attribute naming one layout block:

Revenue increased during the reporting period. <cite doc="report.pdf" page="12" block="p12_text_3"/>

get_citations() parses the tags in the agent’s answer into a list, resolving each doc name to a document ID and each block to its position:

citations = client.get_citations(answer)
# [{'document': 'report.pdf', 'doc_id': 'pi-…', 'page': 12,
#   'block_id': 'p12_text_3', 'bbox': [78, 24, 293, 44], 'block_type': 'text', 'text': '…'}]

bbox is [x0, y0, x1, y1] in thousandths of the page’s width and height, origin top-left, and comes only when the block could be read — use citation.get("bbox").

An agent’s answer carries the same tags as a chat() answer, so the rest works the same: see Display the citations to rewrite them as numbered links, and Highlight the cited region to draw a citation’s box on the page image.