@type agent_event() ::
  {:agent_start}
  | {:tool_schema_snapshot, snapshot :: LemonAgent.Types.ToolSchemaSnapshot.t()}
  | {:loop_state_transition, from :: atom() | nil, to :: atom(),
     metadata :: map()}
  | {:agent_end, messages :: [agent_message()]}
  | {:turn_start}
  | {:turn_end, message :: agent_message(),
     tool_results :: [LemonAi.Types.ToolResultMessage.t()]}
  | {:loop_budget_exhausted, details :: map()}
  | {:message_start, message :: agent_message()}
  | {:message_update, message :: agent_message(), assistant_event :: term()}
  | {:message_end, message :: agent_message()}
  | {:tool_execution_start, id :: String.t(), name :: String.t(), args :: map()}
  | {:tool_execution_update, id :: String.t(), name :: String.t(),
     args :: map(), partial_result :: LemonAgent.Types.AgentToolResult.t()}
  | {:tool_execution_end, id :: String.t(), name :: String.t(),
     result :: LemonAgent.Types.AgentToolResult.t(), is_error :: boolean()}
  | {:error, reason :: term(), partial_state :: term()}

Events emitted by the Agent for UI updates and lifecycle tracking.

These events provide fine-grained information about messages, turns, and tool executions.

Agent Lifecycle

• {:agent_start} - Agent run has started
• {:tool_schema_snapshot, snapshot} - Tool schema was frozen for this run
• {:loop_state_transition, from, to, metadata} - Loop lifecycle state changed
• {:agent_end, messages} - Agent run has ended with final messages

Turn Lifecycle

A turn is one assistant response plus any tool calls/results.

• {:turn_start} - New turn has started
• {:turn_end, message, tool_results} - Turn completed
• {:loop_budget_exhausted, details} - Tool loop budget exhausted with terminal fallback

Message Lifecycle

Emitted for user, assistant, and tool_result messages.

• {:message_start, message} - Message processing started
• {:message_update, message, assistant_event} - Streaming update (assistant only)
• {:message_end, message} - Message processing complete

Tool Execution Lifecycle

• {:tool_execution_start, id, name, args} - Tool execution started
• {:tool_execution_update, id, name, args, partial_result} - Streaming partial result
• {:tool_execution_end, id, name, result, is_error} - Tool execution complete

Error Handling

• {:error, reason, partial_state} - Agent loop errored

@type agent_message() :: LemonAi.Types.message()

Agent message type - alias for LemonAi.Types.message().

This can be extended by applications to include custom message types beyond the standard user/assistant/tool_result messages.

@type thinking_level() :: :off | :minimal | :low | :medium | :high | :xhigh

Thinking/reasoning level for models that support extended reasoning.

• :off - No extended thinking
• :minimal - Minimal reasoning output
• :low - Low reasoning effort
• :medium - Medium reasoning effort
• :high - High reasoning effort
• :xhigh - Extra high reasoning (only supported by certain OpenAI models)