Retrieve Knowledge and Read Evidence

Search authorized knowledge inside a running agent task’s execution environment, page through retrieved passages, and submit citation selections after verifying that the evidence supports your answer.

Task flow

Task-injected endpoint, credential, workspace, and runtime grant
                              │
                              ▼
          Search bound knowledge sources by keywords
                              │
                              ▼
  Page through evidence with artifact_id / chunk_id / file_id
                              │
                              ▼
      Verify passage content and submit answer citations

Prerequisites

  1. Complete the endpoint, personal access token, and workspace setup in Use the SDK, and ensure a matching SDK package is installed in the task execution environment.

  2. Retain the endpoint (MOI_ENDPOINT), credential (MOI_API_KEY), workspace ID (MOI_WORKSPACE_ID), and short-lived runtime grant (MOI_RUNTIME_AUTHORIZATION) injected into the running agent task; in-task retrieval requires passing all four runtime connection values together.

  3. Ensure the current task has bound knowledge sources and permission to search, read evidence, and submit citations.

Search and read evidence pages

Set the retrieval keyword in the task environment and run the example below. It extracts the first text hit’s artifact ID, chunk ID, file ID, and semantic model ID, then pages through the passage using returned cursors (capped at 20 pages in this example so unread tails are never mistaken for complete material).

export KNOWLEDGE_QUERY="retention policy"
import os
import uuid

from google.protobuf.json_format import MessageToDict
from google.protobuf.struct_pb2 import Struct, Value
import moi_product_sdk as sdk

client = sdk.Client(
    os.environ["MOI_ENDPOINT"],
    sdk.with_api_key(os.environ["MOI_API_KEY"]),
    sdk.with_runtime_authorization(os.environ["MOI_RUNTIME_AUTHORIZATION"]),
)
knowledge = client.workspace(os.environ["MOI_WORKSPACE_ID"]).knowledge()


def checked(result):
    if result.failed:
        raise RuntimeError(MessageToDict(result.output))
    return MessageToDict(result.output)


search = knowledge.search(
    sdk.KnowledgeSearchRequest(
        request_id="search-" + uuid.uuid4().hex,
        keywords=[os.environ["KNOWLEDGE_QUERY"]],
        max_hits=3,
        before=2,
        after=1,
    )
)
checked(search)

choices = []
for artifact in search.artifacts:
    saved = MessageToDict(artifact)
    for chunk in saved.get("data", {}).get("chunks", []):
        if chunk.get("chunk_id") and saved.get("artifact_id"):
            choices.append((saved["artifact_id"], chunk))
if not choices:
    raise SystemExit("No text evidence returned; inspect the search result.")

artifact_id, chunk = choices[0]
selection = {"type": "rag_chunk", "artifact_id": artifact_id}
for key in ("chunk_id", "file_id", "semantic_model_id"):
    if key in chunk:
        selection[key] = chunk[key]
print("Selected evidence:", selection)

cursor = 0
for _ in range(20):
    request = sdk.KnowledgeReadEvidenceRequest(
        request_id="read-" + uuid.uuid4().hex,
        artifact_id=artifact_id,
        chunk_id=chunk["chunk_id"],
        file_id=chunk["file_id"],
        cursor=Value(number_value=cursor),
        limit_chars=4000,
    )
    if "semantic_model_id" in chunk:
        request.semantic_model_id = int(chunk["semantic_model_id"])
    page = checked(knowledge.read_evidence(request))
    print(page.get("content", ""))
    if not page.get("has_more", False):
        break
    next_cursor = page.get("next_cursor")
    if not isinstance(next_cursor, (int, float)) or next_cursor <= cursor:
        raise RuntimeError("Invalid evidence continuation cursor")
    cursor = next_cursor
else:
    raise RuntimeError("Read budget reached; finish reading before citing")
package main

import (
	"context"
	"fmt"
	"os"
	"time"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
	"google.golang.org/protobuf/types/known/structpb"
)

func checked(result *sdk.KnowledgeRuntimeResult, err error) map[string]any {
	if err != nil {
		panic(err)
	}
	if result.GetFailed() {
		panic(fmt.Sprint(result.GetOutput().AsMap()))
	}
	return result.GetOutput().AsMap()
}

func requestID(prefix string) string {
	return fmt.Sprintf("%s-%d", prefix, time.Now().UnixNano())
}

func main() {
	ctx := context.Background()
	client, err := sdk.New(
		os.Getenv("MOI_ENDPOINT"),
		sdk.WithAPIKey(os.Getenv("MOI_API_KEY")),
		sdk.WithRuntimeAuthorization(os.Getenv("MOI_RUNTIME_AUTHORIZATION")),
	)
	if err != nil {
		panic(err)
	}
	defer client.Close()

	workspace, err := client.Workspace(os.Getenv("MOI_WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	knowledge := workspace.Knowledge()

	search, err := knowledge.Search(ctx, &sdk.KnowledgeSearchRequest{
		RequestId: requestID("search"),
		Keywords:  []string{os.Getenv("KNOWLEDGE_QUERY")},
		MaxHits:   3,
		Before:    2,
		After:     1,
	})
	checked(search, err)

	var artifactID string
	var chunk map[string]any
	for _, artifact := range search.GetArtifacts() {
		saved := artifact.AsMap()
		data, _ := saved["data"].(map[string]any)
		chunks, _ := data["chunks"].([]any)
		for _, value := range chunks {
			candidate, ok := value.(map[string]any)
			id, _ := saved["artifact_id"].(string)
			if ok && candidate["chunk_id"] != nil && id != "" {
				artifactID, chunk = id, candidate
				break
			}
		}
		if chunk != nil {
			break
		}
	}
	if chunk == nil {
		fmt.Println("No text evidence returned; inspect the search result.")
		return
	}

	selection := map[string]any{"type": "rag_chunk", "artifact_id": artifactID}
	for _, key := range []string{"chunk_id", "file_id", "semantic_model_id"} {
		if value, ok := chunk[key]; ok {
			selection[key] = value
		}
	}
	fmt.Println("Selected evidence:", selection)

	cursor := float64(0)
	complete := false
	for pageIndex := 0; pageIndex < 20; pageIndex++ {
		request := &sdk.KnowledgeReadEvidenceRequest{
			RequestId:  requestID("read"),
			ArtifactId: artifactID,
			ChunkId:    chunk["chunk_id"].(string),
			FileId:     chunk["file_id"].(string),
			Cursor:     structpb.NewNumberValue(cursor),
			LimitChars: 4000,
		}
		if value, ok := chunk["semantic_model_id"].(float64); ok {
			modelID := int64(value)
			request.SemanticModelId = &modelID
		}
		page := checked(knowledge.ReadEvidence(ctx, request))
		fmt.Println(page["content"])
		if page["has_more"] != true {
			complete = true
			break
		}
		next, ok := page["next_cursor"].(float64)
		if !ok || next <= cursor {
			panic("Invalid evidence continuation cursor")
		}
		cursor = next
	}
	if !complete {
		panic("Read budget reached; finish reading before citing")
	}
}

Submit answer citations

After confirming that the retrieved passage supports your answer, continue from the example above to submit the citation selection. When an answer relies on multiple passages, include every adopted source in sources.

source = Struct()
source.update(selection)
citation = knowledge.cite(
    sdk.KnowledgeCiteRequest(
        request_id="cite-" + uuid.uuid4().hex,
        sources=[source],
        complete_read_requirements=True,
    )
)
confirmation = checked(citation)
if confirmation.get("accepted") is not True:
    raise RuntimeError(confirmation)
print("Citation accepted:", confirmation)
source, err := structpb.NewStruct(selection)
if err != nil {
	panic(err)
}
confirmation := checked(knowledge.Cite(ctx, &sdk.KnowledgeCiteRequest{
	RequestId:                requestID("cite"),
	Sources:                  []*structpb.Struct{source},
	CompleteReadRequirements: true,
}))
if confirmation["accepted"] != true {
	panic(fmt.Sprint(confirmation))
}
fmt.Println("Citation accepted:", confirmation)

Limitations and notes

  • If citation submission indicates unread evidence requirements, complete the requested reads before resubmitting; when retrieved passages do not substantiate the claim, submit an empty sources list and state what could not be verified.

  • To search or page through parsed Markdown source text, obtain markdown_file_id from the retrieved evidence and call knowledge.search_document and knowledge.read_document in Python (or knowledge.SearchDocument and knowledge.ReadDocument in Go) using the returned cursor.

Next steps

Last updated on