🤖 Integrate PageIndex with Your Own Agent
The Chat API runs PageIndex’s document-QA agent for you. If you would rather run your own agent, PageIndex hands you the pieces instead: the orchestration prompt and the retrieval tools, shaped for whichever framework you use.
Each *_config helper fills every slot of its framework’s agent in one call. Each is sugar over the explicit pieces — agent_instructions() for the system prompt and as_openai_tools() / as_anthropic_tools() / as_claude_mcp() for the tools — so you can swap in your own prompt whenever you need to.
Locally, doc_id is enforced at the tool layer, not just prompted: out-of-scope lookups return NOT_FOUND. On cloud documents the tools take no allowlist, so doc_id targets at the prompt level only.
OpenAI Agents SDK
from agents import Agent, Runner
agent = Agent(**client.openai_agent_config(doc_id=doc_id))
result = Runner.run_sync(agent, "Summarize the auditor's concerns.")openai_agent_config() provides the name, instructions, and tools an OpenAI agent needs — plus model when the client has a chat model configured, and model_settings carrying prompt-cache marks for LiteLLM-routed Claude models.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| doc_id | string or List[string] | Document ID(s) to target. | None |
| include_management | boolean | Also expose tools that modify the library. | False |
| model | string | Backend model name; overrides the client’s chat model. | None |
| model_settings | ModelSettings | Your own settings, merged on top of the bundled cache marks — your fields win. | None |
| name | string | Agent display name; also seeds SDK-derived handoff and as_tool names. | "PageIndex" |
Tools only
tools = client.as_openai_tools(doc_id=doc_id)On cloud, this is the full live read tool set (search, folders, images — as enabled for your key), discovered from the PageIndex MCP server and executed from your process, so it works with any model backend. Pass hosted=True to hand the connection to OpenAI instead — one hosted MCP tool with server-side execution (lowest latency, OpenAI models on the Responses API only).
Locally, prompt caching happens server-side for OpenAI models; LiteLLM-routed Claude (Anthropic, Bedrock, Vertex) gets its cache marks from the bundled model_settings. Replacing that key wholesale drops the marks — pass model_settings to layer on top instead.
Anthropic SDK tool runner
pip install 'pageindex[anthropic]'runner = anthropic_client.beta.messages.tool_runner(
**client.anthropic_runner_config(model="claude-sonnet-4-6", doc_id=doc_id),
messages=[{"role": "user", "content": "Summarize the auditor's concerns."}],
)anthropic_runner_config() configures Anthropic’s native tool runner: the model, a per-model max_tokens default, the instructions as system, the tools, a 10-turn max_iterations, and a top-level cache_control so each loop turn re-reads the growing prompt from cache. Pop that key if you place your own breakpoints — the API allows four.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| model | string | Required — backend model name (also resolves the max_tokens default). | - |
| doc_id | string or List[string] | Document ID(s) to target. | None |
| include_management | boolean | Also expose tools that modify the library. | False |
| asynchronous | boolean | Build async runnables for AsyncAnthropic. | False |
| max_tokens | int | Per-turn output budget. | per model |
| max_turns | int | Agent-loop bound. | 10 |
| thinking | dict | Anthropic thinking config. Pass it here, not alongside the unpacked config, so the max_tokens default stays valid. | None |
Tools only
tools = client.as_anthropic_tools(doc_id=doc_id) # sync Anthropic client
tools = client.as_anthropic_tools(doc_id=doc_id, asynchronous=True) # AsyncAnthropicEach runner accepts only its own flavor. For a manual messages.create loop, serialize with [tool.to_dict() for tool in tools]. Requires anthropic>=0.108.0.
Claude Agent SDK
pip install 'pageindex[claude]'from claude_agent_sdk import ClaudeAgentOptions
options = ClaudeAgentOptions(**client.claude_agent_config(doc_id=doc_id))claude_agent_config() returns the system_prompt, the mcp_servers entry, and its allowed_tools pre-approval.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| doc_id | string or List[string] | Document ID(s) to target. | None |
| include_management | boolean | Also allow tools that modify the library. | False |
| server_name | string | Key the server is registered under; locally also the SDK server name. | "pageindex" |
Explicit form
options = ClaudeAgentOptions(
system_prompt=client.agent_instructions(doc_id=doc_id),
mcp_servers={"pageindex": client.as_claude_mcp(doc_id=doc_id)},
# Pre-approval only — the server itself is already gated.
allowed_tools=["mcp__pageindex"],
)On cloud, as_claude_mcp() returns the remote PageIndex MCP config. Locally it returns an in-process SDK MCP server exposing the agent tools.
Other agent frameworks
tools = client.agent_tools(doc_id=doc_id)agent_tools() returns plain Python functions that work with LangChain, PydanticAI, and other frameworks. Each takes JSON-serializable arguments, returns a JSON string, and reports failures inside that JSON rather than raising — except a cloud 401/403, which raises PageIndexAPIError.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| include_management | boolean | Also expose tools that modify the library. Locally, adds remove_document. | False |
| doc_id | string or List[string] | Local only — restrict the tools to these documents. Raises on cloud. | None |
Locally the set is browse_documents, get_document, get_document_structure, and get_page_content. On cloud it is the full live read tool set, discovered from the PageIndex MCP server when the method is called — one function per tool, signature and docstring synthesized from the server’s schemas, calls executed from your process over MCP.
include_management is gated by the URL on cloud: the default connects to the read-only endpoint (/mcp?tools=read), and True connects to the full /mcp tool list (upload, delete, …).
agent_instructions()
The orchestration guidance PageIndex’s own agent runs on — pass it as your agent’s system prompt, or append it to yours.
instructions = client.agent_instructions(doc_id=doc_id)Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| doc_id | string or List[string] | Appends the target documents’ names and metadata, directing the agent to work within them. | None |
| include_management | boolean | Fetch the guidance for the full tool set, matching include_management=True tools. | False |
On cloud these are the live instructions the PageIndex MCP server serves for your key’s tool set, so server-side guidance updates arrive without an SDK release. Locally it is the built-in guidance for the in-process tools.
It raises PageIndexAPIError if a doc_id does not exist, or if its name is shadowed by a newer same-name document — the name-addressed tools could not reach it. The *_config bundles, whose tools carry the doc_id scope, relax this to duplicates within the targeted set.