> ## 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.

# messages

> `protected` `readonly` **messages**: [`MessageLog`](/docs/agent-sdk/interface/messages)

The agent's persistent conversation history.

An append-only, per-instance log ordered by an assigned monotonic `seq`.
See [MessageLog](/docs/agent-sdk/interface/messages) for reads, writes, and the LangChain / OpenAI /
Anthropic adapters.

## add()

> **add**(`role`, `content`): `Promise`\<`number`>

Append a message by role + content — shorthand for
`append({ role, content })`.

**Parameters**

| Parameter | Type |
| - | - |
| `role` | `"system"` \| `"user"` \| `"assistant"` \| `"tool"` |
| `content` | `string` |

**Returns**

`Promise`\<`number`>

The assigned `seq` of the new message.

## append()

> **append**(`msg`): `Promise`\<`number`>

Append one message; atomically assigns and returns its `seq` (the counter
advance and the row write commit together).

Message fields must be storage-codec-safe; a value that cannot be encoded
throws a `CodecError`.

**Parameters**

| Parameter | Type |
| - | - |
| `msg` | [`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage) |

**Returns**

`Promise`\<`number`>

The assigned `seq` of the new message.

## appendMany()

> **appendMany**(`msgs`): `Promise`\<`number`>

Append a batch of messages atomically — all rows commit together.

**Parameters**

| Parameter | Type |
| - | - |
| `msgs` | [`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage)\[] |

**Returns**

`Promise`\<`number`>

The last assigned `seq` (or the current count for an empty
batch).

## all()

> **all**(): `Promise`\<[`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage)\[]>

The full history in chronological order (paginates internally — no length
cap).

Reads the entire history every time; on a long-lived conversation prefer
[`last(n)`](/docs/agent-sdk/interface/messages#last) for a bounded context window.

**Returns**

`Promise`\<[`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage)\[]>

## last()

> **last**(): `Promise`\<[`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage) | `undefined`>

The single most-recent message, or `undefined` on an empty log.

**Returns**

`Promise`\<[`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage) | `undefined`>

**Call Signature**

> **last**(`n`): `Promise`\<[`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage)\[]>

The last `n` messages, in chronological order.

**Parameters**

| Parameter | Type |
| - | - |
| `n` | `number` |

**Returns**

`Promise`\<[`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage)\[]>

## count()

> **count**(): `Promise`\<`number`>

Total messages ever appended — the current `seq` high-water mark. The log
is append-only, so this equals the number of stored messages.

**Returns**

`Promise`\<`number`>

## toOpenAI()

> **toOpenAI**(): `Promise<Array<{ role: string; content: string; name?: string; tool_call_id?: string; tool_calls?: Array<{ id: string; type: "function"; function: { name: string; arguments: string } }> }>>`

The full history as OpenAI Chat Completions messages.

All roles are included. `toolCalls` on assistant turns map to
`tool_calls` (with `args` JSON-stringified into `function.arguments`),
and `toolCallId` maps to `tool_call_id`. The result feeds any
OpenAI-compatible chat-completions endpoint directly.

**Returns**

`Promise`\<`object`\[]>

## toAnthropic()

> **toAnthropic**(): `Promise<Array<{ role: "user" | "assistant"; content: unknown }>>`

The full history as Anthropic Messages-API turns.

`system` messages are **dropped** — the Anthropic API takes the system
prompt as a top-level `system` parameter, so pass it on the request
yourself. Assistant `toolCalls` become `tool_use` content blocks, and
`tool` messages become `user` turns carrying `tool_result` blocks.

**Returns**

`Promise`\<`object`\[]>

## toLangChain()

> **toLangChain**(): `Promise<Array<{ role: "user" | "assistant" | "system"; content: string }>>`

The full history as LangChain / LangGraph messages (accepted by
`agent.invoke({ messages })`).

Only `user` / `assistant` / `system` messages survive — `tool` messages
and `toolCalls` are **dropped**. If your loop needs tool history, persist
it via `append()` with plain roles or rebuild framework state from
[`toOpenAI()`](/docs/agent-sdk/interface/messages#toopenai) output instead.

**Returns**

`Promise`\<`object`\[]>

## new MessageLog()

> **new MessageLog**(`storage`, `onAppend?`): [`MessageLog`](/docs/agent-sdk/interface/messages)

**Parameters**

| Parameter | Type | Description |
| - | - | - |
| `storage` | [`ActorStorage`](/docs/edge-compute/stateful-actors/api-reference/storage) | The actor's persistent storage. |
| `onAppend?` | (`appended`) => `void` | Optional hook fired after each append **commits**, with the stored rows exactly as persisted. The `Agent` base class uses it to push committed appends to connected clients; hook failures propagate to the appending caller. |

**Returns**

[`MessageLog`](/docs/agent-sdk/interface/messages)

## AgentMessage

A framework-neutral chat message. Adapters map this to OpenAI / Anthropic.

**Extended by**

* [`StoredMessage`](/docs/agent-sdk/interface/messages#storedmessage)

**Properties**

**content**

> **content**: `string`

The message text.

***

**name?**

> `optional` **name?**: `string`

Optional author label (tool name for role:"tool", speaker for others).

***

**role**

> **role**: `"system"` | `"user"` | `"assistant"` | `"tool"`

Who authored the message.

***

**toolCallId?**

> `optional` **toolCallId?**: `string`

Present on role:"tool" turns, linking a result back to a ToolCall.id.

***

**toolCalls?**

> `optional` **toolCalls?**: [`ToolCall`](/docs/agent-sdk/interface/messages#toolcall)\[]

Present on assistant turns that request tools.

## ToolCall

A tool-call request emitted by the model (assistant turn).

**Properties**

**args**

> **args**: `unknown`

Arguments for the tool, as the model produced them.

***

**id**

> **id**: `string`

Model-assigned call id; a later `tool` message echoes it as `toolCallId`.

***

**name**

> **name**: `string`

Name of the tool the model wants invoked.

## StoredMessage

An AgentMessage as persisted: assigned a monotonic seq + wall-clock stamp.

**Extends**

* [`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage)

**Properties**

**at**

> **at**: `Date`

Wall-clock stamp at append time; informational only (ordering is by `seq`).

***

**content**

> **content**: `string`

The message text.

**Inherited from**

[`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage).[`content`](/docs/agent-sdk/interface/messages#agentmessage)

***

**name?**

> `optional` **name?**: `string`

Optional author label (tool name for role:"tool", speaker for others).

**Inherited from**

[`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage).[`name`](/docs/agent-sdk/interface/messages#agentmessage)

***

**role**

> **role**: `"system"` | `"user"` | `"assistant"` | `"tool"`

Who authored the message.

**Inherited from**

[`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage).[`role`](/docs/agent-sdk/interface/messages#agentmessage)

***

**seq**

> **seq**: `number`

Monotonic sequence number, assigned on append — the log's order.

***

**toolCallId?**

> `optional` **toolCallId?**: `string`

Present on role:"tool" turns, linking a result back to a ToolCall.id.

**Inherited from**

[`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage).[`toolCallId`](/docs/agent-sdk/interface/messages#agentmessage)

***

**toolCalls?**

> `optional` **toolCalls?**: [`ToolCall`](/docs/agent-sdk/interface/messages#toolcall)\[]

Present on assistant turns that request tools.

**Inherited from**

[`AgentMessage`](/docs/agent-sdk/interface/messages#agentmessage).[`toolCalls`](/docs/agent-sdk/interface/messages#agentmessage)