<span id="任务内知识检索与引用"></span>

# 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.

<span id="认证与请求范围"></span>

## 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:

```http
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.

<span id="检索文本证据"></span>

## Search text evidence

`POST /semantic-models/runtime/search`：

```json
{"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.

<span id="读取所选证据"></span>

## Read selected evidence

`POST /semantic-models/runtime/read-evidence`; replace selectors with the exact values returned by the same retrieval:

```json
{"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.

<span id="确认引用选择"></span>

## Select citations

`POST /semantic-models/runtime/cite`：

```json
{"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.

(runtime-knowledge-markdown)=
<span id="定位-markdown-原文"></span>

## 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 | `/semantic-models/runtime/search-document` | `request_id`, `markdown_file_id`, `query`; optional `max_matches`, `context_chars`. |
| Page through parsed Markdown | `/semantic-models/runtime/read-document` | `request_id`, `markdown_file_id`, `cursor`, `limit_chars`; continue with the returned cursor. |
| Find source files | `/semantic-models/runtime/find-files` | `request_id`, `query`, `top_k`; inventory locates sources but is not retrieval evidence. |
| Search images | `/semantic-models/runtime/search-images` | `request_id`; use task-appropriate `query_text` or `query_visual_file_id` with a matching ranking configuration. |
| Inspect available tables | `/semantic-models/runtime/describe-tables` | `request_id`, `table_names` or `keywords`; optional samples and DDL length. |
| Query structured knowledge | `/semantic-models/runtime/query` | `request_id`, `sql`, `max_rows`; optional `semantic_claims`; inspect truncation and provenance. |

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](../../../sdk/ai-studio/智能体/检索知识并读取引用证据.md#sdk-ai-studio-runtime-knowledge-read) and the CLI guide [In-Task Knowledge Retrieval](../../../cli/tasks/runtime-knowledge.md).

<span id="区分读取模式和游标"></span>

## 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.
