feat(agui): add agui event, mixin, and adding community agno event ad…

[thibaud-perrin]

Adding AGUI protocol on the main callback
Adding agno adapter to easly converte agno agent run events into digitalkin agui event objects

Changelog will be in : https://digitalkin-ai.github.io/digitalkin/dev/changelog/0.3.5_to_0.4.0

---

Migration AG-UI : nouveau protocole de streaming

A partir de 0.4.0, le SDK adopte le protocole AG-UI pour le streaming des evenements agent.
Les anciens mixins UserMessageMixin (callback_mixin) et ChatHistoryMixin sont deprecated et seront supprimes dans une version future.

Nouveaux composants

AgUiMixin

Mixin integre dans BaseMixin (donc disponible dans tous les TriggerHandler).
Convertit les evenements agent DigitalKin en evenements AG-UI et les envoie via context.callbacks.

from digitalkin.mixins import AgUiMixin

class MyTrigger(TriggerHandler, AgUiMixin):
    async def handle(self, input_data, setup_data, context):
        for event in events:
            await self.send_message(context, event)

Evenements supportes :

• Run lifecycle : RunStarted, RunCompleted, RunError
• Text messages : TextMessageStart, TextMessageContent, TextMessageEnd
• Reasoning : ReasoningStart, ReasoningMessageContent, ReasoningEnd
• Tool calls : ToolCallStart, ToolCallArgs, ToolCallEnd, ToolCallResult

AgnoStreamAdapter (community)

Adaptateur pour convertir les evenements Agno en evenements DigitalKin.
Gere automatiquement le cycle de vie (ouverture/fermeture des sequences text/reasoning).

from digitalkin.community.agno import AgnoStreamAdapter

adapter = AgnoStreamAdapter()

async for raw_event in agent.arun(message, stream=True, stream_events=True):
    for event in adapter.to_digitalkin_events(raw_event):
        await self.send_message(context, event)

# Fermer les sequences encore ouvertes en fin de stream
for event in adapter.flush():
    await self.send_message(context, event)

Modeles d'evenements (digitalkin.models.events)

Evenements framework-agnostic pour les runs agent :

Classe	Description
RunStartedEvent	Debut d'un run agent
RunContentEvent	Contenu texte streame
RunCompletedEvent	Fin d'un run
RunErrorEvent	Erreur pendant le run
TextMessageStartedEvent	Debut d'un message texte
TextMessageCompletedEvent	Fin d'un message texte
ReasoningStartedEvent	Debut d'une phase de raisonnement
ReasoningContentDeltaEvent	Delta de contenu raisonnement
ReasoningStepEvent	Etape de raisonnement
ReasoningCompletedEvent	Fin de la phase de raisonnement
ToolCallStartedEvent	Debut d'un appel outil
ToolCallCompletedEvent	Fin d'un appel outil
ToolCallErrorEvent	Erreur d'un appel outil

Modeles de sortie AG-UI (digitalkin.models.module.ag_ui)

40+ types de sortie AG-UI avec serialisation camelCase automatique et union discriminee via le champ protocol.

Architecture

Framework (Agno, ...)
    |
    v
AgnoStreamAdapter          -- convertit les events framework -> DigitalKin
    |
    v
DigitalKin Events          -- modeles framework-agnostic (agent_events.py)
    |
    v
AgUiMixin.send_message()   -- convertit DigitalKin events -> AG-UI protocol
    |
    v
context.callbacks           -- envoie vers le client via gRPC stream

Exemple complet (Agno)

from digitalkin.community.agno import AgnoStreamAdapter
from digitalkin.models.events import BaseAgentRunEvent
from digitalkin.modules.trigger_handler import TriggerHandler


@MyModule.register
class MessageTrigger(TriggerHandler):

    protocol = "agui_stream"
    input_format = AgUiStreamInput
    output_format = AgUiEventOutput

    async def handle(self, input_data, setup_data, context):
        message = extract_user_message(input_data)

        adapter = AgnoStreamAdapter()

        async def send_event(event: BaseAgentRunEvent) -> None:
            await self.send_message(context, event)

        async for raw_event in agent.arun(message, stream=True, stream_events=True):
            for event in adapter.to_digitalkin_events(raw_event):
                await send_event(event)

        for event in adapter.flush():
            await send_event(event)

Deprecations

Ancien	Nouveau	Notes
UserMessageMixin	AgUiMixin	Emettra un DeprecationWarning a l'heritage
ChatHistoryMixin	AgUiMixin	Emettra un DeprecationWarning a l'heritage
context.callbacks.send_message(output) directement	self.send_message(context, event) via AgUiMixin	Les events passent maintenant par le pipeline AG-UI

BaseMixin mis a jour

# Avant (0.3.5)
class BaseMixin(CostMixin, ChatHistoryMixin, FileHistoryMixin, LoggerMixin): ...

# Apres (0.4.0)
class BaseMixin(CostMixin, AgUiMixin, FileHistoryMixin, LoggerMixin): ...

AgUiMixin remplace ChatHistoryMixin dans la chaine d'heritage de BaseMixin.
Tous les TriggerHandler ont donc acces a self.send_message(context, event) sans import supplementaire.