atem studio — cloud ConvoAI agents + telephony

[guohai]

Summary

A new atem studio command family for managing cloud ConvoAI agents and connecting them to phone calls over a SIP trunk. This is the CLI/TUI counterpart of Agora's Conversational AI Studio.

How it differs from atem agent

• atem agent → local dev agents (Claude Code, Codex) over ACP/PTY.
• atem studio → cloud ConvoAI voice agents, optionally bridged to the PSTN.

Same word "agent", two scopes — disambiguated by the command family.

Proposed command surface

atem studio number import / list / remove     # SIP endpoints (number + trunk creds)
atem studio agent  create / list / show / update / delete / start / stop
atem studio call                              # start an agent + dial out
atem studio hangup
atem studio list                              # running agents + active calls

Design notes

• Provider-agnostic telephony. atem does not integrate the Twilio API. Users provision numbers + SIP trunks with their provider's own CLI (Twilio, Telnyx, Exotel…), then atem studio number import takes generic SIP params: --number, --trunk-address, --sip-username, --sip-password. SIP credentials go in the encrypted store.
• Reuse. Agent definitions reuse the existing convo.toml schema (convo_config.rs). /join and /leave logic exists in convo_test_server.rs. The serv list/kill registry pattern fits active calls.
• Lifecycle. agent start/stop runs an agent in a channel (no phone); call/hangup is the telephony path. These are distinct from atem serv convo, which is a local demo harness, not agent management.
• Capabilities. atem studio agent show reports an agent's capabilities (phone_call, …). Capability-specific actions are flat verbs gated by that list — no generic toolbox wrapper.

Open questions (Phase 0 research)

1. The exact ConvoAI Engine telephony API — the endpoint that places an outbound call through a SIP trunk.
2. Whether Agora's API accepts generic SIP trunk params (address + user/pass) vs. provider-keyed fields — the whole provider-agnostic design rests on this.
3. SIP trunk setup story — one-time manual (provider CLI), or atem-assisted.
4. Inbound calls — in scope for v1, or outbound-only first.

Suggested phasing

Phase	Deliverable
0	Research — pin the telephony API, confirm Q1–Q4
1	Twilio-agnostic number import / list / remove
2	Cloud agent definitions (agent create/list/...) on convo_config.rs
3	Outbound call / hangup
4	Inbound routing (if in scope)
5	TUI Studio mode

This is a large epic — best split into per-phase sub-issues once Phase 0 lands.

Part of the atem roadmap.