Skip to content

Commit 50adde5

Browse files
akoako
committed
Merge branch 'agentic'
2 parents 7a80230 + 06f6f34 commit 50adde5

File tree

6 files changed

+358
-0
lines changed

6 files changed

+358
-0
lines changed

‎.claude/skills/agents.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Agents
2+
3+
## Overview
4+
5+
Four AI agent document types stored as JSON inside Mendix MPR files:
6+
7+
| Type | CREATE keyword | Notes |
8+
|------|---------------|-------|
9+
| Model | `CREATE MODEL` | GenAI model configuration; required by Agent |
10+
| Knowledge Base | `CREATE KNOWLEDGE BASE` | KB source; referenced by Agent body |
11+
| Consumed MCP Service | `CREATE CONSUMED MCP SERVICE` | MCP tool server; referenced by Agent body |
12+
| Agent | `CREATE AGENT` | Orchestrates model + tools + prompts |
13+
14+
**Requires:** `AgentEditorCommons` marketplace module, Mendix 11.9+.
15+
16+
## Syntax
17+
18+
### Model
19+
20+
```sql
21+
CREATE MODEL Module.MyModel (
22+
Provider: MxCloudGenAI, -- default, can omit
23+
Key: Module.ApiKeyConst -- must be a String constant
24+
);
25+
```
26+
27+
### Knowledge Base
28+
29+
```sql
30+
CREATE KNOWLEDGE BASE Module.ProductDocs (
31+
Provider: MxCloudGenAI,
32+
Key: Module.KBKeyConst
33+
);
34+
```
35+
36+
### Consumed MCP Service
37+
38+
```sql
39+
CREATE CONSUMED MCP SERVICE Module.WebSearch (
40+
ProtocolVersion: v2025_03_26,
41+
Version: '1.0',
42+
ConnectionTimeoutSeconds: 30,
43+
Documentation: 'Web search MCP server'
44+
);
45+
```
46+
47+
### Agent (full syntax)
48+
49+
```sql
50+
CREATE AGENT Module.MyAgent (
51+
UsageType: Task, -- Task | Conversational
52+
Model: Module.MyModel, -- must exist
53+
Description: 'Agent description',
54+
MaxTokens: 4096,
55+
Temperature: 0.7, -- float
56+
TopP: 0.9, -- float
57+
ToolChoice: Auto,
58+
Variables: ("Language": EntityAttribute, "Name": String),
59+
SystemPrompt: $$Multi-line
60+
prompt here.$$,
61+
UserPrompt: 'Single line prompt.'
62+
)
63+
{
64+
MCP SERVICE Module.WebSearch {
65+
Enabled: true
66+
}
67+
68+
KNOWLEDGE BASE KBAlias {
69+
Source: Module.ProductDocs,
70+
Collection: 'product-docs',
71+
MaxResults: 5,
72+
Description: 'Product docs',
73+
Enabled: true
74+
}
75+
76+
TOOL MyMicroflowTool {
77+
Description: 'Fetch customer data',
78+
Enabled: true
79+
}
80+
};
81+
```
82+
83+
## Gotchas
84+
85+
### Dollar-quoting for multi-line prompts
86+
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.
87+
88+
### Portal-populated metadata fields
89+
`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.
90+
91+
### documentId vs qualifiedName
92+
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.
93+
94+
### Drop order
95+
Agents reference Model, Knowledge Base, and MCP Service documents. Always drop Agents before dropping their dependencies:
96+
```sql
97+
DROP AGENT Module.MyAgent;
98+
DROP CONSUMED MCP SERVICE Module.WebSearch;
99+
DROP KNOWLEDGE BASE Module.ProductDocs;
100+
DROP MODEL Module.MyModel;
101+
```
102+
103+
### Variables: syntax
104+
- `"Key": EntityAttribute` — binds an attribute from the entity in the agent's context
105+
- `"Key": String` — binds a plain string value
106+
- Keys must be quoted (string literals or quoted identifiers)
107+
108+
### Association between BSON and MDL names
109+
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`.
110+
111+
## Common Patterns
112+
113+
### Minimal agent (no tools)
114+
```sql
115+
CREATE MODEL Module.M (Provider: MxCloudGenAI, Key: Module.K);
116+
CREATE AGENT Module.A (
117+
UsageType: Task,
118+
Model: Module.M,
119+
SystemPrompt: 'You are a helpful assistant.',
120+
UserPrompt: 'Ask me anything.'
121+
);
122+
```
123+
124+
### Check all agent documents in a module
125+
```sql
126+
LIST MODELS IN Module;
127+
LIST KNOWLEDGE BASES IN Module;
128+
LIST CONSUMED MCP SERVICES IN Module;
129+
LIST AGENTS IN Module;
130+
```

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -472,6 +472,7 @@ Full syntax tables for all MDL statements (microflows, pages, security, navigati
472472
- ALTER WORKFLOW (SET properties, INSERT/DROP/REPLACE activities, outcomes, paths, conditions, boundary events)
473473
- CALCULATED BY microflow syntax for calculated attributes
474474
- Image collections (SHOW/DESCRIBE/CREATE/DROP)
475+
- 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+)
475476
- OData contract browsing (SHOW/DESCRIBE CONTRACT ENTITIES/ACTIONS FROM cached $metadata)
476477
- AsyncAPI contract browsing (SHOW/DESCRIBE CONTRACT CHANNELS/MESSAGES FROM cached AsyncAPI)
477478
- SHOW EXTERNAL ACTIONS, SHOW PUBLISHED REST SERVICES

‎cmd/mxcli/help.go‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,7 @@ Available topics:
180180
fragment - Show fragment (reusable widget group) syntax
181181
java-action - Show Java action syntax (CREATE/DESCRIBE/CALL, type params, EXPOSED AS)
182182
business-events - Show business event service syntax
183+
agents - Show AI agent document syntax (Model, KB, MCP Service, Agent)
183184
xpath - Show XPath constraint syntax for WHERE clauses
184185
oql - Show OQL query execution syntax (mxcli oql)
185186
sql - Show external SQL query execution syntax (mxcli sql)
@@ -245,6 +246,8 @@ Example:
245246
showTopicHelp("java-action")
246247
case "business-events", "businessevents", "business_events", "be":
247248
showTopicHelp("business-events")
249+
case "agents", "agent", "agent-editor", "agenteditor", "model", "models", "knowledge-base", "knowledgebase", "mcp", "mcp-service":
250+
showTopicHelp("agents")
248251
case "xpath", "xpath-constraints":
249252
showTopicHelp("xpath")
250253
case "oql":

‎cmd/mxcli/help_topics/agents.txt‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
Agents
2+
======
3+
4+
AI agent documents (Model, Knowledge Base, Consumed MCP Service, Agent)
5+
require the AgentEditorCommons marketplace module and Mendix 11.9+.
6+
7+
PREREQUISITES
8+
-------------
9+
10+
1. AgentEditorCommons module installed from the marketplace
11+
2. Encryption module configured with a 32-character key
12+
3. ASU_AgentEditor registered as the after-startup microflow
13+
14+
Create constants to hold the API keys first:
15+
16+
CREATE CONSTANT Module.ModelApiKey TYPE String DEFAULT '';
17+
18+
SHOW / LIST
19+
-----------
20+
21+
LIST MODELS [IN Module];
22+
LIST KNOWLEDGE BASES [IN Module];
23+
LIST CONSUMED MCP SERVICES [IN Module];
24+
LIST AGENTS [IN Module];
25+
26+
DESCRIBE MODEL Module.Name;
27+
DESCRIBE KNOWLEDGE BASE Module.Name;
28+
DESCRIBE CONSUMED MCP SERVICE Module.Name;
29+
DESCRIBE AGENT Module.Name;
30+
31+
CREATE MODEL
32+
------------
33+
34+
CREATE MODEL Module.MyModel (
35+
Provider: MxCloudGenAI,
36+
Key: Module.ModelApiKey
37+
);
38+
39+
Provider defaults to MxCloudGenAI when omitted.
40+
Key must refer to a String constant in the project.
41+
42+
CREATE KNOWLEDGE BASE
43+
---------------------
44+
45+
CREATE KNOWLEDGE BASE Module.ProductDocs (
46+
Provider: MxCloudGenAI,
47+
Key: Module.KBApiKey
48+
);
49+
50+
CREATE CONSUMED MCP SERVICE
51+
----------------------------
52+
53+
CREATE CONSUMED MCP SERVICE Module.WebSearch (
54+
ProtocolVersion: v2025_03_26,
55+
Version: '1.0',
56+
ConnectionTimeoutSeconds: 30,
57+
Documentation: 'Web search MCP server'
58+
);
59+
60+
CREATE AGENT (simple)
61+
---------------------
62+
63+
CREATE AGENT Module.Summarizer (
64+
UsageType: Task,
65+
Model: Module.MyModel,
66+
SystemPrompt: 'Summarize in 3 sentences.',
67+
UserPrompt: 'Enter text.'
68+
);
69+
70+
UsageType values: Task, Conversational
71+
72+
CREATE AGENT (with variables and tools)
73+
----------------------------------------
74+
75+
CREATE AGENT Module.ResearchAssistant (
76+
UsageType: Conversational,
77+
Description: 'Research assistant',
78+
Model: Module.MyModel,
79+
MaxTokens: 16384,
80+
Temperature: 0.7,
81+
TopP: 0.9,
82+
ToolChoice: Auto,
83+
Variables: ("Language": EntityAttribute),
84+
SystemPrompt: $$You are a research assistant.
85+
Respond in {{Language}}.$$,
86+
UserPrompt: 'Ask me anything.'
87+
)
88+
{
89+
MCP SERVICE Module.WebSearch {
90+
Enabled: true
91+
}
92+
93+
KNOWLEDGE BASE ProductKB {
94+
Source: Module.ProductDocs,
95+
Collection: 'product-docs',
96+
MaxResults: 5,
97+
Description: 'Product documentation',
98+
Enabled: true
99+
}
100+
101+
TOOL MyMicroflowTool {
102+
Description: 'Fetch customer data',
103+
Enabled: true
104+
}
105+
};
106+
107+
Use $$...$$ for multi-line prompts. Single-quoted strings cannot span lines.
108+
Variables: ("Key": EntityAttribute) binds entity attributes.
109+
Variables: ("Key": String) binds plain string values.
110+
111+
DROP
112+
----
113+
114+
DROP AGENT Module.Name;
115+
DROP CONSUMED MCP SERVICE Module.Name;
116+
DROP KNOWLEDGE BASE Module.Name;
117+
DROP MODEL Module.Name;
118+
119+
Always drop Agents before the Model, Knowledge Base, or MCP Service they reference.
120+
121+
NOTES
122+
-----
123+
124+
Portal-populated metadata fields (DisplayName, KeyName, KeyID, Environment,
125+
ResourceName, DeepLinkURL) are managed by the Mendix portal and should not
126+
be set manually in CREATE statements.
127+
128+
The documentId field is an opaque agent-internal ID populated at
129+
runtime by ASU_AgentEditor. You do not need to set it.
130+
131+
Cross-document references are validated at execute time: the Model, Knowledge
132+
Base, and MCP Service documents must exist before creating an Agent that
133+
references them.

‎docs/01-project/MDL_QUICK_REFERENCE.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -428,6 +428,87 @@ CREATE OR REPLACE NAVIGATION Responsive
428428
| Create service | `CREATE BUSINESS EVENT SERVICE Module.Name (...) { MESSAGE ... };` | See help topic for full syntax |
429429
| Drop service | `DROP BUSINESS EVENT SERVICE Module.Name;` | Delete a service |
430430

431+
## Agents
432+
433+
AI agent document types (Model, Knowledge Base, Consumed MCP Service, Agent) require
434+
the `AgentEditorCommons` marketplace module and Mendix 11.9+.
435+
436+
**Model**
437+
438+
| Statement | Syntax | Notes |
439+
|-----------|--------|-------|
440+
| List models | `LIST MODELS [IN Module];` | Also `SHOW MODELS` |
441+
| Describe model | `DESCRIBE MODEL Module.Name;` | Full MDL output |
442+
| Create model | `CREATE MODEL Module.Name (Provider: MxCloudGenAI, Key: Module.Const);` | Key must be a String constant |
443+
| Drop model | `DROP MODEL Module.Name;` | |
444+
445+
**Knowledge Base**
446+
447+
| Statement | Syntax | Notes |
448+
|-----------|--------|-------|
449+
| List knowledge bases | `LIST KNOWLEDGE BASES [IN Module];` | Also `SHOW KNOWLEDGE BASES` |
450+
| Describe knowledge base | `DESCRIBE KNOWLEDGE BASE Module.Name;` | Full MDL output |
451+
| Create knowledge base | `CREATE KNOWLEDGE BASE Module.Name (Provider: MxCloudGenAI, Key: Module.Const);` | Key must be a String constant |
452+
| Drop knowledge base | `DROP KNOWLEDGE BASE Module.Name;` | |
453+
454+
**Consumed MCP Service**
455+
456+
| Statement | Syntax | Notes |
457+
|-----------|--------|-------|
458+
| List MCP services | `LIST CONSUMED MCP SERVICES [IN Module];` | Also `SHOW CONSUMED MCP SERVICES` |
459+
| Describe MCP service | `DESCRIBE CONSUMED MCP SERVICE Module.Name;` | Full MDL output |
460+
| Create MCP service | `CREATE CONSUMED MCP SERVICE Module.Name (ProtocolVersion: v2025_03_26, Version: '1.0', ConnectionTimeoutSeconds: 30, Documentation: 'text');` | |
461+
| Drop MCP service | `DROP CONSUMED MCP SERVICE Module.Name;` | |
462+
463+
**Agent**
464+
465+
| Statement | Syntax | Notes |
466+
|-----------|--------|-------|
467+
| List agents | `LIST AGENTS [IN Module];` | Also `SHOW AGENTS` |
468+
| Describe agent | `DESCRIBE AGENT Module.Name;` | Full MDL output, re-executable |
469+
| Create agent | See example below | Requires a Model document |
470+
| Drop agent | `DROP AGENT Module.Name;` | Drop agents before their Model/KB/MCP dependencies |
471+
472+
```sql
473+
CREATE AGENT Module.MyAgent (
474+
UsageType: Task,
475+
Model: Module.MyModel,
476+
MaxTokens: 4096,
477+
Temperature: 0.7,
478+
TopP: 0.9,
479+
ToolChoice: Auto,
480+
Description: 'Agent description',
481+
Variables: ("Language": EntityAttribute),
482+
SystemPrompt: $$You are a helpful assistant.
483+
Respond in {{Language}}.$$,
484+
UserPrompt: 'Ask me anything.'
485+
)
486+
{
487+
MCP SERVICE Module.WebSearch {
488+
Enabled: true
489+
}
490+
491+
KNOWLEDGE BASE KBAlias {
492+
Source: Module.ProductDocs,
493+
Collection: 'product-docs',
494+
MaxResults: 5,
495+
Description: 'Product documentation',
496+
Enabled: true
497+
}
498+
499+
TOOL MyMicroflowTool {
500+
Description: 'Fetch customer data',
501+
Enabled: true
502+
}
503+
};
504+
```
505+
506+
**Notes:**
507+
- `Variables: ("Key": EntityAttribute)` binds entity attributes; `("Key": String)` binds a plain string.
508+
- Use `$$...$$` dollar-quoting for multi-line SystemPrompt/UserPrompt values.
509+
- Drop agents before dropping their referenced Model, Knowledge Base, or MCP Service.
510+
- Portal-populated metadata fields (`DisplayName`, `KeyName`, `KeyID`, `Environment`, `ResourceName`, `DeepLinkURL`) are managed by the portal and should not be set manually.
511+
431512
## Image Collections
432513

433514
| Statement | Syntax | Notes |

‎mdl/visitor/visitor_agenteditor.go‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,16 @@ func (b *Builder) ExitCreateAgentStatement(ctx *parser.CreateAgentStatementConte
213213
fmt.Sscanf(v, "%d", &n)
214214
stmt.MaxTokens = &n
215215
}
216+
if v, ok := props["temperature"]; ok {
217+
var f float64
218+
fmt.Sscanf(v, "%g", &f)
219+
stmt.Temperature = &f
220+
}
221+
if v, ok := props["topp"]; ok {
222+
var f float64
223+
fmt.Sscanf(v, "%g", &f)
224+
stmt.TopP = &f
225+
}
216226

217227
// Parse Variables: ("Key": EntityAttribute, "Key2": String)
218228
stmt.Variables = parseVariableDefsFromProps(ctx.AllModelProperty())

0 commit comments

Comments
 (0)