# `Alloy.Result`
[🔗](https://github.com/alloy-ex/alloy/blob/v0.10.1/lib/alloy/result.ex#L1)

Structured result from an agent run.

Returned by `Alloy.run/2` and `Alloy.Agent.Server.chat/3`.
Implements `Access` for bracket-syntax compatibility (`result[:text]`).

## Fields

  * `:text` — the final assistant text (or `nil` if the model returned no text)
  * `:messages` — full conversation history
  * `:usage` — accumulated `%Alloy.Usage{}` token counts
  * `:tool_calls` — list of tool execution metadata maps
  * `:metadata` — auxiliary result metadata such as provider-owned state
  * `:status` — final run status (`:completed`, `:max_turns`, `:budget_exceeded`, `:error`, `:halted`)
  * `:turns` — number of agent loop iterations
  * `:error` — error term (or `nil` on success)
  * `:request_id` — correlation ID for async requests (or `nil` for sync)

# `t`

```elixir
@type t() :: %Alloy.Result{
  error: term() | nil,
  messages: [Alloy.Message.t()],
  metadata: map(),
  request_id: binary() | nil,
  status: Alloy.Agent.State.status(),
  text: String.t() | nil,
  tool_calls: [map()],
  turns: non_neg_integer(),
  usage: Alloy.Usage.t()
}
```

# `from_state`

```elixir
@spec from_state(Alloy.Agent.State.t()) :: t()
```

Build a `Result` from a final `State`.

Extracts text, messages, usage, tool calls, status, turns, and error
from the state. The `request_id` is left as `nil` — async callers
overlay it via `%{result | request_id: id}`.

---

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