feat(context-grounding): read a page range of an indexed document

[SummerWangUiPath]

Why

Agents built on a context index can only search it. When a user names pages ("summarize pages 57 and 58") or a search hit continues on the next page, the agent has no way to read those pages. ECS adds a deterministic page read for one document, POST /v2/indexes/{indexId}/ReadPages (behind the PageRangeEnabled flag). This PR adds the SDK call for it and the agent.json setting that lets an agent opt into a page-reading tool.

What

uipath-platform: context_grounding.read_pages(name, source_document_id, start_page, end_page, folder_key=None, folder_path=None, include_system_indexes=False) and read_pages_async.

• They look the index up by name like unified_search, then post { sourceDocumentId, range: { from, to } } with the folder and job-key headers.
• Pages are 1-based, like page_number in search results. ECS allows at most 20 per call and validates the range itself.
• The result is the new ContextGroundingPageRange: source_document_id, source, reference, pages (ContextGroundingPage: page_number, content), missing_pages (past the end of the document), has_previous, has_next.

uipath: AgentContextSettings.read_pages (alias readPages, default False). It's the agent.json field that turns the page tool on for a context, following searchDuringIngestion.

SDK_REFERENCE.md lists the two new methods.

The consumer side is UiPath/uipath-langchain-python#1163 (a <context>_read_pages tool next to the context's search tool), which is blocked on this being released.

Backward compatibility

• An agent.json without readPages reads as False, so nothing changes for existing agents.
• An old SDK ignores the key (extra="allow"), so the toggle does nothing there; the version pins prevent that combination.

Testing

• uipath-platform: 3 new tests (5 runs; the 2 async tests run under both anyio backends). They cover the sync and async calls (URL, body, folder and job-key headers, user agent, parsed result) and the 400 path raising EnrichedException. The full suite passes.
• uipath: 5 new tests covering the default, alias and field-name parsing, round-trip, and reaching AgentContextResourceConfig. The full suite passes.
• ruff check, ruff format --check, mypy and the httpx linter are clean for both packages; check_dependency_version_bumps.py passes.
• End to end: a low-code agent (uipath run agent.json) with these packages and the langchain change read pages through the new endpoint and answered from them.

Versions

uipath-platform 0.2.40 → 0.2.41; uipath 2.14.41 → 2.14.42, with its uipath-platform lower bound raised to 0.2.41.

Development Packages

uipath-platform

[project]
dependencies = [
  # Exact version (copy-paste ready):
  "uipath-platform==0.2.41.dev1019467916",

  # Any version from this PR (uncomment to use a range instead):
  # "uipath-platform>=0.2.41.dev1019460000,<0.2.41.dev1019470000",
]

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true

[tool.uv.sources]
uipath-platform = { index = "testpypi" }

uipath

[project]
dependencies = [
  # Exact version (copy-paste ready):
  "uipath==2.14.42.dev1019467916",

  # Any version from this PR (uncomment to use a range instead):
  # "uipath>=2.14.42.dev1019460000,<2.14.42.dev1019470000",
]

[[tool.uv.index]]
name = "testpypi"
url = "https://test.pypi.org/simple/"
publish-url = "https://test.pypi.org/legacy/"
explicit = true

[tool.uv.sources]
uipath = { index = "testpypi" }
uipath-platform = { index = "testpypi" }

[tool.uv]
override-dependencies = ["uipath-platform==0.2.41.dev1019467916"]

[Copilot]

🟢 Approval recommended

The additive changes follow existing SDK patterns, include focused coverage, and have no identified blocking issues.

No open issues 🎉

What changed in this PR

Adds deterministic document page-range reading to the UiPath SDK and an opt-in setting for agents to expose a page-reading tool.

Changes:

• Adds synchronous and asynchronous page-reading methods and response models.
• Adds the backward-compatible readPages setting and focused tests.
• Updates SDK documentation, package versions, and the platform dependency minimum.

File	Description
packages/​uipath/​uv.lock	Updates SDK and platform versions.
packages/​uipath/​tests/​agent/​models/​test_agent.py	Tests setting defaults, parsing, and serialization.
packages/​uipath/​src/​uipath/​agent/​models/​agent.py	Adds the readPages opt-in setting.
packages/​uipath/​src/​uipath/​_resources/​SDK_REFERENCE.md	Documents both page-reading methods.
packages/​uipath/​pyproject.toml	Bumps SDK version and platform dependency minimum.
packages/​uipath-platform/​uv.lock	Updates platform version.
packages/​uipath-platform/​tests/​services/​test_context_grounding_service.py	Tests requests, responses, headers, and errors.
packages/​uipath-platform/​src/​uipath/​platform/​context_grounding/​context_grounding.py	Defines page and page-range response models.
packages/​uipath-platform/​src/​uipath/​platform/​context_grounding/​_context_grounding_service.py	Implements synchronous and asynchronous page reads.
packages/​uipath-platform/​src/​uipath/​platform/​context_grounding/​__init__.py	Exports the new response models.
packages/​uipath-platform/​pyproject.toml	Bumps platform version.

_{Review effort: Balanced}

[github-actions]

🚨 Heads up: uipath-integrations cross-tests are FAILING 🚨

Your changes may break one or more integrations in uipath-integrations-python:

• uipath-openai-agents
• uipath-google-adk
• uipath-agent-framework
• uipath-llamaindex
• uipath-pydantic-ai

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud