Configuration

#Configuration

The mAIvn SDK uses a layered configuration system that supports environment variables and programmatic configuration.

For HTTP credentials and endpoints, use ClientConfig.from_sources(...) or the corresponding Client constructor options. Agent and Swarm also accept api_key, env_file, and api_key_file. Terminal MAIVN_API_KEY values take precedence over selected files. MAIVN_API_KEY_FILE supports a mounted single-line secret. See Authentication for exact precedence, shared-client behavior, and file handling.

This page covers SDK environment and process-level settings. Invocation-time runtime controls such as memory, system tools, orchestration, structured output, and swarm transport are documented in Session Config Models.

#Import

from maivn import (
    ConfigurationBuilder,
    MaivnConfiguration,
    get_configuration,
)

#MaivnConfiguration

A compatibility view of SDK settings. Use ClientConfig for the current HTTP client configuration, or ClientBuilder.from_configuration(config) to convert this nested representation explicitly.

class MaivnConfiguration:
    server: ServerConfiguration
    execution: ExecutionConfiguration
    security: SecurityConfiguration
    logging: LoggingConfiguration

#ServerConfiguration

Server connection settings.

#ExecutionConfiguration

Compatibility execution settings. The following defaults describe a directly constructed ExecutionConfiguration, not the defaults of ClientConfig.

When converting a manually constructed compatibility configuration, omitted execution timeout fields retain ClientConfig defaults of 900, 300, and 7200 seconds respectively. ConfigurationBuilder.from_environment() records the resolved client values. These three execution-budget fields remain compatibility settings. They do not impose server execution deadlines. server.timeout_seconds controls the actual HTTP timeout.

#SecurityConfiguration

Authentication settings.

API keys are hidden in representations and human-readable validation errors. Explicit model_dump() and to_dict() output contains the key. Do not log it.

#LoggingConfiguration

Logging settings.

#ConfigurationBuilder

Factory for creating configuration from various sources.

#from_environment()

Create configuration from environment variables.

config = ConfigurationBuilder.from_environment()

# Optional explicitly selected file; process environment still wins.
config = ConfigurationBuilder.from_environment(env_file="/path/to/project/.env")

Both ConfigurationBuilder.from_environment() and ClientBuilder.from_environment() accept the same source options as ClientConfig.from_sources(), including env_file, api_key_file, endpoint overrides, project and thread IDs, and timeout settings. They share the credential precedence rules. Converting a builder-produced configuration to a client preserves the resolved endpoints and settings. No implicit dotenv or shell PATH search occurs.

#Environment Variables

The local-store variables are read when automatic private storage is needed. They are separate from ClientConfig and the compatibility configuration tables above. They read the process environment; selecting Client(env_file=...) does not load these vault settings from that file. Explicit Client(local_vault=LocalVaultConfig(...)) replaces environment-based vault configuration. See local storage setup.

#Configuration Functions

#get_configuration()

Get the current active configuration.

from maivn import get_configuration

config = get_configuration()
print(config.server.timeout_seconds)

If no configuration is set, returns a default configuration.

This is a compatibility context. To use its values, pass the configuration to ClientBuilder.from_configuration(). Client() and Agent() resolve their own explicit arguments and environment. They do not automatically consult this context.

#Examples

#Environment-Based Configuration

# .env file
MAIVN_API_KEY=your-api-key
# The SDK defaults to https://api.maivn.io; availability depends on your environment.
# Local development opts into a local address explicitly:
MAIVN_BASE_URL=http://127.0.0.1:8000

from maivn import Agent, ClientBuilder, ConfigurationBuilder

# Select a dotenv file, with exported values taking precedence.
config = ConfigurationBuilder.from_environment(env_file=".env")

# Agent uses this configuration
agent = Agent(name='my_agent', client=ClientBuilder.from_configuration(config))

#Checking Configuration

from maivn import get_configuration

config = get_configuration()

print(f'API Key set: {bool(config.security.api_key)}')
print(f'API address: {config.server.base_url}')

#Client with Custom Timeouts

from maivn import Client

# Override the actual HTTP request timeout.
client = Client(
    api_key='...',
    timeout_seconds=60,
)

Invocation RunOptions(timeout=...) can select an HTTP timeout for one request.

#Configuration Hierarchy

Use ClientConfig.from_sources() to resolve explicit values, environment, selected dotenv, and built-in defaults. Supply the resulting config= or share the client with scopes. ClientBuilder.from_configuration() converts the specific nested configuration you pass. It does not consult the active configuration context.

#Background Execution

execution.enable_background_execution is retained for source compatibility. Changing it does not change tool execution in the current SDK. Use the supported invocation and orchestration APIs for execution behavior.

#See Also

• Client - Client timeout configuration
• Session Config Models - Typed invocation runtime controls
• Logging - Logging configuration