935f2fbd1f
- Removed legacy agent profile settings from the .env.example and README, streamlining the configuration process. - Introduced a new local YAML configuration adapter for assistant settings, allowing for easier management of assistant profiles. - Updated backend integration documentation to clarify the behavior of assistant config sourcing based on backend URL settings. - Adjusted various service implementations to directly utilize API keys from the new configuration structure. - Enhanced test coverage for the new local YAML adapter and its integration with backend services.
55 lines
1.7 KiB
Markdown
55 lines
1.7 KiB
Markdown
# Backend Integration and History Bridge
|
|
|
|
This engine uses adapter-based backend integration so core runtime logic can run
|
|
with or without an external backend service.
|
|
|
|
## Runtime Modes
|
|
|
|
Configure with environment variables:
|
|
|
|
- `BACKEND_MODE=auto|http|disabled`
|
|
- `BACKEND_URL`
|
|
- `BACKEND_TIMEOUT_SEC`
|
|
- `ASSISTANT_LOCAL_CONFIG_DIR` (default: `engine/config/agents`)
|
|
- `HISTORY_ENABLED=true|false`
|
|
|
|
Mode behavior:
|
|
|
|
- `auto`: use HTTP backend adapter only when `BACKEND_URL` is set.
|
|
- `http`: force HTTP backend adapter (falls back to null adapter when URL is missing).
|
|
- `disabled`: force null adapter and run engine-only.
|
|
|
|
Assistant config source behavior:
|
|
|
|
- If `BACKEND_URL` exists and backend mode is enabled, fetch assistant config from backend.
|
|
- If `BACKEND_URL` is missing (or backend mode is disabled), load assistant config from local YAML.
|
|
- `assistant_id` query parameter is still required and maps to `engine/config/agents/<assistant_id>.yaml` when local YAML source is active.
|
|
|
|
## Architecture
|
|
|
|
- Ports: `core/ports/backend.py`
|
|
- Adapters: `app/backend_adapters.py`
|
|
- Compatibility wrappers: `app/backend_client.py`
|
|
|
|
`Session` and `DuplexPipeline` receive backend capabilities via injected adapter
|
|
methods instead of hard-coding backend client imports.
|
|
|
|
## Async History Writes
|
|
|
|
Session history persistence is handled by `core/history_bridge.py`.
|
|
|
|
Design:
|
|
|
|
- transcript writes are queued with `put_nowait` (non-blocking turn path)
|
|
- background worker drains queue
|
|
- failed writes retry with exponential backoff
|
|
- finalize waits briefly for queue drain before sending call finalize
|
|
- finalize is idempotent
|
|
|
|
Related settings:
|
|
|
|
- `HISTORY_QUEUE_MAX_SIZE`
|
|
- `HISTORY_RETRY_MAX_ATTEMPTS`
|
|
- `HISTORY_RETRY_BACKOFF_SEC`
|
|
- `HISTORY_FINALIZE_DRAIN_TIMEOUT_SEC`
|