AgentEngine.Transcript (agent_engine v0.2.0)

Copy Markdown View Source

Minimal, provider-neutral transcript for the AgentEngine.Turn loop.

A transcript is an ordered list of normalized chat messages: plain maps with string role/content keys, plus tool_calls (on assistant messages) and tool_call_id/name (on tool messages). It is distilled from the public recomposition path used by host applications:

%{"role" => "user",      "content" => "..."}
%{"role" => "assistant", "content" => "...", "tool_calls" => [%{"id" => ..., "name" => ..., "arguments" => %{...}}]}
%{"role" => "tool",      "content" => "...", "tool_call_id" => "...", "name" => "..."}

Tool-call entries are stored as serialized maps (id, name, arguments), which keeps the transcript serializable and free of provider-specific struct coupling. A host-supplied LLM function receives these maps and may pass them straight to a provider's message normalizer.

The transcript is a pure data structure: it never calls an LLM, never executes tools, and owns no persistence. AgentEngine.Turn drives it.

Summary

Types

message()
role()
t()
tool_call()

Functions

append_assistant(t, opts)

Append an assistant message.

append_system(t, content)

Append a system message. Useful for a one-shot system prompt.

append_tool_results(t, results)

Append one tool message per tool result.

append_user(t, content)

Append a user message.

from_messages(messages)

Create a transcript from an existing list of messages.

new()

Create a new empty transcript.

pending_tool_calls(transcript)

Return the pending (unanswered) tool calls from the last assistant turn.

to_messages(transcript)

Return the normalized message list, ready for an LLM provider call.

Types

message()

@type message() :: map()

role()

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

t()

@type t() :: %AgentEngine.Transcript{messages: [message()]}

tool_call()

@type tool_call() :: %{
  required(String.t()) => String.t() | map() | nil,
  optional(String.t()) => String.t() | map() | nil
}

Functions

append_assistant(t, opts)

@spec append_assistant(
  t(),
  keyword()
) :: t()

Append an assistant message.

Options:

  • :content — text content (nil when the message only carries tool calls)
  • :tool_calls — list of tool-call structs or maps (default [])

Tool calls are normalized to serialized maps: %{"id", "name", "arguments"}.

append_system(t, content)

@spec append_system(t(), String.t()) :: t()

Append a system message. Useful for a one-shot system prompt.

append_tool_results(t, results)

@spec append_tool_results(t(), [map() | struct()]) :: t()

Append one tool message per tool result.

Each result becomes its own tool-role message keyed by tool_call_id, matching provider message conventions. Accepts LlmToolkit.Tool.Result structs or equivalent maps (tool_call_id, name, content).

append_user(t, content)

@spec append_user(t(), String.t()) :: t()

Append a user message.

from_messages(messages)

@spec from_messages([map()]) :: t()

Create a transcript from an existing list of messages.

Each message is normalized to a string-keyed map via normalize/1.

new()

@spec new() :: t()

Create a new empty transcript.

pending_tool_calls(transcript)

@spec pending_tool_calls(t()) :: [tool_call()]

Return the pending (unanswered) tool calls from the last assistant turn.

A tool call is pending when its id has no subsequent tool-role message carrying the same tool_call_id. Returns [] when the last assistant message carries no tool calls, or when every call has been answered.

Tool calls are returned as serialized maps (%{"id", "name", "arguments"}).

to_messages(transcript)

@spec to_messages(t()) :: [message()]

Return the normalized message list, ready for an LLM provider call.