ExAgent.Message (ExAgent v0.4.0)

Normalized message struct used across all LLM providers.

Represents a single message in a conversation, supporting system, user, assistant, and tool roles.

Summary

Types

attachment()

role()

t()

Functions

map_attachments(messages, fun)

Applies fun to every attachment on every message, halting on the first error.

new(attrs)

Creates a new message with validated attributes.

Types

attachment()

@type attachment() :: ExAgent.Attachment.t()

role()

@type role() :: :system | :user | :assistant | :tool

t()

@type t() :: %ExAgent.Message{
  attachments: [attachment()],
  content: String.t(),
  metadata: map(),
  role: role(),
  tool_call_id: String.t() | nil,
  tool_calls: [map()] | nil
}

Functions

map_attachments(messages, fun)

@spec map_attachments([t()], (attachment() -> {:ok, attachment()} | {:error, error})) ::
  {:ok, [t()]} | {:error, error}
when error: term()

Applies fun to every attachment on every message, halting on the first error.

Provider services use this to resolve attachments - loading bytes, uploading oversized files - before building a request body, so their formatting functions stay free of IO.

new(attrs)

@spec new(keyword()) :: {:ok, t()} | {:error, String.t()}

Creates a new message with validated attributes.

Examples

iex> {:ok, msg} = ExAgent.Message.new(role: :user, content: "Hello")
iex> msg.role
:user

iex> ExAgent.Message.new(role: :invalid, content: "Hello")
{:error, "invalid role: :invalid. Must be one of: [:system, :user, :assistant, :tool]"}

iex> ExAgent.Message.new(role: :user)
{:error, "content is required"}