SDK configuration: variables, egress, and telemetry

Configure the application process embedding the Duale AI SDK: environment variables, egress destinations, logging, telemetry export, and local health.

This page covers environment variables, outbound destinations, logging, telemetry export, local health, and submission back-pressure for the embedded SDK.

DUALEAI_ environment variables and their defaults.
Outbound destinations required by the egress policy.
Logging behavior and handler replacement on construction.
Telemetry export via observability endpoint and token.
Local health status and submission back-pressure.

Summaries were generated by AI.

Configure the application process that embeds the SDK: its environment variables, the outbound destinations your egress policy must allow, logging, telemetry export, and local health.

Environment variables

DualeAIConfig reads DUALEAI_ environment variables. Explicit configuration values override the environment. Nested observability keys use a double underscore. For installed applications, export these variables or pass configuration explicitly; do not depend on the SDK finding your application’s .env file.

Variable	Field	Default	Notes
`DUALEAI_TOKEN`	`token`	required	The Agent Identity API token, carrying the `dualeai_` prefix. The SDK exchanges it for the short-lived credential each call presents, and renews that credential for you.
`DUALEAI_ENDPOINT`	`endpoint`	`https://api.beta.duale.ai`	An HTTPS origin, such as `https://api.beta.duale.ai`. No service path, embedded credentials, query, or fragment; a trailing slash is accepted. HTTPS is required in local development too.
`DUALEAI_AGENT_ID`	`agent_id`	none	Required to publish Tools. Also supplies the default identity for task attachment uploads, which accept a per-call `agent_id=` override. Starts with a letter; letters, digits, hyphen, underscore; 3–50 characters.
`DUALEAI_TENANT_ID`	`tenant_id`	none	Required for Library management and attachment uploads.
`DUALEAI_REDIS_URL`	`redis_url`	`redis://localhost:8010`	Activity cache. Accepts `redis://` or `rediss://` for TLS. Falls back to SQLite after a Redis connection failure.
`DUALEAI_SQLITE_PATH`	`sqlite_path`	none	Activity-cache fallback file. Defaults to `~/.dualeai/cache/<API-token-hash>/cache.db`. Setting a path does not skip Redis.
`DUALEAI_DEBUG`	`debug`	`false`	Verbose logging.
`DUALEAI_OBSERVABILITY__ENDPOINT`	`observability.endpoint`	`http://localhost:4318`	OTLP over HTTP base endpoint for your own collector. A separate outbound destination from `DUALEAI_ENDPOINT`.
`DUALEAI_OBSERVABILITY__TOKEN`	`observability.token`	none	Enables telemetry export. Use a telemetry token, never your `dualeai_` API token.

create_sdk accepts the same settings as keyword arguments.

Allow outbound destinations

Your application process opens every connection, and nothing connects to it from outside. Allow these destinations in your egress policy:

Where an application with the SDK connectsYour application process opens every connection, and nothing connects to it from outside. It reaches the Duale AI API origin for Tasks, Tool Host publication and Libraries, over HTTPS with end-to-end encryption. It sends file bytes to a separate storage host through signed, time-limited upload addresses. It can also export its own traces and metrics to your collector and keep activity results in your Redis.

Destination	When the SDK uses it	Protection
Duale AI API origin, `DUALEAI_ENDPOINT`	Always: credential exchange, Tasks, Tool Host publication and heartbeats, Tool Results, Libraries	HTTPS; Task, Tool Host, Tool Result, and Library requests also use end-to-end encryption
File storage host, named in each upload response	Attachment and Library uploads	HTTPS through signed, time-limited upload URLs
Your collector, `DUALEAI_OBSERVABILITY__ENDPOINT`	Only when telemetry export is on	Your collector’s transport; use an `https://` endpoint off the host
Your Redis, `DUALEAI_REDIS_URL`	Only when your code uses `@activity`	`rediss://` for TLS

Destination
Duale AI API origin, DUALEAI_ENDPOINT
When the SDK uses it
Always: credential exchange, Tasks, Tool Host publication and heartbeats, Tool Results, Libraries
Protection
HTTPS; Task, Tool Host, Tool Result, and Library requests also use end-to-end encryption
Destination
File storage host, named in each upload response
When the SDK uses it
Attachment and Library uploads
Protection
HTTPS through signed, time-limited upload URLs
Destination
Your collector, DUALEAI_OBSERVABILITY__ENDPOINT
When the SDK uses it
Only when telemetry export is on
Protection
Your collector’s transport; use an https:// endpoint off the host
Destination
Your Redis, DUALEAI_REDIS_URL
When the SDK uses it
Only when your code uses @activity
Protection
rediss:// for TLS

Duale AI, not your process, reaches the model endpoints in your pool. Plan the deployment explains that separate network path, and End-to-end encryption explains which exchanges that encryption covers.

Logging

Constructing the SDK replaces the process’s root logging handlers with its console handler. The default level is ERROR; DUALEAI_DEBUG=true selects DEBUG. Cleanup does not restore previous handlers. If your application owns logging, configure its handlers after constructing the SDK.

Telemetry export

Set the observability endpoint and its separate token to export traces and metrics to your collector. The SDK appends /v1/traces and /v1/metrics to that endpoint. It does not configure OTLP log export. Install the telemetry extra to add automatic instrumentation for aiohttp, Redis, SQLite, and system metrics:

python -m pip install 'dualeai[telemetry]'

Export requires the observability token. Core trace and metric exporters are already installed with the base package. Providers and automatic instrumentation affect the whole process; coordinate them with any existing OpenTelemetry setup. SDK cleanup does not flush or shut down global providers.

Local health

sdk.get_health_status() returns local status, components, uptime_seconds, inflight_tasks, and registered_tools. It checks neither remote readiness nor the activity cache. Uninitialized components report healthy, so use separate checks for connectivity and Tool publication.

Submission back-pressure

Task submissions use no local queue. A process-local circuit breaker blocks new submissions after repeated failures; Circuit breaker states when it opens and closes. To tune it, or to bound how many cached activities run and wait at once, pass a BackpressureConfig.

Environment variables Allow outbound destinations Logging Telemetry export Local health Submission back-pressure

Last updatedOctober 23, 2026