Configuration Reference

Before you start

• Install Java 21 and the TnsAI modules for the runtime you are configuring.
• Choose one LLM provider or prepare an LLMClient implementation programmatically.
• Keep credentials outside source control and inject them through your process environment or secret manager.

Minimum working configuration

For a hosted provider, export its required credential before starting the application:

export OPENAI_API_KEY="replace-with-a-secret"

For a self-hosted OpenAI-compatible endpoint, add the matching base URL:

export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"

Then construct the client and agent as shown in the Quickstart. Constructor or builder arguments can replace these environment values when configuration is application-owned.

LLM provider environment variables

API-key clients fail loudly when neither a constructor argument nor the required environment variable is present. Every client derived from AbstractLLMClient also accepts a base-URL override derived from its key name: for example, ANTHROPIC_API_KEY maps to ANTHROPIC_BASE_URL. The table calls out aliases and required companion values that do not follow that rule.

The framework module's provider matrix is the source for provider-specific behavior. Its ProviderEnvVarConsistencyTest guards the framework README against requireApiKey(...) call sites; the Docs contract test separately guards this consolidated page.

For Vertex AI, a non-default VERTEX_AI_LOCATION must be paired with a matching regional VERTEX_AI_BASE_URL, such as https://europe-west4-aiplatform.googleapis.com. The client reads the location after deriving its default host, so setting only the location would send the regional request path to the default us-central1 hostname.

Databricks has no shared workspace endpoint. Always provide DATABRICKS_BASE_URL; the constructor's placeholder URL is not a usable service configuration.

Channel environment variables

Slack, Discord, WhatsApp, and Email configuration records can also be supplied programmatically. Their fromEnvironment() factories return an empty result when a required group is incomplete, so treat every value in the Required column as a unit. Telegram accepts its token through the adapter constructor or TELEGRAM_BOT_TOKEN.

Built-in tool environment variables

Common tool configuration is intentionally separate from provider and channel credentials:

See the tool catalog for credentials owned by individual integrations.

AgentBuilder options

AgentBuilder is the programmatic entry point for an agent. The current public surface is grouped below; the Javadoc has parameter and validation details.

• Metadata and lifecycle — id, description, version, autoStart, idleTimeoutMs, tenantId, did, groupMembership
• Model and conversation — llm, communication, promptStrategy, promptStrategies, promptEnhancer, maxContextTokens
• Identity and accountability — identity, identities, principal, liabilitySink, authorityScope, paymentBroker
• Roles, plans, and recovery — role, roles, plan, plans, errorRecoveryScenario, errorRecoveryScenarios, plannerHandle, reasoningStrategy
• Memory and retrieval — memoryStore, memoryConfig, addKnowledgeSource, knowledgeSources, retrieval, chatKnowledge, liveChatKnowledge
• Skills and tools — skillStore, skillResolver, skillResolverPolicy, maxActiveSkills, actionExecutor, toolPojos, builtInTools, dynamicTool, dynamicTools, toolCallFilter
• Reliability and validation — idempotencyStore, relaxValidation, withReachabilityChecks, reachabilityCheckTimeout, validateFully
• Entry and terminal operations — create, build

The builder does not expose per-call temperature, topP, or maxTokens setters. Configure those on the selected LLM client. For retrieval, add one or more KnowledgeSourceConfig values and a RetrievalConfig.

Server configuration

The standalone server accepts CLI arguments and environment variables. CLI values win where both forms exist.

For an embedded server, configure TnsServer, BindPolicy, AuthConfig, OriginPolicy, and WorkspaceConfig programmatically. There is no server.yml loader. YAML belongs only to the separate declarative lifecycle-hook registry, where applications explicitly parse hook definitions and register them.

Per-agent LLM overrides

The variables above configure a provider process-wide. To override a single agent's provider, model or tuning without recompiling, register an LLMConfigurationSource on the SCOP bridge. Its environment() implementation reads:

TNSAI_LLM_<AGENT>_<FIELD>

<AGENT> is the agent name upper-cased with every non-alphanumeric character replaced by _; <FIELD> is one of PROVIDER, MODEL, TEMPERATURE, MAX_TOKENS, ENDPOINT, API_KEY_ENV. A Researcher agent's model comes from TNSAI_LLM_RESEARCHER_MODEL. Names differing only in punctuation collide after normalisation.

System properties are checked before environment variables and both are read on every call. A .env file is loaded once per JVM, so editing it — including removing an override — needs a restart.

apiKeyEnv can name any variable the process can see, and endpoint decides where that value is sent as a bearer token. Treat a configuration source as trusted infrastructure; see External LLM Configuration.

Related

• Installation — dependency and initial credential setup.
• Server — standalone and embedded runtime behavior.
• Help / FAQ — common credential questions.
• Troubleshooting — missing credentials and connection failures.
• External LLM Configuration — per-agent overrides from a file or the environment.