read_document converts the attached .docx to HTML. Every edit anchor must be markup copied verbatim from this tool or from
search_document, so read a spot before you edit it.
The agent should reach for this when it needs the shape of a document - what sections exist, how a table is
laid out, where a new paragraph belongs. If the agent already knows the text it needs,
search_document is faster and cheaper.
Parameters
integer
default:"1"
1-based first page to return.
integer
1-based last page to return. Omit for a default span starting at
start_page._meta under com.vespper/session-id. See
Document sessions. Vespper SDK
auto-patching supplies this metadata automatically.
Returns
string
The HTML projection of the requested page range. Its last line always states
the range in words, for example
Pages 3-7 of 42 returned; 35 pages remain.integer
First page actually returned.
integer
Last page actually returned. May be lower than the
end_page you asked for,
because a call is also capped by a token budget.integer
Pages in the whole document.
integer
Approximate token count of the returned
html.integer
Approximate token count of the whole document.
boolean
true when pages remain past end_page. Fetch them with start_page = end_page + 1.integer
Size of the current session document.
integer
Revision of the session document used for this read.
Example
Paging through a long document
A wideend_page is still bounded by the per-call token budget, so on a large document
has_more stays true. Keep calling with start_page = end_page + 1 until it is false.
Anchors copied from any page match the whole document, so you can edit straight from a page
without re-reading it. Don’t page through a document hunting for a string - search for it.
Existing tracked changes
Changes already in the document render as<ins> and <del> elements, each carrying a
data-author. Use them to see which changes are pending and who made them before you accept,
reject, or modify one - see
Resolving a tracked change.
Errors
Failures return{ error, message } rather than raising: message is
agent-facing copy that says what to do next. Out of credits returns HTTP 402
upstream and a message that says so. An unknown, closed, or user-mismatched
session returns document session not found.