<!-- skill-index: generated by scripts/skill-index.py; make check-skill-index -->

Find it fast

sed -n '<from>,<to>p' SKILL.md one section rather than reading the file; ./mxcli syntax <topic> answers how do I write this for a fraction of either.

lines	section
24-50	Overview
51-137	Syntax
138-164	Altering existing documents
165-193	Gotchas
194-215	Common Patterns
216-251	Calling Agents from Microflows
252-254	AI agent documents

<!-- /skill-index -->

Agents

Overview

Four AI agent document types stored as JSON inside Mendix MPR files:

Type	CREATE keyword	Notes
Model	create ai model	GenAI model configuration; required by Agent
Knowledge Base	create knowledge base	KB source; referenced by Agent body
Consumed MCP Service	create consumed mcp service	MCP tool server; referenced by Agent body
Agent	create agent	Orchestrates model + tools + prompts

Requires: Mendix 11.9+ and the full agent-editor marketplace stack (7 modules) — AgentEditorCommons depends transitively on the other six, so all must be installed:

Module	Role
GenAICommons	Core AI types (Request/Response, DeployedModel, Tool, KnowledgeBase)
MxGenAIConnector	Mendix Cloud AI backend, model config, embeddings
AgentCommons	Agent management (versioned agents, tools, KBs, MCP)
AgentEditorCommons	Bridge to the Studio Pro Agent Editor extension
MCPClient	MCP server connections, tool discovery/execution
ConversationalUI	Chat widgets, tool-approval UI, trace monitoring
Encryption	Provides the 32-char key models/KBs reference

Install them with mxcli marketplace install <id> -p app.mpr (or via Studio Pro). Also register ASU_AgentEditor as an after-startup microflow.

Syntax

Model

mdl 1;
create ai model Module.MyModel (
  Provider: MxCloudGenAI,   -- default, can omit
  key: @Module.ApiKeyConst   -- must be a String constant
);

Provider is free-form, and nothing validates it. MDL passes the value straight through; MxCloudGenAI is only the default applied when you omit the property, not the only accepted value. Provider: OpenAI parses, writes, and round-trips through describe ai model — as does Provider: TotallyMadeUp.

That means a typo is caught by nothing in the headless path. Agent Editor documents are stored as custom blobs, and mxbuild contains no agent-editor strings at all, so mx check and the build both stay green and the fault surfaces only when Studio Pro opens the document.

mxcli deliberately does not enforce an allowlist, because the authoritative set of provider values is not available to it: the agent editor is a Studio Pro extension, its enum is not in generated/metamodel and not in mxbuild. Guessing a list risks rejecting a value Mendix accepts. Take the value from a model document Studio Pro created, rather than from memory or from this file.

Knowledge Base

mdl 1;
create knowledge base Module.ProductDocs (
  Provider: MxCloudGenAI,
  key: @Module.KBKeyConst
);

Consumed MCP Service

mdl 1;
create consumed mcp service Module.WebSearch (
  ProtocolVersion: v2025_03_26,
  version: '1.0',
  ConnectionTimeoutSeconds: 30,
  documentation: 'Web search MCP server'
);

Agent (full syntax)

mdl 1;
create agent Module.MyAgent (
  UsageType: task,              -- Task | Conversational
  model: Module.MyModel,        -- must exist
  description: 'Agent description',
  MaxTokens: 4096,
  Temperature: 0.7,             -- float
  TopP: 0.9,                    -- float
  ToolChoice: Auto,
  variables: ("Language": EntityAttribute, "Name": string),
  SystemPrompt: $$multi-line
prompt here.$$,
  UserPrompt: 'Single line prompt.'
)
{
  mcp service Module.WebSearch (
    Enabled: true
  )

  knowledge base KBAlias (
    source: Module.ProductDocs,
    collection: 'product-docs',
    MaxResults: 5,
    description: 'Product docs',
    Enabled: true
  )

  tool MyMicroflowTool (
    description: 'Fetch customer data',
    Enabled: true
  )
};

Altering existing documents

All four agent-editor document types support ALTER for targeted partial updates (no need to re-specify the whole document):

mdl 1;
-- Model, Knowledge Base, Consumed MCP Service: SET-only (no collections)
alter ai model Module.MyModel set DisplayName = 'GPT-4 Turbo', KeyName = 'OPENAI_KEY';

alter knowledge base Module.MyKB set ModelDisplayName = 'text-embedding-3-small';

alter consumed mcp service Module.MyMCP
    set ConnectionTimeoutSeconds = 60, Version = '0.2.0';

-- Agent: SET for scalars, ADD/DROP for tools, MCP services, knowledge bases
alter agent Module.MyAgent
    set SystemPrompt = 'New prompt', Temperature = 0.7, MaxTokens = 4096
    add tool MyMicroflow ( Description: '...', Enabled: true )
    add mcp service Module.WeatherSvc ( Description: '...', Enabled: true )
    add knowledge base Docs ( Source: Module.MyKB, Collection: 'docs', MaxResults: 5 )
    drop tool OldTool
    drop mcp service Module.OldSvc
    drop knowledge base OldKB;

Property names match CREATE (SystemPrompt, UserPrompt, Temperature, MaxTokens, ToolChoice, Model, Entity, Description, UsageType, …). Unknown property names error out with unknown agent property: X. CREATE OR MODIFY remains available when you want a full replacement.

Gotchas

Dollar-quoting for multi-line prompts

Single-quoted strings cannot span lines. Use $$...$$ for any SystemPrompt or UserPrompt that contains newlines. DESCRIBE always emits $$...$$ when the value contains newlines, so DESCRIBE output re-parses cleanly.

Portal-populated metadata fields

DisplayName, KeyName, KeyID, Environment, ResourceName, DeepLinkURL are populated by the Mendix portal at sync time. Do not set them manually in CREATE statements — they will be overwritten.

documentId vs qualifiedName

Each document has both a qualifiedName (e.g. Module.MyModel) and an opaque documentId UUID. The UUID is assigned by ASU_AgentEditor at runtime. Only qualifiedName is set by CREATE; cross-reference lookups resolve by scanning all documents for a matching name.

Drop order

Agents reference Model, Knowledge Base, and MCP Service documents. Always drop Agents before dropping their dependencies:

mdl 1;
drop agent Module.MyAgent;
drop consumed mcp service Module.WebSearch;
drop knowledge base Module.ProductDocs;
drop ai model Module.MyModel;

Variables: syntax

• "key": EntityAttribute — binds an attribute from the entity in the agent's context
• "key": string — binds a plain string value
• Keys must be quoted (string literals or quoted identifiers)

Association between BSON and MDL names

The feature uses CustomBlobDocument BSON type with a Contents field holding the JSON payload. The $type field is always "AgentEditorCommons$CustomBlobDocument". The document type is identified by the readableTypeName inside Metadata.

Common Patterns

Minimal agent (no tools)

mdl 1;
create ai model Module.M (Provider: MxCloudGenAI, key: @Module.K);
create agent Module.A (
  UsageType: task,
  model: Module.M,
  SystemPrompt: 'You are a helpful assistant.',
  UserPrompt: 'Ask me anything.'
);

Check all agent documents in a module

list ai models in module;
list knowledge bases in module;
list consumed mcp services in module;
list agents in module;

Calling Agents from Microflows

Dedicated call agent MDL syntax is not yet implemented. Use call java action with the AgentCommons Java actions instead:

-- Single-call (Task) agent — no chat history
$response = call java action AgentCommons.Agent_Call_WithoutHistory(
  agent = $agent,
  UserMessage = $UserInput
);

-- Conversational agent — with chat history
$response = call java action AgentCommons.Agent_Call_WithHistory(
  agent = $agent,
  ChatContext = $ChatContext,
  UserMessage = $UserInput
);

-- Create a ChatContext wired to an agent (for ConversationalUI)
$ChatContext = call java action AgentCommons.ChatContext_Create_ForAgent(
  agent = $agent,
  ActionMicroflow = Module.HandleToolCall,
  context = $ContextObject
);

Retrieve the AgentCommons.Agent entity by qualified name before calling:

retrieve $agent from AgentCommons.Agent
  where [QualifiedName = 'Module.MyAgent']
  first;

The AgentCommons.Agent entity is populated at runtime by ASU_AgentEditor from the agent documents you create with create agent.

AI agent documents

Model, Knowledge Base, Consumed MCP Service, Agent (LIST/DESCRIBE/CREATE/DROP, with variables, tools, KB tools, dollar-quoted multi-line prompts; requires AgentEditorCommons module, Mendix 11.9+)