DRAFT: fixes & comments on agent document proposal

[tinaengel-mx]

No description provided.

[github-actions]

AI Code Review

What Looks Good

The PR updates the agent document proposal with several valuable improvements:

• Fixes typos and formatting errors (missing commas, incorrect document IDs)
• Clarifies descriptions based on observed behavior (e.g., explaining how fields are decoded from key constants)
• Adds missing information discovered through observation (endpoint and authentication microflow in MCP service)
• Corrects inconsistencies in the original proposal (qualified names, document IDs)
• Improves technical accuracy (tool choice tool name requirement, variables[] handling)
• Maintains the proposal's structure while making it more precise

Recommendation

Approve - This PR improves the accuracy and clarity of a proposal document based on observed agent document behavior. Since it only updates documentation (no code or MDL syntax changes), most checklist items don't apply, and the documentation updates are appropriate and helpful for future implementation work. The "DRAFT" status is correctly maintained as this is still a proposal under discussion.

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

[tinaengel-mx]

I don't think entity & variables are super relevant for an overview

[tinaengel-mx]

afaik customblobdocuments only have these properties exposed
$ID: "",
name: "",
excluded: false,
documentType: agentDocumentTypeId, //i.e. agenteditor.agent
contents: createNewAgent(), //json

[tinaengel-mx]

I can only speak for the extensions-api, what's readable from a dump-mpr might be different

[github-actions]

AI Code Review

Critical Issues

• Missing version gating: The proposal introduces Agent documents (Mendix 11.9+) but lacks version compatibility checklist items:
  • No registry entry in sdk/versions/mendix-11.yaml
  • No executor checkFeature() pre-check with actionable error/hint
  • No test coverage using -- @version: directives
  • No update to .claude/skills/version-awareness.md
    This violates the version compatibility requirement for new MDL features.

Moderate Issues

• Incomplete test coverage plan: While the proposal mentions updating mxcli check for reference validation, it doesn't explicitly require adding working examples to mdl-examples/doctype-tests/ as mandated for MDL syntax changes. The proposal should include doctype tests for CREATE AGENT, CALL AGENT, etc.

What Looks Good

• MDL syntax design:
  • Uses standard CRUD-aligned verbs (CREATE, DROP, DESCRIBE, SHOW, CALL for invocation)
  • Proper qualified names (Agents.MyFirstModel)
  • Correct property format ( Key: value, ... ) with colon separators
  • Clear English readability ("business analyst can understand")
  • No keyword overloading observed in proposed syntax
  • Consistent with existing patterns (mirrors CREATE REST CLIENT)
• Full-stack consistency:
  • Explicitly plans grammar/AST/visitor/executor additions (Section 1.5)
  • Includes LSP and DESCRIBE roundtrip wiring (Section 2.0)
  • Addresses VS Code extension updates (Section 3.0)
  • Covers catalog integration and validator updates
• Documentation quality:
  • Well-structured with clear phases
  • Accurate BSON/JSON schema observations from real samples
  • Helpful implementation notes (e.g., tool choice validation requirements)

Recommendation

Request changes to add version gating plan per checklist. Once version compatibility items are addressed in the proposal, the PR can proceed. No code changes are needed in this documentation-only PR, but the proposal must include the missing version awareness elements before implementation begins.

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

[tinaengel-mx]

see my comment at the top. afaik not all of these properties are exposed for custom blob documents

[ako]

Correction to my earlier review

On re-reading, I was too quick to treat Tina's edits as corrections to the BSON. The original proposal was written by inspecting a real project's BSON; I should have verified before accepting changes that contradict it.

Checked the shipping parser:

• sdk/mpr/parser_customblob.go:26 — wrapper $Type is CustomBlobDocuments$CustomBlobDocument (matches original).
• Line 59 — parser reads raw["CustomDocumentType"], not DocumentType.

So the field name in the actual BSON is CustomDocumentType. The edit on line 19 to DocumentType is almost certainly a slip (and only one of four occurrences was changed). Revert that one.

Stepping back, the edits in this PR are three different kinds of change that need different handling:

1. BSON field-name edits (e.g. CustomDocumentType → DocumentType): reject unless a BSON snapshot or parser line proves otherwise. The shipping parser is the ground truth here.

2. New empirical claims about schema content — endpoint / authenticationMicroflow on ConsumedMCPService; UsageType: "Task" | "Chat" vs the original "Task" | "Conversational"; the explanation of empty type/name/... as decoded from the key constant. These could be correct in a newer Mendix version or a different sample project than the original author examined, but they contradict the original's "observed in test3 project" baseline. Need a real BSON snapshot from a current project before landing. If the BSON actually contains these, great. If not, they belong in a "spec/intent" section, not in the observed-schema section.

3. Design-intent additions — microflow tool return-type contract (String, primitive inputs + GenAICommons.Request/Tool), tool-name regex, ToolChoice: Tool requiring toolChoiceToolName, auth microflow returning List of System.HttpHeader, minSimilarity range 0–1. These are product knowledge the empirical-only original couldn't have. These should land — they're the highest-value contribution in the PR. Just mark them clearly as "design constraints" rather than "observed schema."

My original "what's valuable" list conflated (2) and (3). Only (3) is unambiguously valuable without more evidence.

Net recommendation: revert the DocumentType edit, get a fresh BSON snapshot to validate the category-2 claims, and keep the category-3 additions.

[tinaengel-mx]

AgentEditorCommons itself has many dependencies; see https://docs.mendix.com/appstore/modules/genai/genai-for-mx/agent-editor/#dependencies

[tinaengel-mx]

These are actions that require an agent object (not agent document) as input. In the toolbox in the agent editor section, there is now also a call agent acitvity, which is the preferred way when using the agent editor. It is called: AgentEditorCommons.Agent_CallDocument_WithoutHistory

A with history operation will be added soon as well.

[tinaengel-mx]

it's probably best to let the extension handle the variable calculation. We can trigger that on chnage and on opening of the agent tab

[tinaengel-mx]

of add to existing after startup logic

[tinaengel-mx]

of course this is still possible, because all objects (including agents) will be created in the ASU, but it will be easier to just use the native agent editor call agent activities that require and Agent docment as input. This will remove the need to do a database retrieve of the agent object before passing it to the agent commons call agent actions

[tinaengel-mx]

only valid values will we Task or Chat; Chat will likely be introduced in v1.1.0

[tinaengel-mx]

only available at runtime, will be added to extension later

[tinaengel-mx]

only available at runtime, will be added to extension later

[github-actions]

AI Code Review

We are reviewing a pull request that updates a proposal document for agent document support in MDL.
The PR only modifies a markdown file: docs/11-proposals/PROPOSAL_agent_document_support.md

We are to review against the checklist. However, note that the PR does not contain any code changes, only a proposal document.

Let's break down the checklist:

1. Overlap & duplication:

   • The PR updates a proposal document. We should check if there are existing proposals covering the same functionality.
   • The proposal is about agent document support, which is a new feature (as per the context, mxcli currently has no visibility into agent documents).
   • We note that the proposal document already exists (we are updating it). We should check if there are other proposals for the same feature?
     The repo does not have a docs/11-proposals/ directory with multiple proposals (from the context, we see only one proposal file in the diff).
     However, the context says: "Proposals in repo: No proposals directory." but then we see the file in the diff.
     Actually, the context says: "Proposals in repo: No proposals directory." meaning that in the initial state there was no proposals directory,
     but now we are adding one? Actually, the diff shows we are modifying an existing file in docs/11-proposals/.

   Since the PR only updates a proposal document, we don't have to worry about code duplication.

2. MDL syntax design:

   • The PR does not add or modify any MDL syntax (it's only a proposal document). So we skip this.

3. Full-stack consistency:

   • The PR does not add any MDL feature (it's a proposal). So we skip.

4. Test coverage:

   • Not applicable (no code).

5. Security & robustness:

   • Not applicable.

6. Scope & atomicity:

   • The PR is scoped to updating a proposal document. It's one thing.

7. Code quality:

   • Not applicable (no code).

8. Bugs & correctness:

   • We should check the proposal document for correctness and clarity.

However, note that the checklist also includes a section for "Documentation" in the PR/Commit Review Checklist:

- [ ] **Skills** — new features documented in `.claude/skills/` (syntax, examples, gotchas)
- [ ] **CLI help** — `mxcli` command help text updated (Cobra `Short`/`Long`/`Example` fields)
- [ ] **Syntax reference** — `docs/01-project/MDL_QUICK_REFERENCE.md` updated with new statement syntax
- [ ] **MDL examples** — working examples added to `mdl-examples/` for new commands
- [ ] **Site docs** — `docs-site/src/` pages added or updated for user-facing features

But note: this PR is updating a proposal document, not the actual documentation or skills.
The proposal document is in docs/11-proposals/ and is not part of the user-facing documentation (yet).
It is a design document.

Therefore, we should check if the proposal document is correct and complete, but note that the actual implementation
(if any) would be in a separate PR.

Since the PR is only updating a proposal, we focus on the content of the proposal.

Let's look at the changes in the proposal document:

We see several changes:

1. In the table of document types:

   • Changed "ConversationalUI" description to add "token & observability dashboards"

2. In the CustomBlobDocuments$CustomBlobDocument section:

   • Changed CustomDocumentType to DocumentType and added the possible values.

3. In the Key observations about the wrapper:

   • Changed the comment about Excluded to clarify it can be set to true by the user.

4. In the MODEL section (Contents JSON schema):

   • Changed the example type from empty string to "Text generation"
   • Changed the comment about type, name, etc. to explain they are decoded from the key and can be updated by the backend.

5. In the KNOWLEDGE BASE section:

   • Changed the example qualifiedName for the key constant from "Agents.LLMKey" to "Agents.KnowledbaseKey" (note: typo? "KnowledbaseKey" -> should be "KnowledgeBaseKey"?)
     But note: the original had "Agents.LLMKey" and now it's "Agents.KnowledbaseKey". However, in the example below, they use "Agents.KBKey".
     This seems inconsistent. We should check.

     Actually, in the example for CREATE KNOWLEDGE BASE, they use:
     Key: Agents.KBKey

     So the example in the JSON schema should probably be "Agents.KBKey" or "Agents.KnowledgeBaseKey"?
     But note: the proposal says the constant is a String constant. The name of the constant is arbitrary.

     However, the example in the JSON schema for Knowledge Base uses:
     "qualifiedName": "Agents.KnowledbaseKey"

     This has a typo: "KnowledbaseKey" (missing an 'o' and an 'e'?).

     But note: the example in the CREATE KNOWLEDGE BASE section uses:
     Key: Agents.KBKey

     So there's an inconsistency. We should flag this.

6. In the CONSUMED MCP SERVICE section:

   • Added endpoint and authenticationMicroflow fields to the JSON example and the CREATE statement.
   • Updated the description to explain the endpoint and authentication microflow.

7. In the AGENT section (Simple agent and Fully-populated agent):

   • Added a model reference in the simple agent example.
   • In the fully-populated agent, added a toolChoiceToolName field and changed the structure of the tools array to include a document field (which is a DocRef) for both MCP and Microflow tools.
   • Added usageType field and explained it.
   • Added minSimilarity to knowledgebaseTools.
   • Added temperature and topP to the agent.
   • Changed toolChoice to have a new property toolChoiceToolName when set to "Tool".

8. In the observations about the agent schema:

   • Added several new points about model, entity, usageType, tools[], knowledgebaseTools[], variables[].
   • Corrected the toolChoice enum values and added the requirement for toolChoiceToolName.

9. In the Block-level property reference table:

   • Changed "MCP SERVICE" to "CONSUMED MCP SERVICE" (to match the document type name).
   • Changed the description of the TOOL block to specify that the microflow must return a String and have limited input parameters.

10. In the example of CREATE AGENT:

    • Changed the comment on Variables to clarify that they are attributes to read from the context object.
    • Added a note about UsageType: Task determining if the user prompt is a template.

11. In the explanation of the CALL AGENT statement:

    • Added a row for UsageType: Task and changed the row for ToolChoice to explain the toolChoiceToolName.

12. In the Agent struct:

    • Added ToolChoiceToolName field.

13. In the Variable struct:

    • Added a comment to IsAttributeInEntity.

14. In the DocRef struct:

    • Changed the comment to say it can reference a CustomBlobDocument or a microflow.

15. In the ToolRef struct:

    • Made several changes:
      • The Name field is now only relevant for microflow tools and has constraints (must start with letter/underscore, etc.)
      • Added comments for Description, Enabled, ToolType.
      • Changed the Document field to reference either a ConsumedMCPService (for MCP) or a microflow (for Microflow).
      • Removed the separate Microflow field.

16. In the KBToolRef struct:

    • Added MinSimilarity field.

17. In the Model and ConsumedMCPService structs:

    • In Model: added a comment that KeyConstant points to a String constant.
    • In ConsumedMCPService: added Endpoint and AuthenticationMicroflow fields (as DocRef).

18. In the CATALOG table definitions:

    • Updated CATALOG.CONSUMED_MCP_SERVICES to include endpoint_constant and authentication_microflow.

19. In the writer_customblob.go instructions:

    • Changed the note for Model/KnowledgeBase/ConsumedMCPService to resolve the Key/Endpoint constant.

20. In the validation rules for CREATE/ALTER AGENT:

    • Changed UsageType must be Task or Chat (was Task or Conversational).

21. In the examples for CREATE MODEL, CREATE KNOWLEDGE BASE, CREATE CONSUMED MCP SERVICE:

    • Updated the examples to reflect the changes (e.g., in KNOWLEDGE BASE, changed the key constant to Agents.KBKey and added the Portal-populated fields).

22. In the example agent definition at the end:

    • Changed UsageType: Conversational to UsageType: Chat.

Given the above, we notice a few potential issues:

• In the KNOWLEDGE BASE JSON example, the qualifiedName for the key constant is written as "Agents.KnowledbaseKey" (which appears to be a typo).
  It should probably be "Agents.KnowledgeBaseKey" or, to match the example in the CREATE statement, "Agents.KBKey".
  However, note that the CREATE statement example uses "Agents.KBKey", so the JSON example should use that same constant.

  But wait: the JSON example is showing the contents of the Knowledge Base document, which includes a reference to the String constant (by its qualifiedName).
  The constant itself is named whatever the user chose. In the example, they are using a constant named "Agents.KBKey".
  So the JSON example should have:
  "qualifiedName": "Agents.KBKey"

  However, the example in the JSON schema for Knowledge Base currently says:
  "qualifiedName": "Agents.KnowledbaseKey"

  This is inconsistent and likely a typo.

• In the CONSUMED MCP SERVICE example, the JSON output shape now includes:
  "endpoint": {
  "documentId": "",
  "qualifiedName": "Agents.MCPEndpoint"
  },
  "authenticationMicroflow": {
  "documentId": "",
  "qualifiedName": "Agents.AuthenticationMicroflow"
  }

  This is consistent with the DocRef structure.

• In the ToolRef struct, we now have:
  Document *DocRef // references ConsumedMCPService for ToolType=="MCP", references a microflow for ToolType=="Microflow"

  This is correct.

However, note that the proposal document is just a proposal. The actual implementation may change.

Since the PR is only updating a proposal document, and we are not implementing the feature in this PR, we do not block on the proposal being perfect.

But we should note the typo in the Knowledge Base example and suggest a fix.

Also, note that the proposal document is very long and we have only checked the parts that changed.

Let's check for any other inconsistencies:

• In the AGENT section, the simple agent example now includes a model field. This is consistent with the updated Agent struct.

• The explanation of UsageType is added:
  UsageType: Task determines if user prompt is a template or not | Task agents have a fixed user prompt, potentially containing variables, while Chat agents do not have a predefined userprompt, because it is determined by the user at runtime.

  This is clear.

• The explanation of ToolChoice and toolChoiceToolName is added and seems correct.

• In the Block-level property reference table, the TOOL block now specifies:
  Microflow tools must be microflow references (qualified name) and the target microflow must return a String; input parameters are limited to primitives and GenAICommons.Request/GenAICommons.Tool types.

  This is a good addition.

Given the above, we have:

Moderate Issue:
In the KNOWLEDGE BASE JSON example, the qualifiedName for the key constant is written as "Agents.KnowledbaseKey", which is likely a typo and should be "Agents.KBKey" to match the CREATE example.

However, note that the CREATE example uses:
Key: Agents.KBKey

So the JSON example should use the same constant.

Alternatively, the constant could be named anything, but the example should be consistent.

We also note that in the Knowledge Base struct, the KeyConstant field is of type *ConstantRef, which points to a String constant.

Therefore, we recommend changing the example in the JSON schema for Knowledge Base to use "Agents.KBKey".

Additionally, we see that in the CREATE KNOWLEDGE BASE example, they use:
Key: Agents.KBKey

and then in the JSON output shape example for Knowledge Base, they have:
"key": {
"documentId": "51b85be5-f040-4562-bf4c-086347d38712",
"qualifiedName": "Agents.KnowledbaseKey"
}

This is inconsistent. The qualifiedName in the JSON should be "Agents.KBKey".

So we flag this as a moderate issue because it's a documentation error in the proposal.

We also note that the same issue might appear in the Model example? Let's check:

In the Model section, the JSON example for Model does not show the key constant. It only shows:
{
"type": "Text generation",
"name": "",
"displayName": "",
"provider": "MxCloudGenAI",
...
}

So no issue there.

In the ConsumedMCPService section, the JSON example now includes endpoint and authenticationMicroflow, and they use:
"endpoint": {
"documentId": "",
"qualifiedName": "Agents.MCPEndpoint"
},
"authenticationMicroflow": {
"documentId": "",
"qualifiedName": "Agents.AuthenticationMicroflow"
}

This is consistent with the CREATE example.

Therefore, only the Knowledge Base example has the typo.

We also note that in the Knowledge Base section, the text says:
Same shape as Model, but providerFields carries besides information about the knowledgebase also a refrence to an embedding-model.

There's a typo: "refrence" -> "reference".

We can fix that too.

However, note that the PR is already submitted. We are reviewing and can request changes.

Let's summarize:

Moderate Issues:
1. In the KNOWLEDGE BASE JSON example, the qualifiedName for the key constant is written as "Agents.KnowledbaseKey" (which has a typo) and should be "Agents.KBKey" to match the CREATE example.
2. In the same section, there's a typo: "refrence" -> "reference".

We also note that the proposal document is very long and we might have missed other typos, but we are only required to review the changed parts.

However, note that the PR only shows the changed lines. We see that the line with the typo in the KNOWLEDGE BASE JSON example was changed?
Actually, in the diff we see:

    -      "qualifiedName": "Agents.LLMKey"
    +      "qualifiedName": "Agents.KnowledbaseKey"

So the PR introduced the typo?

Originally, it was "Agents.LLMKey" (which was for the LLM key constant). Then they changed it to "Agents.KnowledbaseKey" (which is meant to be for the knowledge base key constant) but misspelled.

They should have used "Agents.KBKey" (as in the CREATE example) or "Agents.KnowledgeBaseKey".

Since the CREATE example uses "Agents.KBKey", we suggest using that.

Also, the text change:
- Same shape as Model, but providerFields includes embedding-model info (modelDisplayName, modelName) instead of resourceName. The key reference points to the same String constant.
+ Same shape as Model, but providerFields carries besides information about the knowledgebase also a refrence to an embedding-model. User-settable fields are just Provider and Key:

We see two issues in the added line:
- "carries besides information" -> awkward phrasing, but not critical.
- "refrence" -> should be "reference".

We can suggest:
Same shape as Model, but providerFields carries information about the knowledgebase and a reference to an embedding-model. User-settable fields are just Provider and Key:

However, note that the PR also changed the example below to use "Agents.KBKey".

So we have two issues in the same hunk.

We'll flag both.

Additionally, we note that in the CONSUMED MCP SERVICE section, the text says:
Same shape as Model, but providerFields includes embedding-model info (modelDisplayName, modelName) instead of resourceName. The key reference points to the same String constant.

was changed to:

    Same shape as Model, but `providerFields` carries besides information about the knowledgebase also a refrence to an embedding-model. User-settable fields are just `Provider` and `Key`:

and then the example was changed to use KBKey.

This section is actually for the KNOWLEDGE BASE, not CONSUMED MCP

---

Automated review via OpenRouter (Nemotron Super 120B) — workflow source

[tinaengel-mx]

let me know if there are still open questions regarding microflow tools. I added a lot of info above

[tinaengel-mx]

as decribed earlier, we have an will continue to introdcue decided toolbox actions in AgentEditorCommons module that accept an agent document as input param. This will simplify microflows containing call agent acitivites even though the "old" from AgentCommons actions will still work

[tinaengel-mx]

currently we require a restart of the app after every change to be able to use the testing playground and male sure that agent object in the database are in sync with agent documents

[tinaengel-mx]

correct we ship samples (template agents) but agents can be created in any module

[tinaengel-mx]

we can handle renames of referenced documents from the extension, however we are not yet able to recover references when a document is deleted and recreated with the same name. This will result in a consistency error and the user needs to reselect the referenced document (model, constant, microflow, KB, MCP)

[tinaengel-mx]

not correct. Keys are impoted right after selection of a constant. We also listen to changes to the constant values or the runtime configs. Additionally users can trigger a call to the resource by pressing the test key button, this might update the model name and ID if that was chnages in the portal in the meantime