Search and cite knowledge within a task¶
Search authorized knowledge, read source evidence, and select citations inside a live agent task. Knowledge management, task retrieval, and answer citations are separate operations.
Authentication and scope¶
Use the product credential, workspace, and short-lived task authorization supplied by the current execution environment. Keep its Base URL; paths below are relative to the product prefix. Send JSON with these headers:
X-API-Key: <runtime-product-credential>
X-Workspace-ID: <runtime-workspace-id>
X-MOI-Runtime-Authorization: Bearer <runtime-task-grant>
Content-Type: application/json
Current task bindings, authorization, and lifecycle determine resource scope. Request bodies do not select another task or role identity. Use a unique request_id for each new operation; reuse the same identifier and input when replaying the exact request.
Search text evidence¶
POST /semantic-models/runtime/search:
{"request_id":"search-retention-1","keywords":["retention policy"],"max_hits":3,"before":2,"after":1}
Ordinary search can narrow sources using file_ids or volume_id, or select full-text retrieval with fulltext_only. No hits do not establish corpus-wide absence.
The common response contains call_id, output, artifacts, metadata, and failed. Check failed and the operation result after HTTP success. Text evidence normally appears in artifacts[].data.chunks, with artifact_id on the containing artifact. Preserve each passage’s chunk_id, file_id, and semantic_model_id; do not reconstruct identities from names.
Read selected evidence¶
POST /semantic-models/runtime/read-evidence; replace selectors with the exact values returned by the same retrieval:
{"request_id":"read-retention-1","artifact_id":"<retrieval-artifact-id>","chunk_id":"<chunk-id>","file_id":"<file-id>","semantic_model_id":7,"cursor":0,"limit_chars":4000}
Use the actual integer semantic_model_id. Reads return output.content, has_more, and next_cursor. Continue the same evidence with the returned cursor and a distinct request ID per page. Paged artifacts can instead use artifact_id and part_index; do not combine this with passage, file, model, or character-pagination selectors.
A consumer that has inspected a complete canonical passage locally can submit local_content_sha256; the server verifies it against evidence saved by the current task. Do not combine this mode with pagination. local_reads atomically registers multiple complete local reads and cannot be combined with single-passage selectors.
Select citations¶
POST /semantic-models/runtime/cite:
{"request_id":"cite-retention-1","sources":[{"type":"rag_chunk","artifact_id":"<retrieval-artifact-id>","chunk_id":"<chunk-id>","file_id":"<file-id>","semantic_model_id":7}],"complete_read_requirements":true}
Select only supporting sources you have read. Check output.accepted; satisfy returned read requirements before selecting again. A new selection should include all sources used in the answer. When evidence is insufficient, send an explicit sources: [] and state which facts cannot be confirmed.
Locate Markdown source¶
Use markdown_file_id from current evidence. It cannot be inferred from an original file ID.
Task |
POST path |
Request fields |
|---|---|---|
Find text in parsed Markdown |
|
|
Page through parsed Markdown |
|
|
Find source files |
|
|
Search images |
|
|
Inspect available tables |
|
|
Query structured knowledge |
|
|
To enumerate enabled text passages in source order, call search with source_page containing the model ID, file ID, cursor, and page size. Do not mix this mode with ordinary search fields. Use output.source_page.has_more to decide whether to continue; stop when it is false. This mode enumerates passages rather than ranking semantically.
For complete calls, see the SDK guide Retrieve Knowledge and Read Evidence and the CLI guide In-Task Knowledge Retrieval.
Reading modes and cursors¶
Single-passage evidence reading uses an integer Unicode character offset. Reading an evidence list without a chunk selector uses the returned {item_index, content_offset} cursor object. The list response uses complete=true to indicate completion. Do not interchange these cursor forms. For a single passage, an omitted or zero limit_chars uses 2000; the explicit maximum is 8000.
Markdown read-document returns next_cursor; zero means the end. It does not return an evidence window’s has_more field. Preserve returned cursors rather than calculating byte offsets. An omitted or nonpositive Markdown window uses 8000, with a maximum of 20000.
Parsed Markdown reads use the current task’s visible, enabled segments. Parsed Markdown is reconstructed from current segments and may differ from an older full Markdown file. Deleted or disabled segments are not current readable evidence.