ReqAnthropic.Messages (ReqAnthropic v0.2.1)

The Messages API: send prompts to Claude, count tokens, and stream responses as parsed events.

ReqAnthropic.Messages.create(
  model: "claude-haiku-4-5",
  max_tokens: 256,
  messages: [%{role: "user", content: "Hello"}]
)

Streaming returns a Stream of decoded events. Convenience helpers are provided for common patterns:

{:ok, stream} = ReqAnthropic.Messages.stream(model: "...", ...)
stream |> ReqAnthropic.Messages.text_deltas() |> Enum.each(&IO.write/1)

Summary

Functions

collect(stream)

Drain a streamed response into the same shape that create/1 would return, by reassembling content blocks from their deltas.

count_tokens(opts)

Count the tokens that a Messages request would use, without sending it.

create(opts)

Create a non-streaming message.

create!(opts)

Same as create/1, but raises on error.

run(opts)

Send a message and automatically execute any tool calls that have a registered :function (see ReqAnthropic.Tools.custom/1), looping until the model produces a final (non-tool-use) response.

stream(opts)

Stream a message response. Returns {:ok, stream} where stream is a lazy enumerable of decoded SSE events. The stream MUST be consumed in the same process that called stream/1 (a Req requirement of into: :self).

text_deltas(stream)

Stream a message response and yield only text deltas as strings. Useful for piping straight to IO.write/1 or building up a final string.

Functions

collect(stream)

@spec collect(Enumerable.t()) :: {:ok, map()} | {:error, ReqAnthropic.Error.t()}

Drain a streamed response into the same shape that create/1 would return, by reassembling content blocks from their deltas.

count_tokens(opts)

@spec count_tokens(keyword() | map()) ::
  {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Count the tokens that a Messages request would use, without sending it.

create(opts)

@spec create(keyword() | map()) ::
  {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Create a non-streaming message.

All Anthropic Messages parameters are passed through as-is. Pulled out of the keyword for client configuration are: :api_key, :base_url, :anthropic_version, :beta, :req_options.

create!(opts)

@spec create!(keyword() | map()) :: map()

Same as create/1, but raises on error.

run(opts)

@spec run(keyword() | map()) ::
  {:ok, map()} | {:error, ReqAnthropic.Error.t() | Exception.t()}

Send a message and automatically execute any tool calls that have a registered :function (see ReqAnthropic.Tools.custom/1), looping until the model produces a final (non-tool-use) response.

Accepts all the same options as create/1, plus:

:max_rounds — maximum number of tool-use round-trips before returning an error (default: 10).

Tools without a :function that the model tries to call will receive an error tool result so the model can recover gracefully.

Example

alias ReqAnthropic.Tools

tools = [
  Tools.custom(
    name: "get_weather",
    description: "Look up the weather for a city.",
    input_schema: %{
      type: "object",
      properties: %{city: %{type: "string"}},
      required: ["city"]
    },
    function: fn %{"city" => city} ->
      "72°F and sunny in #{city}"
    end
  )
]

{:ok, message} =
  ReqAnthropic.Messages.run(
    model: "claude-sonnet-4-6",
    max_tokens: 1024,
    tools: tools,
    messages: [%{role: "user", content: "What's the weather in Tokyo?"}]
  )

stream(opts)

@spec stream(keyword() | map()) :: {:ok, Enumerable.t()} | {:error, term()}

Stream a message response. Returns {:ok, stream} where stream is a lazy enumerable of decoded SSE events. The stream MUST be consumed in the same process that called stream/1 (a Req requirement of into: :self).

text_deltas(stream)

@spec text_deltas(Enumerable.t()) :: Enumerable.t()

Stream a message response and yield only text deltas as strings. Useful for piping straight to IO.write/1 or building up a final string.