Handler-surface parity with the TypeScript SDK: four handlers, four shapes — and the error hook is the one real divergence
I maintainer di solito rispondono entro 5 giorni
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 25/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Attiva
- Stack tecnologico
- python, typescript
- Ambito
- api
Direzione di ricerca
Start with the cited handler definitions in src/tac/core/tac.py and compare them with the TypeScript references in the issue; the companion issue is twilio-agent-connect-typescript#106. The request is to decide and publish a canonical handler surface and document the cross-SDK mapping, not to make a specified code change. Done means the intended convention and any deliberate language-specific differences are clearly stated for both SDKs.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
This SDK and twilio-agent-connect-typescript expose the same four conceptual event handlers with four different registration shapes. Most of the difference is idiomatic and we are not asking for it to be removed. One of the four is not idiomatic, and that is the part worth a decision.
Filing in both repositories because neither alone can settle it. Companion: twilio/twilio-agent-connect-typescript#106.
Citations are file:line at 2c24bd988c29cdefbb69875ac38ed739b9215a7b (main HEAD, transcribed 2026-10-08) and, for TypeScript, at 022449cf3a730d7877c23c5f5e2d3655e2e40897. Navigation only.
The measured divergence
| handler | this SDK | twilio-agent-connect-typescript |
|---|---|---|
| message ready | three positionals — (message: str, context: ConversationSession, memory: TACMemoryResponse | None) -> str | None (src/tac/core/tac.py:266-272) |
one object, 8 members — { conversationId, profileId, message, author, memory, session, channel, abortSignal? } (packages/core/src/lib/tac.ts:29-38) |
| interrupt | two positionals — (context, interrupt_data: Any) (tac.py:294-300) |
one object — { conversationId, utteranceUntilInterrupt, durationUntilInterruptMs, session } (tac.ts:40-45) |
| conversation ended | one positional — (context) (tac.py:318-323) |
one object — { session } (tac.ts:47-49) |
| error | TAC.on_error(cb) — on TAC, typed (Exception, dict[str, Any]) (tac.py:341-347) |
channel.on('error', cb) — on the channel, untyped (...args: any[]), dispatched by a switch on a string (packages/core/src/channels/base.ts:123-134) |
What we checked and found is NOT a gap
Recording these because they are the obvious-looking differences and they do not hold up — we would rather not send anyone after them.
authorandchannelare reachable here.ConversationSessioncarrieschannel: str(src/tac/models/session.py:45),author_info: AuthorInfo | None(:53) andai_agent_info(:56). The TypeScript handler receivesauthorandchannelas flattened members of its params object; here they are one level down, oncontext. That is depth, not absence.- The missing
abortSignalis not a missing capability. TypeScript needs an explicitAbortSignalbecause aPromiseis not cancellable.asynciocancellation is native here, and this SDK deliberately supports it:src/tac/channels/base.py:371-372and:403-404re-raiseasyncio.CancelledErrorwith the comment "Re-raise to allow proper cancellation (e.g., Voice channel interrupts)". Two idioms for one capability.
The one that is a real divergence
The error handler is registered on a different object in each SDK, and only one of them is typed. This SDK's design is the better one and we think it should be the one that wins:
- it is on
TAC, so an application registers once and observes everything the SDK handles internally, rather than once per channel; - it is typed —
(Exception, dict[str, Any])— where the TypeScript side accepts(...args: any[])through a stringly-typed dispatcher that has nodefaultclause, so a misspelled event name there registers nothing and reports nothing; - its docstring states the purpose exactly right: "surface failures that TAC handles internally but that would otherwise be invisible to your application". That is the problem both SDKs have, and only this one gives the application a hook for it.
What we think should happen
- Decide and publish which handler surface is canonical, so handlers added to either SDK converge rather than diverge further. The event surface is the newest and most active part of both, which is where divergence accumulates fastest.
- For the error hook specifically, we think the TypeScript side should adopt this SDK's shape — a typed,
TAC-level handler — rather than this SDK adopting theirs. Raised on the companion issue. - If the positional-versus-object difference is deliberately per-language (which is defensible — a params object is natural in TS, keyword arguments are native here), documenting the mapping somewhere both SDKs point at would be enough. A table like the one above.
Context, offered as motivation rather than a request: we maintain a code generator that emits Agent Connect clients, and it has to choose one event-handler shape. Where the two hand-written SDKs disagree, any choice is wrong for one of them. "This is intentional, here is the mapping" is a perfectly good answer and is actionable in a way silence is not.
Thanks for reading.
- Lingua principale
- Python
- Stelle
- 17
- Fork
- 11
- Merge medio
- 5g 19h
- PR unite (30g)
- 6
Preparare l'ambiente
- Nessun Dockerfile né file Docker Compose
- Ha un modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di twilio/twilio-agent-connect-python
-
ParticipantResponse.name is required where the API definition marks it nullable, so a nameless participant fails to parseForse già presa @TheeCoderAhmed l’ha presa 22 giorni fa. Aperta
Difficoltà 1/5 Meno di un'ora Idoneità per principianti 86/100
twilio/twilio-agent-connect-python#134 ·
I maintainer di solito rispondono entro 5 giorni
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 50/100
twilio/twilio-agent-connect-python#136 ·
I maintainer di solito rispondono entro 5 giorni
-
Difficoltà 4/5 3-5 giorni Idoneità per principianti 45/100
twilio/twilio-agent-connect-python#133 ·
I maintainer di solito rispondono entro 5 giorni
-
Difficoltà 5/5 Più di una settimana Idoneità per principianti 30/100
twilio/twilio-agent-connect-python#101 ·
I maintainer di solito rispondono entro 5 giorni
-
add tac config validationsForse già presa @rahulsjha l’ha presa 4 giorni fa. Aperta
Difficoltà 3/5 1-2 giorni Idoneità per principianti 45/100
twilio/twilio-agent-connect-python#70 · 1 commento ·
I maintainer di solito rispondono entro 5 giorni
Tutte le issue di twilio/twilio-agent-connect-python
Issue simili
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 64/100
I maintainer di solito rispondono entro 1 giorno
-
Harden tools/pr_threads.sh: pass all printed thread fields through the deterministic sanitizerApertaarea:cli area:security enhancement priority:medium size:small
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
RonaldHensbergen/composable-data-stack#1338 ·
I maintainer di solito rispondono entro 1 giorno
-
area:stdlib effort:S impact:med platform:linux type:bug
Difficoltà 2/5 1-3 ore Idoneità per principianti 84/100
I maintainer di solito rispondono entro 1 giorno
-
automated endpoint-dead needs-curation
Difficoltà 2/5 1-3 ore Idoneità per principianti 76/100
almanac-data/climate-almanac#139 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 82/100
UKGovernmentBEIS/inspect_ai#6695 · 1 commento ·
I maintainer di solito rispondono entro 1 giorno