Whatever message this page gives is out now! Go check it out!
agent
Last update:
May 18, 2026
Creates an Advanced RAG service with full pipeline control: custom document loaders, splitters, query transformers, multi-source routing, content aggregation, content injection, and guardrails — all configurable via ColdFusion structs and UDFs. The
retrievalAugmentor key is mutually exclusive with the legacy contentRetriever key.Syntax
Agent(
chatLanguageModel: <CFChatModel>, // Required
// Optional: document ingestion pipeline
ingestion: {
documentLoader: { type, params?, implementation? },
documentSplitter: { type, params?, implementation? },
embeddingStoreIngestor: { embeddingModel, embeddingStore, ... }
},
// Optional: retrieval pipeline
retrievalAugmentor: {
queryTransformer: { type, params?, implementation? },
queryRouter: { contentRetrievers: [ ... ] },
contentAggregator: { type, params?, implementation? },
contentInjector: { promptTemplate?, metadataKeys? }
},
inputGuardrails: [ udf1, udf2, ... ], // Optional
outputGuardrails: [ udf3, udf4, ... ] // Optional
)Parameters
Key | Type | Required | Description |
|---|---|---|---|
chatLanguageModel | CFChatModel | Required | The chat model used to generate final answers from retrieved context. |
ingestion | Struct | Optional | Configures document loading, splitting, and embedding pipeline. Each sub-key accepts a Struct with a type field ("filesystem", "url", "recursive", "custom") and either params for built-in types or implementation (UDF) for custom types. |
retrievalAugmentor | Struct | Optional | Configures the retrieval pipeline. Contains queryTransformer, queryRouter (with contentRetrievers Array), contentAggregator, and contentInjector. Mutually exclusive with the top-level contentRetriever key. |
inputGuardrails | Array of UDF | Optional | Ordered UDFs executed against the user message before the LLM call. Each must return { action, reason [, newPrompt] }. Valid actions: "success", "failure", "fatal", "reprompt". May also accept CFC file paths implementing a validate() function. |
outputGuardrails | Array of UDF | Optional | Ordered UDFs executed against the AI response before it is returned. Each must return { action, reason [, instruction] }. Valid actions: "success", "failure", "reprompt". May also accept CFC file paths. |
contentInjector Keys
The optional
contentInjector sub-key of retrievalAugmentor controls how retrieved content is merged with the user question before the LLM sees it.Property | Type | Default | Description |
|---|---|---|---|
promptTemplate | String | Built-in default | Mustache-style template controlling how retrieved content and the user question are assembled. Supports two placeholders: {{contents}} (replaced with retrieved chunks) and {{userMessage}} (replaced with the user question). If neither placeholder is present, ColdFusion logs a warning and falls back to default injection. |
metadataKeys | Array of String | [] (none) | Document metadata fields to append to each retrieved chunk. For example, ["file_name"] appends the source filename next to each chunk, enabling the LLM to cite sources. |
Returns
Returns an AIService object with a
chat(message) method that returns the AI-generated response String.Examples
Example 1: Multiple vector stores with LLM-based routing
technicalStore = VectorStore({ provider: "chroma", collection: "technical-docs",
host: "localhost", port: 8000 });
businessStore = VectorStore({ provider: "chroma", collection: "business-docs",
host: "localhost", port: 8000 });
routingModel = ChatModel({ provider: "openai", model: "gpt-3.5-turbo",
apiKey: "your-api-key" });
aiService = Agent({
chatLanguageModel: chatModel,
retrievalAugmentor: {
queryRouter: {
routingModel: routingModel,
contentRetrievers: [
{ type: "embeddingStore",
params: { embeddingStore: technicalStore, maxResults: 5 },
description: "Technical docs" },
{ type: "embeddingStore",
params: { embeddingStore: businessStore, maxResults: 5 },
description: "Business docs" }
]
}
}
});
response = aiService.chat("How do I configure SSL for production?");
writeOutput(response);Example 2: Input and output guardrails
sensitiveGuardrail = function(userMessage) {
patterns = ["ssn", "social security", "credit card", "password"];
for (p in patterns) {
if (findNoCase(p, userMessage))
return { action: "fatal", reason: "Sensitive data detected: #p#" };
}
return { action: "success", reason: "OK" };
};
safetyGuardrail = function(aiResponse) {
unsafe = ["violence", "hate"];
for (u in unsafe) {
if (findNoCase(u, aiResponse))
return { action: "failure", reason: "Unsafe content: #u#" };
}
return { action: "success", reason: "Safe" };
};
aiService = Agent({
chatLanguageModel: chatModel,
retrievalAugmentor: {
queryRouter: {
contentRetrievers: [
{ type: "embeddingStore",
params: { embeddingStore: vectorStore, maxResults: 5 },
description: "Company KB" }
]
}
},
inputGuardrails: [ sensitiveGuardrail ],
outputGuardrails: [ safetyGuardrail ]
});
try {
response = aiService.chat("What are the standard operating procedures?");
writeOutput(response);
} catch (any e) {
writeOutput("Blocked: #e.message#");
}Example 3: Custom prompt template with metadata keys
ragService = Agent({
CHATMODEL: chatModel,
ingestion: {
source: docsDir,
documentSplitter: { chunkSize: 500, chunkOverlap: 100 },
vectorStoreIngestor: { vectorStore: vectorStore }
},
retrievalAugmentor: {
contentInjector: {
promptTemplate: "Sources:" & chr(10) &
"{{contents}}" & chr(10) & chr(10) &
"Based on the sources above, answer: {{userMessage}}" & chr(10) &
"Cite the source file names.",
metadataKeys: ["file_name"]
},
queryRouter: {
contentRetrievers: [{
vectorStore: vectorStore,
maxResults: 3,
minScore: 0.3,
description: "Knowledge base"
}]
}
}
});
ragService.ingest();
answer = ragService.chat("How to update TIN?");
writeOutput(answer.message);
We're glad. Tell us how this page helped.
We're sorry. Can you tell us what didn't work for you?
Share additional feedback to help us improve.
0/255
|
