# 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](../guides/ai-studio/processing/workflow/templates/document-knowledge-base.md), [Configure RAG semantics](knowledge-base-rag-semantic-config.md) |
| 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](workflow-multimodal-rag.md) |
| 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](../guides/ai-studio/processing/workflow/templates/drawing-parsing.md), [Extract key information from S3 engineering documents](s3-engineering-document-extraction.md) |
| 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](../guides/ai-studio/knowledge-bases/files-and-tables.md) |

## 2. Structured querying and NL2SQL

1. **Prepare clean schemas and comments first**: Use descriptive column names and comments in [Manage Catalog base objects](../guides/ai-studio/resource-center/catalog-objects.md) 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](knowledge-base-semantic-config.md).
3. **Validate heavy SQL before exposing it to agents**: Test query plans and inspect the **Query Profile** in [SQL Editor](../guides/ai-studio/processing/sql-editor.md) or MatrixOne [Database and SQL workbench](../guides/matrixone/database-and-sql.md) 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](../guides/ai-studio/agents/manage-agents/agent-detail.md)).
   - Store repeatable multi-step checklists in [Skills](../guides/ai-studio/agents/skills/index.md) rather than bloating system prompts.
   - Bind only the minimum required connectors and messaging channels per agent; see [Edit bindings](../guides/ai-studio/agents/manage-agents/edit-bindings.md).
2. **Right-size compute and runtimes**:
   - Leave runtime environments unbound for read-only Q&A agents; enable [Runtime environments](../guides/ai-studio/agents/runtime-environments/index.md) only for code execution or local repository tasks.
   - Pin custom Python dependencies on task-type [Compute instances](../guides/ai-studio/resource-center/compute.md) 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](../guides/ai-studio/agents/manage-agents/web-app.md), 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](../guides/ai-studio/monitoring/jobs.md) and [Billing](../guides/billing/index.md).

## 5. Workspaces, roles, and credential hygiene

- **Isolate environments by workspace**: Keep sandbox experiments in separate [Workspaces](../guides/ai-studio/resource-center/workspace.md) from production knowledge bases and tables.
- **Apply least-privilege role and object grants**: Assign workspace roles and object permissions in [Member management](../guides/ai-studio/resource-center/members.md) and [Users and permissions](../guides/ai-studio/permissions/users.md).
- **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](../guides/billing/credentials.md).
