Configuration and Sync¶

Call taimoe.platform.init() once per process. It creates and binds a TaimoeRegistry, configures observability, performs one synchronous configuration refresh, starts background polling, and optionally enables framework instrumentation.

from taimoe.platform import init

registry = init(
    platform_url="https://platform.example.com",
    api_key="...",
    runtime_name="support-prod",
    runtime_id="support-prod",
    framework="google-adk",
    poll_interval_seconds=300,
    instrument=True,
)

Environment variables¶

Variable	Purpose
`TAIMOE_VIRTUAL_KEY`	Preferred Platform and Gateway credential.
`TAIMOE_PLATFORM_URL`	Platform base URL. Production deployments should set it explicitly.
`TAIMOE_RUNTIME_NAME`	Enables runtime-bound batch synchronization.
`TAIMOE_RUNTIME_TOKEN`	Deprecated alias for `TAIMOE_VIRTUAL_KEY`.

If no Platform URL is supplied, the SDK uses http://localhost:8000 for local development. Do not rely on this default in production.

Synchronization modes¶

Runtime-bound¶

Pass runtime_name when a long-running service has a registered Runtime. One poll retrieves every active Agent configuration bound to that Runtime.

Runtime-less¶

Omit runtime_name when an application only consumes named Agent configuration. Calling taimoe.agent("support") subscribes that name to the per-Agent syncer. This is suitable for local tools, adk web, and processes that cannot expose discovery endpoints.

The modes can coexist. A runtime-bound process can still subscribe to an Agent that is not part of its Runtime batch.

Startup and degraded mode¶

init() attempts one refresh before returning. If the Platform cannot be reached, initialization continues and the background syncer retries later. Instructions use a visible bootstrap message until configuration arrives; requesting a missing model raises TaimoeConfigUnavailableError instead of guessing an alias.

Use on_sync_error for operational reporting and registry.sync_once(ignore_errors=False) in CI when synchronization failure must fail the process. Call registry.stop_sync() during an orderly shutdown.

Initialization is idempotent: a second call returns the existing Registry and logs a warning rather than replacing process-wide state.