High-level agent execution library built on top of the LemonAi library.

LemonAgent provides a complete framework for building AI agents that can:

• Execute multi-turn conversations with tool use
• Stream responses with fine-grained event notifications
• Handle complex agentic loops (prompt -> response -> tool calls -> results -> repeat)
• Manage agent state and lifecycle as a GenServer

Relationship to the LemonAi Library

The LemonAi library provides low-level LLM API abstractions - streaming, message types, provider implementations, etc. LemonAgent builds on top of this to provide:

• Agent Loop - The core loop that handles tool execution and multi-turn conversations
• Agent GenServer - A supervised process that manages agent state and handles concurrency
• Event System - Rich events for UI integration and progress tracking
• Extended Types - Agent-specific types like AgentTool with execute functions

┌─────────────────────────────────────────────────────────────────┐
│                         Your Application                        │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  LemonAgent                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │    Agent    │  │    Loop     │  │  EventStream / Types    │ │
│  │  (GenServer)│  │ (core logic)│  │  (events & structures)  │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────┐
│  LemonAi Library                                                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │   stream/3  │  │   Types     │  │      Providers          │ │
│  │ complete/3  │  │  Context    │  │ (Anthropic, OpenAI,...) │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Quick Start

Using the Agent GenServer (recommended)

The Agent GenServer provides a supervised, stateful interface with event subscriptions:

# Start an agent
{:ok, agent} = LemonAgent.new_agent(
  model: my_model,
  system_prompt: "You are a helpful assistant.",
  tools: [read_file_tool, write_file_tool]
)

# Subscribe to events
LemonAgent.subscribe(agent, self())

# Send a prompt (non-blocking)
:ok = LemonAgent.prompt(agent, "Hello, can you help me?")

# Receive events as they arrive
receive do
  {:agent_event, {:message_start, msg}} ->
    IO.puts("Assistant started responding...")

  {:agent_event, {:message_update, msg, delta}} ->
    IO.write(delta)

  {:agent_event, {:tool_execution_start, id, name, args}} ->
    IO.puts("Executing tool: #{name}")

  {:agent_event, {:agent_end, messages}} ->
    IO.puts("Agent finished with #{length(messages)} messages")
end

# Or wait for the agent to finish
:ok = LemonAgent.wait_for_idle(agent)
state = LemonAgent.get_state(agent)

Using the Loop directly (advanced)

For more control, you can use the Loop module directly:

alias LemonAgent.{Loop, Types}

# Create initial state
state = %Types.AgentState{
  system_prompt: "You are helpful",
  model: my_model,
  tools: my_tools,
  messages: []
}

# Create config with required callbacks
config = %Types.AgentLoopConfig{
  model: my_model,
  convert_to_llm: &my_convert_fn/1
}

# Run the loop (returns a stream of events)
state
|> Loop.agent_loop(config, user_message)
|> Enum.each(fn event ->
  IO.inspect(event)
end)

Events

LemonAgent emits detailed events throughout agent execution:

Agent Lifecycle

• {:agent_start} - Agent run has begun
• {:tool_schema_snapshot, snapshot} - Tool schema was frozen for the run
• {:agent_end, messages} - Agent run completed with final message list

Turn Lifecycle

• {:turn_start} - New turn (LLM call) has started
• {:turn_end, message, tool_results} - Turn completed

Message Lifecycle

• {:message_start, message} - Message processing started
• {:message_update, message, delta} - Streaming update
• {:message_end, message} - Message processing complete

Tool Execution

• {:tool_execution_start, id, name, args} - Tool started
• {:tool_execution_update, id, name, args, partial} - Partial result
• {:tool_execution_end, id, name, result, is_error} - Tool completed

Configuration

The AgentLoopConfig struct controls agent behavior:

%LemonAgent.Types.AgentLoopConfig{
  # Required: the model to use
  model: my_model,

  # Required: convert agent messages to LLM format
  convert_to_llm: fn messages -> {:ok, llm_messages} end,

  # Optional: transform context before each LLM call
  # (useful for context window management)
  transform_context: fn messages, signal -> {:ok, transformed} end,

  # Optional: get API key dynamically (for OAuth tokens)
  get_api_key: fn provider -> api_key end,

  # Optional: inject steering messages mid-run
  get_steering_messages: fn -> [] end,

  # Optional: add follow-up prompts to keep agent running
  get_follow_up_messages: fn -> [] end,

  # Optional: streaming options
  stream_options: %LemonAi.Types.StreamOptions{}
}

Modules

• LemonAgent.Agent - GenServer for stateful agent management
• LemonAgent.Loop - Core agentic loop implementation
• LemonAgent.EventStream - Async event producer/consumer
• LemonAgent.Types - Type definitions and structs
• LemonAgent.Proxy - Stream proxy for event transformation