API Reference | AgentDuet SDK

Public API for agentduet 1.0.0. For integration patterns, see Concepts and Integrations.

SessionManagerConfig

SessionManagerConfig.create(
    api_key=...,
    connector_uuid=...,
    call_audio=CallAudioConfig(sample_rate=16000),  # optional
)
SessionManagerConfig.create(
    cert_path="/etc/certs/client.pem",
    key_path="/etc/certs/client.key",
    call_audio=...,
)

SessionManager

Hold one for the life of your process: async with SessionManager(config) as sm:.

Method	Description
`@on_incoming_call`	Receives `IncomingCallNotification` for every incoming call.
`@on_incoming_message`	Receives `IncomingMessage` for every incoming WhatsApp message.
`await open_session(session_id, subscriber)`	Ephemeral session (get-or-create). Returns `Session`.
`await list_sessions(subscriber=None, offset=0, limit=50)`	List active sessions. Returns `list[SessionInfo]` (`session_id`, `subscriber`, `participants`, `created_at`, `last_activity_at`).
`await setup_trigger_conditions(config)`	Set routing. See Trigger Conditions.
`start()`	Begin delivering inbound notifications. Idempotent.
`await run_forever(install_signal_handlers=True)`	Start delivery until interrupt or `disconnect()`. Default installs SIGINT/SIGTERM handlers (replacing existing ones). Pass `False` if your app owns signals.
`await disconnect()`	Disconnect and release resources; wakes `run_forever()`.

Property: id (server-assigned connection id; None until connected).

Session

Method	Description
`await process_call(noti)`	Attach to a notified call; returns ready `Call`.
`await make_call(dest)`	Outbound `Call` to `Address`, state `NEW`. Then `dial()`.
`await send_message(msg)`	Send an outbound message (`BaseSendMessage` subclass such as `SendWAMessage`). Returns `SendMessageResult`.

Properties: id, subscriber.

Address

API	Description
`Address.telco(value)`	Phone endpoint (`TELCO`).
`Address.whatsapp(value)`	WhatsApp endpoint (`WA`).
`network` / `value`	Network enum and address string.

Frozen and hashable (usable as a dict key).

IncomingCallNotification

Field	Description
`call_id`	Call id (also `call.id` after `process_call`).
`subscriber`	Pass to `open_session()`.
`participant`	External party (`Address`).
`network`	Shorthand for `participant.network`.
`created_at`	Notify time, unix epoch seconds.

IncomingMessage

Delivered to @sm.on_incoming_message (WhatsApp).

Field	Description
`id`	Message id (dedup key).
`subscriber`	Your business identity; pass to `open_session()`.
`participant`	Sender (`Address`); reply target.
`network`	Shorthand for `participant.network`.
`payload`	Raw WhatsApp webhook payload (`dict`).

SendWAMessage

Outbound WhatsApp body for session.send_message().

Field	Description
`api_version`	Cloud API version (for example `"v23.0"`).
`data`	Provider request dict (`messaging_product`, `type`, `to`, `text`, …).

SendMessageResult

Returned by session.send_message(). Check result.success. Unlike CommandResult, this type is not bool-like (if result: is always true).

Field	Description
`success`	`True` on success.
`response_content`	Provider response payload when present.
`error_code`	A `MessageErrorCode` on failure.
`error_content`	Human-readable failure detail.

See WhatsApp Messaging and Error Handling.

Call

Command methods return CommandResult (truthy on success) for operational failures.

Method	Description
`await answer()`	Answer inbound.
`await dial(*, ring_time_seconds=60)`	Ring outbound. Falsy: `CALL_UNANSWERED` / `TIMEOUT`.
`await connect(*, ring_time_seconds=60)`	3-way conference.
`await whisper()`	After `connect()`: agent → subscriber only.
`await barge()`	After `connect()`: agent → both.
`await spy()`	After `connect()`: listen only.
`await disconnect()`	End for all parties.
`await close()`	Release agent; after `connect()`, parties may stay up.
`await send_audio(audio_data)`	Queue PCM out.
`await clear_send_audio_buffer()`	Drop queued outbound audio.
`await get_send_audio_buffer_size()`	Outgoing buffer bytes.
`@on_hangup`	Hangup handler (`CallEvent.HANGUP`).
`@on_call_event(event)`	Call event handlers.
`to_json()` / `from_json(data)`	Handoff; only in `CallState.NEW`.

Audio in: call.caller.audio_stream() / call.callee.audio_stream().

Properties: id, participant, subscriber, caller, callee, state, audio_config.

CallState

NEW · OPENING · RINGING · LIVE · TERMINATED

CallEvent

HANGUP · ERROR

CallParty

Member	Description
`value`	Address string.
`audio_stream()`	Async iterator of that party’s PCM.

CallAudioConfig

Field	Notes
`sample_rate`	`8000` \| `16000` \| `24000` (required when constructing).
`buffer_size`	Outgoing ring buffer bytes (power of two).
`inbound_queue_maxsize`	Per-track inbound chunk cap (default `1000`).

CommandResult

Field	Description
`success`	`True` on success. The `CommandResult` itself is also truthy when `success` is `True`.
`error_code`	Server code or `"TIMEOUT"`.
`error_message`	Human-readable detail.
`payload`	Optional server payload.

VoiceAgent

High-level runner. See VoiceAgent.

API	Description
`VoiceAgent(config, *, tools=None, on_transcript=None, on_usage=None, inbound=...)`	Construct with a `SessionManagerConfig`.
`VoiceAgent.from_env(*, sample_rate=24000, ...)`	Build from `AGENTDUET_*` env vars.
`run(model)` / `await serve(model)`	Serve inbound calls with a `VoiceModel`.
`call_out` / `await dial`	One-shot outbound call on its own client.
`await place_call(...)`	Outbound on a running `serve()` client.
`is_serving`	`True` while `serve()` is running.

Adapter seam

Member	Description
`await VoiceModel.open()`	Returns a `ModelSession` for one call.
`await ModelSession.push_audio(pcm)`	Caller audio in.
`ModelSession.events()`	Yields `AudioOut`, `Interrupted`, `ToolCall`, `TranscriptDelta`, `Usage`.
`await ModelSession.send_tool_result(call_id, result)`	Tool outcome back to the model.
`await ModelSession.close()`	End the model session on hangup.

Optional model adapters live in agentduet-adapters (see VoiceAgent). Integrations use a direct provider bridge.

Helpers

new_session_id() - mint a unique session id string.
TriggerConditionsBuilder / InboundCallMode - see Trigger Conditions.
SendWAMessage / IncomingMessage / MessageErrorCode - see WhatsApp Messaging.

Next Step

Error Handling

Understand SDK exception hierarchy, CommandResult status codes, and recovery mechanisms.