agents

name	agents
description	MDL Agent Documents — CREATE MODEL, CREATE KNOWLEDGE BASE, CREATE CONSUMED MCP SERVICE, CREATE AGENT syntax and calling agents from microflows
compatibility	opencode

MDL agent document author — model, knowledge base, MCP service, and agent creation with full syntax reference.

> Full syntax reference for creating AI agent documents in MDL. Covers CREATE MODEL, CREATE KNOWLEDGE BASE, CREATE CONSUMED MCP SERVICE, CREATE AGENT, drop order, dollar-quoting, and calling agents from microflows via Java actions.

Load when: - Creating or modifying agent, model, knowledge base, or consumed MCP service documents in MDL - Debugging agent document syntax errors - Calling agents from microflows using AgentCommons Java actions - Understanding agent document structure, variables, prompts, or tool wiring

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

Type	CREATE keyword	Notes
Model	create 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: AgentEditorCommons marketplace module, Mendix 11.9+.

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

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;

</common_patterns>

<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.

</calling_agents_from_microflows>

<output_rules>Output MDL code only in code blocks. Keep explanations concise.</output_rules>