Agents

Overview

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

Requires: AgentEditorCommons marketplace module, Mendix 11.9+.

Syntax

Model

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

Knowledge Base

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

Consumed MCP Service

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

Agent (full syntax)

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
  }
};

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:

drop agent Module.MyAgent;
drop consumed mcp service Module.WebSearch;
drop knowledge base Module.ProductDocs;
drop 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)

create 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 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 database AgentCommons.Agent
  where AgentCommons.Agent/QualifiedName = 'Module.MyAgent'
  limit 1;

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