Models

EventEnvelopeWithMetadata

Bases: BaseModel

Client readable representation of an Event. Includes class metadata in order to support matching event types semantically in an extendable manner (e.g. "StartEvent", "StopEvent", etc.).

Parameters:

Name	Type	Description	Default
value	dict[str, Any]		required
qualified_name	str | None		required
type	str		required
types	list[str] | None		required

Source code in llama_agents/client/protocol/serializable_events.py

class EventEnvelopeWithMetadata(BaseModel):
    """
    Client readable representation of an Event. Includes class metadata in order to support
    matching event types semantically in an extendable manner (e.g. "StartEvent", "StopEvent", etc.).
    """

    value: dict[str, Any]

    # deprecated, use type instead
    qualified_name: str | None

    # New metadata
    type: str
    types: list[str] | None

    def load_event(self, registry: list[Type[Event]] = []) -> Event:
        """
        Attempts to load the event data as a python class based on the envelope metadata.
        Looks up the event from the registry, if provided. Falls back to the qualified_name, attempting to load from the module path.
        """
        registry_lookup = {e.__name__: e for e in registry}
        as_event_envelope = EventEnvelope(
            value=self.value, type=self.type, qualified_name=self.qualified_name
        ).model_dump()
        return EventEnvelope.parse(
            client_data=as_event_envelope, registry=registry_lookup
        )

    @classmethod
    def from_event(
        cls, event: Event, include_qualified_name: bool = True
    ) -> EventEnvelopeWithMetadata:
        """
        Build a backward-compatible envelope for an Event, preserving existing
        fields (e.g., qualified_name, value) while adding metadata useful for
        type-safe clients.

        """
        # Start with the existing JSON-serializable structure
        value = event.model_dump(mode="json")

        envelope = EventEnvelopeWithMetadata(
            value=value,
            qualified_name=_get_qualified_name(type(event))
            if include_qualified_name
            else None,
            types=_get_event_subtypes(type(event)),
            type=type(event).__name__,
        )
        return envelope

load_event

load_event(registry: list[Type[Event]] = []) -> Event

Attempts to load the event data as a python class based on the envelope metadata. Looks up the event from the registry, if provided. Falls back to the qualified_name, attempting to load from the module path.

Source code in llama_agents/client/protocol/serializable_events.py

def load_event(self, registry: list[Type[Event]] = []) -> Event:
    """
    Attempts to load the event data as a python class based on the envelope metadata.
    Looks up the event from the registry, if provided. Falls back to the qualified_name, attempting to load from the module path.
    """
    registry_lookup = {e.__name__: e for e in registry}
    as_event_envelope = EventEnvelope(
        value=self.value, type=self.type, qualified_name=self.qualified_name
    ).model_dump()
    return EventEnvelope.parse(
        client_data=as_event_envelope, registry=registry_lookup
    )

from_event classmethod

from_event(event: Event, include_qualified_name: bool = True) -> EventEnvelopeWithMetadata

Build a backward-compatible envelope for an Event, preserving existing fields (e.g., qualified_name, value) while adding metadata useful for type-safe clients.

Source code in llama_agents/client/protocol/serializable_events.py

@classmethod
def from_event(
    cls, event: Event, include_qualified_name: bool = True
) -> EventEnvelopeWithMetadata:
    """
    Build a backward-compatible envelope for an Event, preserving existing
    fields (e.g., qualified_name, value) while adding metadata useful for
    type-safe clients.

    """
    # Start with the existing JSON-serializable structure
    value = event.model_dump(mode="json")

    envelope = EventEnvelopeWithMetadata(
        value=value,
        qualified_name=_get_qualified_name(type(event))
        if include_qualified_name
        else None,
        types=_get_event_subtypes(type(event)),
        type=type(event).__name__,
    )
    return envelope

HandlerData

Bases: BaseModel

Parameters:

Name	Type	Description	Default
handler_id	str		required
workflow_name	str		required
run_id	str | None		required
error	str | None		required
result	EventEnvelopeWithMetadata | None		required
status	Literal['running', 'completed', 'failed', 'cancelled']		required
started_at	str		required
updated_at	str | None		required
completed_at	str | None		required

Source code in llama_agents/client/protocol/__init__.py

class HandlerData(BaseModel):
    handler_id: str
    workflow_name: str
    run_id: str | None
    error: str | None
    result: EventEnvelopeWithMetadata | None
    status: Status
    started_at: str
    updated_at: str | None
    completed_at: str | None

HandlersListResponse

Bases: BaseModel

Parameters:

Name	Type	Description	Default
handlers	list[HandlerData]		required

Source code in llama_agents/client/protocol/__init__.py

class HandlersListResponse(BaseModel):
    handlers: list[HandlerData]

SendEventResponse

Bases: BaseModel

Parameters:

Name	Type	Description	Default
status	Literal['sent']		required

Source code in llama_agents/client/protocol/__init__.py

class SendEventResponse(BaseModel):
    status: Literal["sent"]

CancelHandlerResponse

Bases: BaseModel

Parameters:

Name	Type	Description	Default
status	Literal['deleted', 'cancelled']		required

Source code in llama_agents/client/protocol/__init__.py

class CancelHandlerResponse(BaseModel):
    status: Literal["deleted", "cancelled"]