> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Log

> this.messages — append-only conversation history with seq ordering and adapters for LangChain, OpenAI, and Anthropic.

`this.messages` is the actor's durable conversation log. Messages are ordered by an
assigned monotonic `seq` (insertion order, not wall-clock), and the log is append-only —
there is no delete.

## Types

```ts theme={null}
interface AgentMessage {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
  name?: string;          // tool name for role:"tool", speaker label otherwise
  toolCalls?: ToolCall[]; // present on assistant turns that request tools
  toolCallId?: string;    // links a tool result back to a ToolCall.id
}

interface ToolCall {
  id: string;
  name: string;
  args: unknown;
}

// As persisted — what reads return:
interface StoredMessage extends AgentMessage {
  seq: number; // monotonic, assigned on append
  at: Date;    // wall-clock stamp, informational only
}
```

## Writing

| Method               | Returns           | Semantics                                                            |
| -------------------- | ----------------- | -------------------------------------------------------------------- |
| `add(role, content)` | `Promise<number>` | Shorthand for `append({ role, content })`                            |
| `append(msg)`        | `Promise<number>` | Appends one `AgentMessage`, atomically assigns and returns its `seq` |
| `appendMany(msgs)`   | `Promise<number>` | Appends a batch atomically, returns the last assigned `seq`          |

## Reading

| Method    | Returns                               | Semantics                                                         |
| --------- | ------------------------------------- | ----------------------------------------------------------------- |
| `all()`   | `Promise<StoredMessage[]>`            | Full history, chronological — paginates internally, no length cap |
| `last()`  | `Promise<StoredMessage \| undefined>` | The single most-recent message                                    |
| `last(n)` | `Promise<StoredMessage[]>`            | The last `n` messages, in chronological order                     |
| `count()` | `Promise<number>`                     | Total messages ever appended                                      |

`all()` reads the entire history every time — on a long-lived conversation prefer
`last(n)` for a bounded context window.

## Adapters

Each adapter reads the full history and converts it. They differ in how they treat
`system` and `tool` messages:

| Adapter         | Output                    | `system`                                                             | `tool` / `toolCalls`                                                                                         |
| --------------- | ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `toLangChain()` | plain `{ role, content }` | included                                                             | **dropped** — only `user`/`assistant`/`system` survive                                                       |
| `toOpenAI()`    | Chat Completions messages | included                                                             | mapped to `tool_calls` / `tool_call_id`, `args` JSON-stringified                                             |
| `toAnthropic()` | Messages-API turns        | **dropped** — pass the system prompt as the top-level `system` param | assistant `toolCalls` become `tool_use` blocks; `tool` results become `user` turns with `tool_result` blocks |

```ts theme={null}
const history = await this.messages.toOpenAI();
// → ready for env.TELNYX.ai.openai.chat.createCompletion({ model, messages: history })
//   (the pre-authenticated binding) or any OpenAI-compatible client
```

If you record tool calls in history and hand it to LangChain, note the drop: persist
what the framework needs via `append()` with plain roles, or rebuild framework state
from `toOpenAI()` output instead.