Fiche aide-mémoire ColdFusion AI

The main rule

The LLM is not your application. It is a reasoning engine your ColdFusion application supervises. ColdFusion still owns:

• authentication
• authorization
• validation
• business rules
• database access
• logging
• error handling
• output encoding
• security

The stack at a glance

ChatModel()

Use ChatModel() for simple, stateless AI calls. Good for:

• summarizing
• rewriting
• translating
• classifying
• drafting
• explaining
• extracting

Not good for:

• remembering conversations
• checking permissions
• querying live app data
• searching private documents
• performing actions
• enforcing business rules

Basic shape:

<cfscript>
	chatModel = ChatModel( {
		provider : "openAI",
		modelName : "gpt-5-nano",
		apiKey : application.aiApiKey,
		temperature : 0.3,
		maxTokens : 500,
		timeout : 30
	} );

	response = chatModel.chat(
		"Summarize this support request in one sentence."
	);

	writeOutput( encodeForHtml( response.message ) );
</cfscript>

ChatModel() reminders

Do:

• set a timeout
• set maxTokens
• use lower temperature for factual tasks
• encode output before display
• validate JSON or structured output
• keep API keys out of source control

Do not:

• trust model output as HTML
• assume valid JSON
• expect memory
• let it make permission decisions
• use it as your application logic

Agent()

Use Agent() when the AI interaction needs more structure. Good for:

• multi-turn conversations
• system instructions
• memory
• user-specific context
• tool requests
• assistant-style workflows

Mental model:

• ChatModel(): The model connection.
• Agent(): The assistant wrapper around the model.

Use Agent() when the interaction is more than, "Prompt in, response out."

Memory

Memory is for recent conversation context. It is not permanent storage. It is not authorization. It is not truth.

Message window memory

Keeps the last N messages.

CHATMEMORY : {
	TYPE : "messageWindowChatMemory",
	MAXMESSAGES : 20,
	PERUSER : true
}

Use when:

• messages are normal length
• you want a simple default
• predictable message count matters

Token window memory

Keeps as much history as fits within a token limit.

CHATMEMORY : {
	TYPE : "tokenWindowChatMemory",
	MAXTOKENS : 4000,
	PERUSER : true
}

Use when:

• users paste long content
• token budget matters
• message count is not enough

Memory key rule

Use a real per-user memory key.

memoryKey = "tenant-" & session.tenantId & ":user-" & session.userId;

For separate conversations:

memoryKey = "tenant-" & session.tenantId
	& ":user-" & session.userId
	& ":conversation-" & session.aiConversationId;

Preferences

Preferences are durable application data. Memory:

The user just asked about invoice INV-123.

Preference:

The user prefers concise CFScript examples.

Store preferences in your database. Inject them intentionally into prompts or system messages. Do not rely on memory windows to preserve preferences forever.

CFC tools

Use CFC tools when the assistant needs controlled access to your application. Good for:

• checking ticket status
• listing upcoming events
• calculating totals
• validating coupons
• creating drafts
• checking eligibility

Bad for:

• arbitrary SQL
• broad “do everything” methods
• permission decisions
• exposing raw service layers
• destructive actions without confirmation

Tool registration

Expose specific methods.

TOOLS : [
	{
		CFC : "tools.SupportTool",
		METHODS : [
			{
				METHOD : "getTicketStatus",
				DESCRIPTION : "Get the current status of a support ticket by ticket ID. Use this when the user asks about the progress, state, or status of an existing support ticket."
			}
		]
	}
]

Descriptions matter. The model uses them to decide when to request the tool.

Tool execution checklist

Before executing a tool request:

• confirm the tool is allowlisted
• validate all arguments
• inject user context from ColdFusion
• enforce authorization inside the tool/service
• return only required data
• log the action safely
• require confirmation for risky writes

Never let the model provide:

• userId
• tenantId
• accountId
• role
• permission level
• ownership status

Read tools versus write tools

Start with read tools. Read tools:

• get status
• list records
• calculate totals
• check availability

Write tools:

• create records
• send emails
• issue refunds
• cancel registrations
• update accounts
• delete data

Write tools need:

• authentication
• authorization
• validation
• confirmation
• audit logging
• safe error handling
• idempotency where appropriate

The model should not mutate production because it sounded confident.

MCP

Use MCP when tools, prompts, or resources need to cross system boundaries. Use CFC tools when the capability lives inside your app. Use MCP when:

• tools live outside your application
• multiple apps need shared tools
• resources need standardized access
• prompts need to be shared
• integrations need governance
• auditability matters

Mental model:

• CFC tools: The assistant uses your app.
• MCP: The assistant connects to an ecosystem.

MCP terms

ColdFusion can act as a client, server, or both.

MCP reminders

Do:

• connect only to trusted servers
• allowlist tools
• validate arguments
• authenticate callers
• authorize resources
• filter returned data
• log calls

Do not:

• expose every CFC
• expose arbitrary files
• trust remote tools blindly
• ignore tenant boundaries
• treat MCP as a security model

RAG

Use RAG when the answer lives in documents. Good for:

• FAQs
• policy docs
• manuals
• knowledge bases
• API docs
• onboarding guides
• support articles

Use tools when the answer lives in application state.

• "What does the refund policy say?" RAG.
• "Am I eligible for a refund?" Tools plus RAG.
• "What is my order status?" Tool.
• "What does the API guide say about rate limits?" RAG.

RAG flow

Ingestion:

Load documents.
Split into chunks.
Generate embeddings.
Store chunks and vectors.

Retrieval:

User asks a question.
Question is embedded.
Similar chunks are retrieved.
Model answers using retrieved context.

RAG does not train the model. It supplies context at runtime.

RAG knobs

Start with defaults. Ask real questions. Inspect retrieved chunks. Tune based on bad answers. RAG debugging is usually retrieval debugging.

RAG production reminders

Do:

• use persistent vector stores
• scope documents by tenant/user/role
• track ingestion status
• re-index changed documents
• remove stale chunks
• inspect retrieved chunks
• tell the model not to guess
• include source references where useful

Do not:

• index everything
• ignore permissions
• trust stale content
• use in-memory vector stores for production
• assume RAG eliminates hallucinations
• call a messy folder a knowledge base

Guardrails

Use guardrails to validate, redact, block, or safely fail AI input and output.

They answer two questions:

Before we send this to the model, should we?

Before we show this to the user, should we?

Guardrail result types

Use:

• successWith for redaction
• failure for normal validation problems
• fatal for secrets, bypass attempts, or unsafe requests

Guardrail examples

Input guardrails:

• reject empty prompts
• reject oversized prompts
• redact payment-card-like values
• block prompt injection patterns
• block secrets or private keys
• restrict topics
• enforce feature scope

Output guardrails:

• block system prompt leakage
• block internal implementation details
• validate JSON
• redact sensitive output
• require RAG source support
• prevent tool results from exposing internal IDs

Operational guardrails:

• log safe reason codes
• show user-safe messages
• test normal and malicious cases
• tune based on real usage

Temperature

Use lower temperature for:

• classification
• factual explanations
• structured output
• summarization
• support answers
• RAG responses

Use higher temperature for:

• brainstorming
• naming
• creative writing
• alternate phrasing
• marketing drafts

Prompt checklist

A good prompt usually includes:

• task
• audience
• format
• constraints
• source of truth
• examples, if useful
• what not to do

Weak:

Explain ColdFusion.

Better:

Explain ColdFusion session scope to an experienced web developer who is new to CFML. Keep it under 120 words and include one practical use case.

For RAG:

Answer only using the retrieved context. If the answer is not present in the retrieved context, say you could not find it in the knowledge base. Do not invent policies, dates, prices, or eligibility rules.

For tools:

Use tools when current application data is required. Do not guess ticket status, order status, registration state, permissions, or account details.

Output handling

Plain text:

writeOutput( encodeForHtml( response.message ) );

HTML:

Sanitize before display.

JSON:

Parse it.
Validate it.
Reject invalid structures.

Automation:

Validate it.
Log it.
Require confirmation when risky.

Tool results:

Filter internal fields before the model sees them.

RAG answers:

Prefer source references.
Do not allow unsupported claims.

Logging

Log enough to debug. Do not log enough to create a second data breach. Useful metadata:

• feature name
• provider
• model name
• request ID
• user ID
• tenant/account ID
• latency
• success/failure
• error code
• tool name
• guardrail result
• token usage, if available

Be careful with:

• full prompts
• full responses
• secrets
• personal data
• payment data
• private documents
• raw tool results

Security rules

Never let the model decide:

• user identity
• tenant
• role
• permissions
• ownership
• payment status
• account status
• authorization
• whether a destructive action is allowed

Always validate:

• user input
• model output
• tool arguments
• MCP responses
• RAG retrieval scope
• JSON structures
• write actions

Always encode or sanitize output before display. Always require confirmation before risky writes.

Good first AI features

Start with:

• summarize a support request
• rewrite an announcement
• suggest SEO metadata
• classify a message
• explain a validation error
• answer from a small FAQ
• check status through a read-only tool
• generate a draft for human review

Avoid starting with:

• refunds
• permission changes
• automatic emails
• record deletion
• billing updates
• internal logs
• all private documents
• arbitrary SQL
• legal, financial, or medical decisions

Decision guide

• Need one simple answer? Use ChatModel().
• Need conversation context? Use Agent() with memory.
• Need durable user preferences? Store preferences in your app.
• Need current application data? Use CFC tools.
• Need external/shared tools or resources? Use MCP.
• Need answers from documents? Use RAG.
• Need safety checks? Use guardrails.
• Changing data? Require authorization, validation, confirmation, and logging.

Final reminder

Use the simplest layer that solves the problem. Add memory when conversation matters. Add tools when application data matters. Add MCP when system boundaries matter. Add RAG when documents matter. Add guardrails because users exist.

The robot can help.

ColdFusion still runs the show.