Production best practices

Moving from initial experiments to reliable production usage in MOI depends on matching workflow templates, semantic rules, agent permission boundaries, compute sizing, and workspace isolation to each workload.

1. Unstructured documents and multimodal RAG

Workload

Recommended setup

Reference

Text-heavy policies, SOPs, and contracts

Start with Document Knowledge Base Preparation, keep standard chunking, and add RAG Standard Q&A pairs for high-frequency policy questions

Document Knowledge Base Preparation, Configure RAG semantics

Manuals with diagrams, screenshots, or figures

Use Document Knowledge Base Preparation (Image Index) and bind both text and vision/image embedding models

Prepare multimodal RAG data in batches

Engineering drawings and dense layout scans

Use Drawing Parsing or Multimodal Extraction to extract IDs and metrics into JSON or tables instead of relying solely on text chunks

Drawing Parsing, Extract key information from S3 engineering documents

Versioned or expiring handbooks

Update file revisions and set expiration timestamps in file details so superseded documents are excluded from retrieval

Files, chunks, and versions

2. Structured querying and NL2SQL

  1. Prepare clean schemas and comments first: Use descriptive column names and comments in Manage Catalog base objects or MatrixOne SQL so models do not have to guess column meanings.

  2. Capture business logic in semantic entries: Define aliases, derived metrics, business rules, and default filters in the knowledge base semantic layer instead of repeating metric formulas in every prompt. See Improve knowledge base query accuracy with semantic configuration.

  3. Validate heavy SQL before exposing it to agents: Test query plans and inspect the Query Profile in SQL Editor or MatrixOne Database and SQL workbench before publishing metrics to interactive users.

3. Agent boundaries, bindings, and runtime isolation

  1. Separate instructions, reusable skills, and external tools:

    • Keep system prompts focused on role boundaries, output structure, and explicit uncertainty rules (see Edit prompts and basic info).

    • Store repeatable multi-step checklists in Skills rather than bloating system prompts.

    • Bind only the minimum required connectors and messaging channels per agent; see Edit bindings.

  2. Right-size compute and runtimes:

    • Leave runtime environments unbound for read-only Q&A agents; enable Runtime environments only for code execution or local repository tasks.

    • Pin custom Python dependencies on task-type Compute instances and confirm the status shows Ready before launching dependent workflows.

  3. Review public web app exposure: Before enabling anonymous links in Publish as Web App, verify that bound knowledge bases and write-capable tools are safe for external visitors.

4. Workflow batch runs and cost control

  • Test with 2–5 representative files first: Always validate parser output, JSON schema extraction, and chunk quality on a small batch before running full folders, avoiding redundant Credit spend on OCR or LLM steps.

  • Separate query compute from task compute: Dedicate query compute to interactive SQL/knowledge chat and task compute to batch workflows and custom Python operators.

  • Tag and group production pipelines: Apply tags such as prod or rag-ingest in workflows and monitor runs in Jobs and Billing.

5. Workspaces, roles, and credential hygiene

  • Isolate environments by workspace: Keep sandbox experiments in separate Workspaces from production knowledge bases and tables.

  • Apply least-privilege role and object grants: Assign workspace roles and object permissions in Member management and Users and permissions.

  • Separate personal tokens from service credentials: Use personal access tokens for local CLI/SDK testing and dedicated service accounts or Genesis keys per application environment; see Manage credentials.

Last updated on