# Agents

## Overview

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

## Syntax

### Model

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

### Knowledge Base

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

### Consumed MCP Service

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

### Agent (full syntax)

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

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