--- title: "SDK configuration: variables, egress, and telemetry" description: "Configure the application process embedding the Duale AI SDK: environment variables, egress destinations, logging, telemetry export, and local health." lang: en status: public-preview lastUpdated: 2026-10-23 url: https://duale.ai/en/docs/sdk/configuration --- ## AI-generated summary 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](https://duale.ai/en/docs/sdk/activity-caching.md). 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//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`](https://duale.ai/en/docs/sdk/reference.md#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: ```mermaid flowchart LR accTitle: Where an application with the SDK connects accDescr { Your 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. } Process[Your application with the SDK] Api[Duale AI API origin] Storage[File storage host] Collector[Your telemetry collector, optional] Cache[Your Redis for activity results, optional] Process -->|Tasks, Tool Host, Libraries| Api Process -->|file bytes through signed upload addresses| Storage Process -->|traces and metrics| Collector Process -->|cached activity results| Cache ``` | 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 | Duale AI, not your process, reaches the model endpoints in your pool. [Plan the deployment](https://duale.ai/en/docs/model-routing/plan-deployment.md) explains that separate network path, and [End-to-end encryption](https://duale.ai/en/docs/security/end-to-end-encryption.md) 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: ```bash 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](https://duale.ai/en/docs/sdk/errors.md#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](https://duale.ai/en/docs/sdk/reference.md#backpressureconfig). ## Related content - [Python SDK reference: ask, next, AgentResponse](https://duale.ai/en/docs/sdk/reference.md) - [Python SDK: install, submit a Task, and validate results](https://duale.ai/en/docs/sdk.md) - [Troubleshoot the SDK: task outcomes and error fixes](https://duale.ai/en/docs/sdk/troubleshooting.md) - [Manage Libraries: create, upload, and verify ingestion](https://duale.ai/en/docs/sdk/manage-libraries.md) - [Documentation: integration, capabilities, and limits](https://duale.ai/en/docs.md) - [Deployment: managed service and self-hosted options](https://duale.ai/en/product/deployment.md) --- ## Sitemap See the full [Markdown sitemap](https://duale.ai/sitemap.md) for all pages.