Mojentic.Agents.AsyncLLMAgent (Mojentic v1.2.0)

Asynchronous agent that uses an LLM to generate responses.

This module provides a reusable pattern for creating async agents that interact with language models. It wraps the synchronous Mojentic.LLM.Broker operations in async tasks to avoid blocking the dispatcher.

Features

Behaviour - System prompt defining agent personality
Response Model - JSON schema for structured output
Tools - List of tools available to the LLM
Async Generation - Non-blocking LLM calls

Usage

You can use this module in two ways:

Direct instantiation with new/1 (returns a map with behaviour)
Implementation helper with use Mojentic.Agents.AsyncLLMAgent in your module

Examples

# Option 1: Direct instantiation
defmodule MyAgent do
  @behaviour Mojentic.Agents.BaseAsyncAgent

  def init(broker) do
    AsyncLLMAgent.new(
      broker: broker,
      behaviour: "You are a helpful fact-checker.",
      response_model: %{
        "type" => "object",
        "properties" => %{
          "facts" => %{"type" => "array", "items" => %{"type" => "string"}}
        }
      }
    )
  end

  @impl true
  def receive_event_async(event) do
    agent = init(broker)
    prompt = "Check facts about: #{event.question}"
    {:ok, response} = AsyncLLMAgent.generate_response(agent, prompt)
    {:ok, [create_fact_event(response, event.correlation_id)]}
  end
end

# Option 2: Using the module directly
defmodule FactChecker do
  use Mojentic.Agents.AsyncLLMAgent

  def init(broker) do
    new(
      broker: broker,
      behaviour: "You are a fact-checker.",
      response_model: fact_schema()
    )
  end
end

Summary

Types

t()

Functions

__using__(opts)

Enables using this module in your own agent modules.

create_initial_messages(async_llm_agent)

Creates initial messages from the agent's behaviour.

generate_response(agent, content)

Generates a response from the LLM asynchronously.

new(opts)

Creates a new AsyncLLMAgent configuration.

Types

t()

@type t() :: %Mojentic.Agents.AsyncLLMAgent{
  behaviour: String.t(),
  broker: Mojentic.LLM.Broker.t(),
  response_model: map() | nil,
  tools: [module()] | nil
}

Functions

using(opts)

(macro)

Enables using this module in your own agent modules.

When you use Mojentic.Agents.AsyncLLMAgent, you get helper functions for working with async LLM agents in your own implementations.

Example

defmodule MyFactChecker do
  use Mojentic.Agents.AsyncLLMAgent

  @behaviour Mojentic.Agents.BaseAsyncAgent

  def init(broker) do
    new(
      broker: broker,
      behaviour: "You are a fact-checker.",
      response_model: my_schema()
    )
  end

  @impl true
  def receive_event_async(event) do
    agent = init(get_broker())
    {:ok, response} = generate_response(agent, event.question)
    {:ok, [create_event(response, event)]}
  end
end

create_initial_messages(async_llm_agent)

Creates initial messages from the agent's behaviour.

Returns a list containing the system message with the agent's behaviour.

Examples

iex> agent = AsyncLLMAgent.new(broker: broker, behaviour: "You are helpful.")
iex> AsyncLLMAgent.create_initial_messages(agent)
[%Message{role: :system, content: "You are helpful."}]

generate_response(agent, content)

Generates a response from the LLM asynchronously.

This function wraps the synchronous broker call in a Task to avoid blocking. It handles both structured output (via response_model) and free-form generation.

Parameters

agent - The AsyncLLMAgent configuration
content - The user prompt string

Returns

{:ok, response} - The LLM response (string or parsed object)
{:error, reason} - Generation failed

Examples

{:ok, response} = AsyncLLMAgent.generate_response(agent, "What is 2+2?")

# With structured output
{:ok, %{"answer" => "4", "confidence" => 1.0}} =
  AsyncLLMAgent.generate_response(agent, "What is 2+2?")

new(opts)

Creates a new AsyncLLMAgent configuration.

Parameters

opts - Keyword list with:
- :broker - LLM broker instance (required)
- :behaviour - System prompt defining agent behavior (required)
- :response_model - JSON schema for structured output (optional)
- :tools - List of tool modules (optional)

Examples

broker = Broker.new("qwen3:32b", Ollama)

agent = AsyncLLMAgent.new(
  broker: broker,
  behaviour: "You are a helpful assistant.",
  response_model: %{
    "type" => "object",
    "properties" => %{
      "answer" => %{"type" => "string"},
      "confidence" => %{"type" => "number"}
    }
  }
)