Configuration Reference

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.

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, and its Javadoc has parameter and validation details. The Javadoc ships as tnsai-core-<version>-javadoc.jar in the TnsAI Maven repository.

• 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 knowledge: memoryStore, memoryConfig, knowledge, actionKnowledge, knowledgeScope, knowledgeUsageListener
• 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 knowledge, pass KnowledgeEntry values to knowledge. Each wraps a KnowledgeSourceConfig and, for a SEARCH entry, optional SearchSettings. See RAG.

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.

Audit and liability recording has no environment variable. AgentFactory wires no LiabilitySink, so a bundled-server deployment records nothing until you configure one. See Audit agent actions.

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 _, and <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.