# `CMDC.Message`
[🔗](https://github.com/tuplehq/cmdc/blob/v0.3.0/lib/cmdc/message.ex#L1)

Agent 会话中的消息结构体。

消息在 Agent Loop 中流转，承载用户、助手和工具执行之间的内容。
每种消息由 `role` 字段区分语义：

- `:system` — 系统级指令（系统提示词、压缩指令等）
- `:user` — 用户发出的文本消息
- `:assistant` — 助手回复，包含文本和可选的工具调用列表
- `:tool_result` — 工具执行结果，通过 `call_id` 与调用关联

每条消息在构建时自动分配唯一 ID。

# `role`

```elixir
@type role() :: :system | :user | :assistant | :tool_result
```

# `t`

```elixir
@type t() :: %CMDC.Message{
  call_id: String.t() | nil,
  content: String.t() | nil,
  id: String.t(),
  is_error: boolean(),
  metadata: map() | nil,
  name: String.t() | nil,
  parent_id: String.t() | nil,
  role: role(),
  thinking: String.t() | nil,
  tool_calls: [tool_call()] | nil
}
```

# `tool_call`

```elixir
@type tool_call() :: %{call_id: String.t(), name: String.t(), arguments: map()}
```

# `assistant`

```elixir
@spec assistant(String.t() | nil, [tool_call()], keyword()) :: t()
```

创建助手消息，可附带工具调用列表。`opts` 支持 `:thinking` 键。

# `system`

```elixir
@spec system(String.t()) :: t()
```

创建系统消息。

# `to_map`

```elixir
@spec to_map(t()) :: map()
```

将消息序列化为普通 map，适合 JSON 编码。可选字段仅在存在时包含。

# `tool_result`

```elixir
@spec tool_result(String.t(), String.t(), boolean()) :: t()
```

创建工具结果消息，`is_error` 标识是否为错误输出。

# `user`

```elixir
@spec user(String.t()) :: t()
```

创建用户消息。

---

*Consult [api-reference.md](api-reference.md) for complete listing*