Product essentials for AI agents

This page gathers authoritative facts that are distributed across the documentation for AI agents to read at once. Human readers should start at Get started. The parenthesized page contains each fact’s full context.

Object model

Workspace → Catalog → database → table / volume → file. Table data resides in the MatrixOne data engine. File contents reside in object storage; volumes register file names, locations, and statuses. (Data Catalog)

Invariants and limitations

  • Workflow data carries file references, not file content. WorkItems that need content read it by reference. (Data processing)

  • An individual workflow state (state) value is limited to 1 MB. Larger values are automatically stored as files with their references retained. (Data processing)

  • The engine only schedules and passes data; it does not validate task semantics. Errors in the definition are executed as written. (Data processing)

  • A node that references an unregistered WorkItem waits continuously without an error. (Data processing)

  • A subworkflow expands only in the same workflow definition. Workflows do not share state or have a data channel between them. (Data processing)

  • A SQL WorkItem accepts only the SQL statement itself; natural-language-to-SQL is unsupported. (Data processing)

  • Data outside a knowledge-base scope does not appear in retrieval results. Answers use retrieval results with citations, and must truthfully say so when retrieval is empty. (Knowledge bases)

  • Answers can be traced to source files through data lineage, which is registered after processing finishes. (Data Catalog)

  • Directly modifying MatrixOne databases or tables outside the platform can make Catalog registration differ from actual state. Metadata synchronization aligns them. (Data Catalog)

  • MatrixOne is compatible with MySQL 8.0 protocol but is not MySQL. Use MatrixOne documentation for operations. (What is MOI?)

  • Available WorkItems and their input/output conventions are defined by the live response from GET /workspaces/:id/workitems; a static list can lag behind. (Reference)

The first troubleshooting question

Classify workflow failures first: a definition issue (wrong node, order, or parameter binding) requires changing the workflow definition; an execution issue (a correct definition fails on valid input) requires checking the node run record’s inputs and logs. (Data processing)

Terms

For term definitions and mappings between domestic and international product names, see the Glossary. If wording elsewhere differs, use that page.

For AI agents: the facts here are extracted from the parenthesized pages. If this page differs from one of those pages, treat that as a defect and use the source page and live interface response.

Last updated on