Event Model

Alquimia’s execution engine is event-driven. Every action the agent takes — calling an LLM, executing a tool, flushing memory — is represented as a typed Pydantic model that is emitted, dispatched, and consumed by the controller.

Commands and responses

Events are split into two categories:

Commands — intent to do something. Emitted by the controller stages.

Command	Trigger
`AssistantInference`	Start a new inference run
`ResponseInference`	Call the LLM with the current conversation
`ShieldInference`	Run a guard/classifier model
`ServerToolExecution`	Execute a tool on an MCP/Llama Stack server
`ClientToolExecution`	Request the client to execute a tool
`A2AInference`	Delegate to another agent
`ToolSchema`	Discover tool schemas from a tool source
`AgentDiscovery`	Discover available agents from the registry
`HumanApprovalRequired`	Request human approval before tool execution
`ContextFlush`	Trigger long-term memory summarization
`ContextPersistence`	Persist the current conversation state

Responses — something that happened. Consumed by the controller stages.

Response	Produced by
`AssistantInferenceResponse`	Final answer — terminates the loop
`ResponseInferenceResponse`	LLM call result
`ShieldInferenceResponse`	Guard model result
`ToolExecutionResponse`	Tool execution result
`ToolSchemaResponse`	Tool schema discovery result
`AgentDiscoveryResponse`	Agent discovery result
`HumanApprovalRequiredResponse`	Human approval decision
`ContextFlushResponse`	Memory summarization result
`EmpathyRuleMatchedResponse`	An empathy rule matched and short-circuited the normal response path

CloudEvent registration

Every event type is registered with a CloudEvent type string via the @register_event decorator:

@register_event("com.alquimia.response.inference.v1")
class ResponseInference(BaseCommand):
    query: str
    conversation: Conversation
    parameters: ResponseProfile

This enables serialization to/from the CloudEvents spec for distributed deployments. The runtime uses CloudEvent headers to route events between services.

The control_id

Every command carries a control_id (UUID). The corresponding response carries the same control_id. The worklog uses (event_class, control_id) as a lookup key, enabling O(1) response matching.

# Command emitted by the stage
command = ResponseInference(
    control_id="abc-123",
    query="What is the capital of France?",
    ...
)

# Response consumed by the stage
response = ResponseInferenceResponse(
    control_id="abc-123",  # same ID
    result=AIMessage(content="Paris"),
)

control_id is also the correlation key for exceptions — all ControllerException subclasses carry the control_id of the event that triggered the failure. See Exceptions Reference.

Event flow example

A single inference with one tool call:

AssistantInference
    │
    ▼ (Preprocess stage)
ShieldInference ──────────────────► ShieldInferenceResponse
    │
    ▼ (Process stage)
ToolSchema ───────────────────────► ToolSchemaResponse
    │
ResponseInference ────────────────► ResponseInferenceResponse (tool_calls=[search])
    │
ServerToolExecution ──────────────► ToolExecutionResponse (result="Paris")
    │
ResponseInference ────────────────► ResponseInferenceResponse (content="Paris is...")
    │
    ▼ (Answer stage)
ContextFlush ─────────────────────► ContextFlushResponse
    │
ContextPersistence ───────────────► (no response, fire-and-forget)
    │
    ▼
AssistantInferenceResponse

Observability

Every event that passes through evaluate() is observed by AlquimiaObserver. The observer increments the appropriate metric counter or histogram based on the event type. All metrics carry the CommonAttributes dimensions (assistant_id, session_id, etc.) from the current inference context.

See Core SDK Observability for the full metrics reference.

Architecture — how the controller processes events
evaluate() reference — the orchestration function
Exceptions Reference — exceptions keyed by control_id
Core SDK Observability — metrics emitted per event type