Reference

Advanced Topics

View as Markdown

Logging, concurrency, and delivery semantics for production deployments.

Failure modes and delivery

TopicBehavior
RedeliveryInbound is at-least-once. Dedup calls on IncomingCallNotification.call_id and WhatsApp on IncomingMessage.id.
OrderingConnector-wide competing-consumer. Notifications may arrive concurrently / out of order. Correlate by (subscriber, participant).
Session idle~30-minute sliding TTL. Next process_call / make_call / send_message transparently re-opens once.
ReconnectsSession-manager link auto-reconnects with jittered exponential backoff. Established voice calls are unaffected. If the voice transport drops, on_hangup fires and in-flight ops raise CallClosedError.
Inbound backpressurePer-track queue (inbound_queue_maxsize, default 1000). When full, oldest chunk is dropped.
Outbound backpressuresend_audio() raises BufferFullError when the ring buffer is full.
Audio after hangupsend_audio / clear_send_audio_buffer raise CallClosedError.
ShutdownLeaving async with SessionManager (or signal in run_forever) cancels still-running inbound handlers. Put cleanup in try/finally inside the handler.

Logging

The SDK uses stdlib logging with a NullHandler - configure it in your app.

import logging
logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
)
logging.getLogger("agentduet").setLevel(logging.DEBUG)
logging.getLogger("agentduet.voice_session").setLevel(logging.DEBUG)

Useful loggers: agentduet, agentduet.session_manager_connection, agentduet.voice_session, agentduet.call.

The SDK does not log secrets (API keys, tokens, certs). Connection URLs and call ids may appear for debugging.

Thread safety and concurrency

  • Each incoming call and incoming message runs in its own task.
  • Heartbeat and reconnect run in background tasks.
  • Write ordinary async/await in handlers; the SDK manages lifecycle.

For your own bridge, run model I/O as concurrent tasks and cancel them on hangup.

Cross-node handoff

Serialize only in CallState.NEW. See Sessions and Handoff.

Support

Questions and bug reports: support@agentduet.com. Credentials: agentduet.com.