Agents¶

Forage creates AI agents with configurable chat models, memory providers, and guardrails for LangChain4j integration.

Quick Start¶

forage.myAgent.agent.model.kind=ollama
forage.myAgent.agent.model.name=granite4:3b
forage.myAgent.agent.base.url=http://localhost:11434
forage.myAgent.agent.features=memory
forage.myAgent.agent.memory.kind=message-window
forage.myAgent.agent.memory.max.messages=20

- to:
    uri: langchain4j-agent:myAgent
    parameters:
      agent: "#myAgent"

Properties¶

Property	Description	Type	Default	Required
`forage.provider.features`	Comma-separated list of agent features to enable (e.g., memory)	`String`
`forage.guardrails.input`	Comma-separated list of input guardrail names (@ForageBean values, e.g., pii-detector,keyword-filter)	`String`
`forage.guardrails.output`	Comma-separated list of output guardrail names (@ForageBean values, e.g., sensitive-data,output-length)	`String`
`forage.multi.agent.names`	Comma-separated list of named agent prefixes for multi-agent setup	`String`
`forage.multi.agent.id.source`	Source for extracting agent ID (route-id, header, property, variable)	`String`
`forage.agent.model.kind`	The model provider kind (e.g., ollama, openai, google-gemini, azure-openai, anthropic)	`bean-name`		Yes
`forage.agent.features`	Comma-separated list of enabled features (e.g., memory)	`String`
`forage.agent.memory.kind`	The memory provider kind (e.g., message-window, redis, infinispan)	`bean-name`
`forage.agent.base.url`	Base URL for the model provider API	`String`
`forage.agent.model.name`	The specific model name to use	`String`
`forage.agent.temperature`	Temperature for response randomness (0.0-2.0)	`String`
`forage.agent.endpoint`	Azure OpenAI resource endpoint URL	`String`
`forage.agent.deployment.name`	Azure OpenAI deployment name	`String`
`forage.agent.timeout`	Request timeout duration in ISO-8601 format (e.g. PT120S for 120 seconds)	`String`
`forage.agent.memory.max.messages`	Maximum number of messages to retain in memory	`String`	`20`
`forage.agent.embedding.store.kind`	The embedding store provider kind (e.g., in-memory-store, qdrant, pgvector, redis, milvus)	`bean-name`
`forage.agent.in.memory.store.file.source`	Path to a file to be loaded into store.	`String`
`forage.agent.in.memory.store.max.size`	The maximum size of the segment, defined in characters.	`int`
`forage.agent.in.memory.store.overlap.size`	The maximum size of the overlap, defined in characters.	`int`
`forage.agent.guardrails.input`	Comma-separated list of input guardrail names (@ForageBean values, e.g., pii-detector,keyword-filter)	`String`
`forage.agent.guardrails.output`	Comma-separated list of output guardrail names (@ForageBean values, e.g., sensitive-data,output-length)	`String`
`forage.agent.embedding.model.base.url`	Base URL for the embedding model provider (falls back to forage.agent.base.url when not set)	`String`
`forage.agent.embedding.model.name`	The specific model name to use	`String`
`forage.agent.embedding.model.timeout`	Used for the HttpClientBuilder that will be used to communicate with Ollama	`Duration`
`forage.agent.embedding.model.max.retries`	Used for the HttpClientBuilder that will be used to communicate with Ollama	`int`
`forage.agent.rag.max.results`	The maximum number of Contents to retrieve.	`int`
`forage.agent.rag.min.score`	The minimum relevance score for the returned Contents.	`String`
`forage.infinispan.server-list`	Comma-separated list of Infinispan server addresses in format 'host1:port1,host2:port2'	`String`	`localhost:11222`	Yes
`forage.infinispan.cache-name`	Name of the cache for storing chat messages	`String`	`chat-memory`	Yes
`forage.redis.host`	Redis server hostname or IP address	`string`	`localhost`	Yes
`forage.redis.port`	Redis server port number	`String`	`6379`	Yes
`forage.redis.database`	Redis database number to connect to	`String`	`0`
`forage.memory.message-window.max.messages`	Maximum number of messages to retain in memory	`integer`	`10`
`forage.guardrail.keyword.filter.blocked.words`	Comma-separated list of words to block	`string`
`forage.guardrail.keyword.filter.case.sensitive`	Whether matching should be case-sensitive	`boolean`	`false`
`forage.guardrail.keyword.filter.whole.word.match`	Whether to match whole words only	`boolean`	`true`
`forage.guardrail.pii.detect.types`	Comma-separated list of PII types to detect: EMAIL, PHONE, SSN, CREDIT_CARD, IP_ADDRESS	`string`	`EMAIL,PHONE,SSN,CREDIT_CARD,IP_ADDRESS`
`forage.guardrail.pii.block.on.detection`	Whether to block the message when PII is detected (true) or just warn (false)	`boolean`	`true`
`forage.guardrail.input.length.max.chars`	Maximum allowed character count for input messages	`integer`	`10000`
`forage.guardrail.input.length.min.chars`	Minimum required character count for input messages	`integer`	`1`
`forage.guardrail.prompt.injection.strict`	Enable strict mode (fail on any single pattern match)	`boolean`	`false`
`forage.guardrail.code.injection.strict`	Enable strict mode (fail on any single pattern match)	`boolean`	`false`
`forage.guardrail.code.injection.detect.types`	Comma-separated list of injection types to detect: SHELL_COMMAND, SQL_INJECTION, JAVASCRIPT, HTML_XSS, PATH_TRAVERSAL, COMMAND_CHAINING, TEMPLATE_INJECTION	`string`	`SHELL_COMMAND,SQL_INJECTION,JAVASCRIPT,HTML_XSS,PATH_TRAVERSAL,COMMAND_CHAINING,TEMPLATE_INJECTION`
`forage.guardrail.json.format.required.fields`	Comma-separated list of required field names in the JSON	`string`
`forage.guardrail.json.format.extract.json`	Whether to extract JSON from surrounding text	`boolean`	`true`
`forage.guardrail.json.format.allow.array`	Whether to allow JSON arrays (not just objects)	`boolean`	`true`
`forage.guardrail.output.length.max.chars`	Maximum allowed character count for output messages	`integer`	`50000`
`forage.guardrail.output.length.min.chars`	Minimum required character count for output messages	`integer`	`1`
`forage.guardrail.output.length.truncate.on.overflow`	Whether to truncate instead of failing on overflow	`boolean`	`false`
`forage.guardrail.sensitive.data.detect.types`	Comma-separated list of sensitive data types to detect: API_KEY, AWS_KEY, SECRET, PRIVATE_KEY, CREDIT_CARD, SSN, JWT, CONNECTION_STRING, GITHUB_TOKEN	`String`	`API_KEY,AWS_KEY,SECRET,PRIVATE_KEY,CREDIT_CARD,SSN,JWT,CONNECTION_STRING,GITHUB_TOKEN`
`forage.guardrail.sensitive.data.action`	Action to take when sensitive data is detected: BLOCK, REDACT, WARN	`String`	`BLOCK`
`forage.guardrail.sensitive.data.redaction.text`	Text to use for redaction when action is REDACT	`String`	`[REDACTED]`
`forage.azure.openai.api.key`	Azure OpenAI API key for authentication	`password`		Yes
`forage.azure.openai.endpoint`	Azure OpenAI resource endpoint URL (e.g., https://your-resource.openai.azure.com/)	`String`		Yes
`forage.azure.openai.deployment.name`	Azure OpenAI deployment name (e.g., gpt-35-turbo, gpt-4)	`String`		Yes
`forage.azure.openai.service.version`	Azure OpenAI API service version (e.g., 2024-02-01)	`String`
`forage.azure.openai.temperature`	Temperature for response generation (0.0-2.0): lower values are more deterministic, higher values are more creative	`String`
`forage.azure.openai.max.tokens`	Maximum number of tokens in the model's response	`String`
`forage.openai.model.name`	The specific OpenAI model to use	`String`	`gpt-4o-mini`	Yes
`forage.openai.base.url`	Custom base URL for OpenAI API	`String`
`forage.openai.temperature`	Temperature for response randomness (0.0-2.0)	`String`
`forage.ollama.base.url`	The base URL of the Ollama server	`String`	`http://localhost:11434`
`forage.ollama.model.name`	The Ollama model to use	`String`	`llama3.2`
`forage.ollama.temperature`	Temperature for response randomness (0.0-2.0)	`String`
`forage.ollama.num.ctx`	Context window size	`String`
`forage.ollama.timeout`	Request timeout duration in ISO-8601 format (e.g. PT120S for 120 seconds)	`String`
`forage.google.api.key`	Google AI API key for authentication	`password`		Yes
`forage.google.model.name`	Google Gemini model name (e.g., gemini-pro, gemini-pro-vision, gemini-1.5-pro)	`string`		Yes
`forage.google.temperature`	Temperature for response randomness (0.0-2.0)	`double`
`forage.anthropic.api.key`	Anthropic API key for authentication	`password`		Yes
`forage.anthropic.model.name`	Claude model name (e.g., claude-sonnet-4-20250514, claude-haiku-4-5-20251001, claude-opus-4-20250115)	`string`	`claude-sonnet-4-20250514`
`forage.anthropic.temperature`	Temperature for response generation (0.0-1.0): lower values are more deterministic, higher values are more creative	`double`
`forage.anthropic.max.tokens`	Maximum number of tokens in the model's response	`String`
`forage.bedrock.region`	AWS region where Bedrock is available	`string`	`us-east-1`	Yes
`forage.bedrock.model.id`	Bedrock model identifier (e.g., anthropic.claude-3-5-sonnet-20240620-v1:0)	`string`
`forage.bedrock.temperature`	Sampling temperature for response randomness (0.0-1.0)	`double`		Yes
`forage.dashscope.api.key`	Alibaba Dashscope API key for authentication	`password`		Yes
`forage.dashscope.model.name`	Qwen model name (e.g., qwen-turbo, qwen-plus, qwen-max, qwen-max-longcontext)	`string`	`qwen-turbo`
`forage.dashscope.temperature`	Temperature for response generation (0.0-2.0): lower values are more deterministic, higher values are more creative	`double`
`forage.dashscope.max.tokens`	Maximum number of tokens in the model's response	`String`
`forage.huggingface.api.key`	HuggingFace API key for authentication	`password`		Yes
`forage.huggingface.model.id`	The HuggingFace model ID to use (e.g., microsoft/DialoGPT-medium)	`string`
`forage.huggingface.temperature`	Temperature for response generation (0.0-2.0)	`double`
`forage.huggingface.max.new.tokens`	Maximum number of new tokens to generate	`integer`
`forage.localai.base.url`	The LocalAI server endpoint URL	`String`		Yes
`forage.localai.model.name`	The model to use (must be available on LocalAI server)	`String`
`forage.localai.temperature`	Temperature for response generation (0.0-2.0)	`String`
`forage.localai.user`	User identifier for tracking and monitoring	`String`
`forage.mistralai.api.key`	MistralAI API key for authentication	`password`		Yes
`forage.mistralai.model.name`	The MistralAI model to use	`string`	`mistral-large-latest`
`forage.mistralai.temperature`	Temperature for response generation (0.0-1.0)	`double`
`forage.watsonxai.api.key`	IBM Cloud API key for authentication	`String`		Yes
`forage.watsonxai.url`	The Watsonx.ai service URL (e.g., https://us-south.ml.cloud.ibm.com)	`String`		Yes
`forage.watsonxai.project.id`	The Watsonx.ai project ID	`String`		Yes
`forage.watsonxai.model.name`	The foundation model to use	`String`	`llama-3-405b-instruct`
`forage.watsonxai.temperature`	Temperature for response generation (0.0-2.0)	`String`
`forage.ollama.embedding.model.base.url`	The base URL of the Ollama server	`string`	`http://localhost:11434`
`forage.ollama.embedding.model.name`	The Ollama model to use	`string`	`nomic-embed-text`
`forage.ollama.embedding.model.timeout`	Used for the HttpClientBuilder that will be used to communicate with Ollama	`Duration`
`forage.ollama.embedding.model.max.retries`	Used for the HttpClientBuilder that will be used to communicate with Ollama	`int`
`forage.rag.max.results`	The maximum number of Contents to retrieve.	`int`
`forage.rag.min.score`	The minimum relevance score for the returned Contents.	`double`

Security

Property	Description	Type	Default	Required
`forage.agent.api.key`	API key for authentication with the model provider	`String`
`forage.agent.embedding.model.api.key`	API key for the embedding model provider (falls back to forage.agent.api.key when not set)	`String`
`forage.infinispan.username`	Username for authentication (optional)	`String`
`forage.infinispan.password`	Password for authentication (optional)	`String`
`forage.infinispan.realm`	Security realm for authentication	`String`	`default`
`forage.infinispan.sasl-mechanism`	SASL mechanism for authentication	`String`	`DIGEST-MD5`
`forage.redis.password`	Redis authentication password (optional)	`String`
`forage.openai.api.key`	OpenAI API key for authentication	`String`		Yes
`forage.bedrock.access.key.id`	AWS access key ID (optional, uses default credential chain if not provided)	`String`		Yes
`forage.bedrock.secret.access.key`	AWS secret access key (optional, uses default credential chain if not provided)	`String`		Yes
`forage.bedrock.session.token`	AWS session token for temporary STS credentials (optional, used together with access key ID and secret access key)	`String`		Yes
`forage.localai.api.key`	LocalAI API key for authentication (optional)	`password`

Advanced

Property	Description	Type	Default	Required
`forage.provider.model.factory.class`	Fully qualified class name of the model provider factory	`String`
`forage.provider.features.memory.factory.class`	Fully qualified class name of the chat memory factory	`String`
`forage.provider.agent.class`	Fully qualified class name of the agent factory implementation	`String`
`forage.multi.agent.id.source.header`	Exchange header name to extract agent ID from	`String`
`forage.multi.agent.id.source.property`	Exchange property name to extract agent ID from	`String`
`forage.multi.agent.id.source.variable`	Exchange variable name to extract agent ID from	`String`
`forage.agent.max.tokens`	Maximum number of tokens in the response	`String`
`forage.agent.top.p`	Top-P (nucleus) sampling parameter (0.0-1.0)	`String`
`forage.agent.top.k`	Top-K sampling parameter	`String`
`forage.agent.log.requests`	Enable request logging	`String`
`forage.agent.log.responses`	Enable response logging	`String`
`forage.infinispan.connection-timeout`	Connection timeout in milliseconds	`String`	`60000`
`forage.infinispan.socket-timeout`	Socket timeout in milliseconds	`String`	`60000`
`forage.infinispan.max-retries`	Maximum number of connection retries	`String`	`3`
`forage.infinispan.pool.max-active`	Maximum number of active connections per server	`String`	`20`
`forage.infinispan.pool.min-idle`	Minimum number of idle connections per server	`String`	`1`
`forage.infinispan.pool.max-wait`	Maximum time to wait for a connection in milliseconds	`String`	`3000`
`forage.redis.timeout`	Connection timeout in milliseconds	`String`	`2000`
`forage.redis.pool.max-total`	Maximum number of connections in the pool	`String`	`10`
`forage.redis.pool.max-idle`	Maximum number of idle connections in the pool	`String`	`5`
`forage.redis.pool.min-idle`	Minimum number of idle connections in the pool	`String`	`1`
`forage.redis.pool.test-on-borrow`	Test connections when borrowing from pool	`String`	`true`
`forage.redis.pool.test-on-return`	Test connections when returning to pool	`String`	`true`
`forage.redis.pool.test-while-idle`	Test idle connections periodically	`String`	`true`
`forage.redis.pool.max-wait-millis`	Maximum time to wait for a connection from the pool in milliseconds	`String`	`2000`
`forage.azure.openai.top.p`	Top-p (nucleus sampling) probability threshold (0.0-1.0)	`String`
`forage.azure.openai.presence.penalty`	Presence penalty for discouraging new topic introduction (-2.0 to 2.0)	`String`
`forage.azure.openai.frequency.penalty`	Frequency penalty for discouraging token repetition (-2.0 to 2.0)	`String`
`forage.azure.openai.seed`	Seed for deterministic response generation (same seed + same input = similar output)	`String`
`forage.azure.openai.user`	User identifier for tracking and monitoring API usage	`String`
`forage.azure.openai.timeout`	Request timeout in seconds	`String`
`forage.azure.openai.max.retries`	Maximum number of retry attempts for failed requests	`String`
`forage.azure.openai.log.requests.and.responses`	Enable logging of requests and responses (warning: may log sensitive data)	`boolean`
`forage.openai.max.tokens`	Maximum number of tokens to generate	`String`
`forage.openai.top.p`	Top-P (nucleus) sampling parameter (0.0-1.0)	`String`
`forage.openai.frequency.penalty`	Frequency penalty (-2.0 to 2.0)	`String`
`forage.openai.presence.penalty`	Presence penalty (-2.0 to 2.0)	`String`
`forage.openai.log.requests`	Enable request logging	`String`
`forage.openai.log.responses`	Enable response logging	`String`
`forage.openai.timeout`	Request timeout duration	`String`
`forage.openai.http1`	Use HTTP/1.1 instead of HTTP/2	`String`
`forage.ollama.top.k`	Top-K sampling parameter	`String`
`forage.ollama.top.p`	Top-P (nucleus) sampling parameter (0.0-1.0)	`String`
`forage.ollama.min.p`	Minimum probability threshold (0.0-1.0)	`String`
`forage.ollama.log.requests`	Enable request logging	`String`
`forage.ollama.log.responses`	Enable response logging	`String`
`forage.google.timeout`	Request timeout in seconds	`String`
`forage.google.log.requests`	Enable request and response logging	`boolean`
`forage.google.max.output.tokens`	Maximum number of output tokens	`String`
`forage.google.top.p`	Top-p (nucleus sampling) parameter (0.0-1.0)	`double`
`forage.google.top.k`	Top-k sampling parameter	`String`
`forage.anthropic.top.p`	Top-p (nucleus sampling) probability threshold (0.0-1.0)	`double`
`forage.anthropic.top.k`	Top-k sampling parameter: limits the model to consider only the top-k most probable tokens	`String`
`forage.anthropic.stop.sequences`	Comma-separated stop sequences that cause the model to stop generating further tokens	`string`
`forage.anthropic.timeout`	Request timeout in seconds	`String`
`forage.anthropic.max.retries`	Maximum number of retry attempts for failed requests	`String`
`forage.anthropic.log.requests.and.responses`	Enable logging of requests and responses (warning: may log sensitive data)	`boolean`
`forage.bedrock.max.tokens`	Maximum number of tokens to generate	`integer`		Yes
`forage.bedrock.top.p`	Top-P (nucleus) sampling parameter (0.0-1.0)	`double`		Yes
`forage.dashscope.top.p`	Top-p (nucleus sampling) probability threshold (0.0-1.0)	`String`
`forage.dashscope.top.k`	Top-k sampling parameter: limits the model to consider only the top-k most probable tokens	`String`
`forage.dashscope.repetition.penalty`	Repetition penalty for discouraging token repetition (0.0-2.0)	`String`
`forage.dashscope.seed`	Seed for deterministic response generation (same seed + same input = similar output)	`String`
`forage.dashscope.enable.search`	Enable web search functionality to provide more up-to-date information	`boolean`
`forage.dashscope.timeout`	Request timeout in seconds	`String`
`forage.dashscope.max.retries`	Maximum number of retry attempts for failed requests	`String`
`forage.dashscope.log.requests.and.responses`	Enable logging of requests and responses (warning: may log sensitive data)	`boolean`
`forage.huggingface.return.full.text`	Whether to return full text including input	`boolean`
`forage.huggingface.wait.for.model`	Whether to wait for the model to load if it's not ready	`boolean`
`forage.huggingface.timeout`	Request timeout in seconds	`integer`
`forage.localai.max.tokens`	Maximum number of tokens for model responses	`String`
`forage.localai.top.p`	Top-p (nucleus sampling) probability threshold (0.0-1.0)	`String`
`forage.localai.presence.penalty`	Presence penalty for discouraging new topic introduction (-2.0 to 2.0)	`String`
`forage.localai.frequency.penalty`	Frequency penalty for discouraging token repetition (-2.0 to 2.0)	`String`
`forage.localai.seed`	Seed for deterministic response generation	`String`
`forage.localai.timeout`	Request timeout in seconds	`String`
`forage.localai.max.retries`	Maximum number of retry attempts for failed requests	`String`
`forage.localai.log.requests.and.responses`	Enable request and response logging	`boolean`
`forage.mistralai.max.tokens`	Maximum number of tokens for model responses	`String`
`forage.mistralai.top.p`	Top-p (nucleus sampling) parameter (0.0-1.0)	`double`
`forage.mistralai.random.seed`	Random seed for reproducible results	`String`
`forage.mistralai.timeout`	Request timeout in seconds	`String`
`forage.mistralai.max.retries`	Maximum number of retry attempts	`String`
`forage.mistralai.log.requests.and.responses`	Enable request and response logging	`boolean`
`forage.watsonxai.max.new.tokens`	Maximum number of new tokens in response	`String`
`forage.watsonxai.top.p`	Top-p (nucleus sampling) parameter (0.0-1.0)	`String`
`forage.watsonxai.random.seed`	Random seed for reproducible results	`String`
`forage.watsonxai.stop.sequences`	Stop sequences for response generation (comma-separated)	`String`
`forage.watsonxai.log.requests.and.responses`	Enable request and response logging	`String`
`forage.ollama.embedding.model.log.requests`	Enable request logging	`boolean`
`forage.ollama.embedding.model.log.responses`	Enable response logging	`boolean`

Available Chat Models¶

Name	Description
`azure-openai`	OpenAI models hosted on Microsoft Azure
`openai`	OpenAI API-compatible models
`ollama`	Locally-hosted models via Ollama (Llama, Mistral, etc.)
`google-gemini`	Google Gemini models
`anthropic`	Anthropic Claude models
`bedrock`	Amazon Bedrock multi-model provider supporting Claude, Llama, Titan, Cohere, and Mistral
`dashscope`	Alibaba Cloud Qwen models via DashScope
`hugging-face`	Open-source models via HuggingFace Inference API
`local-ai`	Self-hosted models via LocalAI (OpenAI-compatible)
`mistral-ai`	Mistral AI models
`watsonx-ai`	IBM Watsonx.ai models

Available Memory Providers¶

Name	Description
`infinispan`	Distributed storage using Infinispan
`redis`	Persistent storage using Redis
`message-window`	In-memory storage with configurable message window size

Guardrails¶

Guardrails validate agent inputs and outputs (e.g., PII detection, keyword filtering). They must be explicitly enabled — adding a guardrail jar to the classpath is not enough.

Configuration¶

List guardrails by their @ForageBean value (comma-separated):

forage.myAgent.agent.guardrails.input=pii-detector,keyword-filter
forage.myAgent.agent.guardrails.output=pii-redactor

For MultiAgentFactory (shared across agents):

forage.guardrails.input=pii-detector
forage.guardrails.output=pii-redactor

Fail-closed semantics

If a selected guardrail cannot be created (missing dependency, misconfiguration), the application fails at startup with a descriptive error. Guardrails are security controls — they are never silently skipped.

Available Input Guardrails¶

Name	Description
`pii-detector`	Detects PII (email, phone, SSN, credit card, IP address) in input messages
`prompt-injection`	Detects prompt injection attacks (role manipulation, jailbreak, etc.)
`code-injection`	Detects code injection attacks (SQL, shell, XSS, path traversal, etc.)
`keyword-filter`	Blocks messages containing specific keywords or phrases
`input-length`	Validates input message length (min/max characters)

Available Output Guardrails¶

Name	Description
`sensitive-data`	Detects and optionally redacts sensitive data (API keys, secrets, PII) in output
`output-length`	Validates output message length (min/max characters, optional truncation)
`json-format`	Validates output is valid JSON format with optional required fields

Multimodal Content¶

Agents support multimodal inputs (images, PDFs) in both memory and memoryless modes. When memory is enabled, multimodal content is preserved alongside text in the conversation history.

Memory Isolation¶

Each agent bean gets its own isolated memory store. Two agents using the same memory.kind do not share conversation history — even if they use the same memory.kind and memory.max.messages values.

Provider Selection¶

When multiple providers of the same type are on the classpath, selection is deterministic: providers are matched by their @ForageBean value against the model.kind (or equivalent) property. If no match is found, Forage fails fast with an error listing available providers.