Agents

---
name: agents
description: "Author Mendix AI agent documents in MDL — Model, Knowledge Base, Consumed MCP Service and Agent, with variables, tools and multi-line prompts. Use when adding GenAI features to a Mendix app, wiring an LLM model or knowledge base, or listing/describing existing agent documents. Requires AgentEditorCommons and Mendix 11.9+."
---

# 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

```sql
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

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

### Consumed MCP Service

```sql
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)

```sql
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):

```sql
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:
```sql
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)
```sql
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
```sql
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:

```sql
-- 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:

```sql
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+)