View Source Anthropic.Messages (anthropic_community v0.5.0)

The Messages resource: create/2 for a single request/response turn, stream/2 for a server-sent-events stream of the same. See Anthropic.ToolRunner for driving a full tool-use agentic loop on top of create/2.

Summary

Types

count_tokens_opts()

create_opts()

Functions

count_tokens(client, opts)

Counts the input tokens a request would use, without sending it for completion. Accepts the same :model/:messages/:system/:tools/:tool_choice options as create/2 (minus :max_tokens, which this endpoint doesn't accept).

create(client, opts)

Sends a single request to the Anthropic Messages API and returns the assistant's reply.

create!(client, opts)

Like create/2, but returns the message directly and raises Anthropic.Error on failure.

stream(client, opts)

Returns a lazy Stream.t() of Anthropic.Messages.StreamEvent.t() structs.

stream_to_message(event_stream)

Consumes the result of stream/2 and folds it into a final Message.t() — analogous to the official SDKs' get_final_message().

Types

count_tokens_opts()

@type count_tokens_opts() :: [
  model: String.t(),
  messages: [map()],
  system: String.t() | [map()] | nil,
  tools: [module() | map()] | nil,
  tool_choice: map() | nil
]

create_opts()

@type create_opts() :: [
  model: String.t(),
  max_tokens: pos_integer(),
  messages: [map()],
  system: String.t() | [map()] | nil,
  tools: [module() | map()] | nil,
  tool_choice: map() | nil,
  thinking: map() | nil,
  output_config: map() | nil,
  temperature: float() | nil,
  top_p: float() | nil,
  top_k: pos_integer() | nil,
  stop_sequences: [String.t()] | nil,
  metadata: map() | nil
]

Functions

count_tokens(client, opts)

@spec count_tokens(Anthropic.Client.t(), count_tokens_opts()) ::
  {:ok, %{input_tokens: non_neg_integer()}} | {:error, Anthropic.Error.t()}

Examples

{:ok, %{input_tokens: 15}} =
  Anthropic.Messages.count_tokens(client,
    model: "claude-opus-4-8",
    messages: [%{role: "user", content: "Hello, Claude"}]
  )

create(client, opts)

@spec create(Anthropic.Client.t(), create_opts()) ::
  {:ok, Anthropic.Messages.Message.t()} | {:error, Anthropic.Error.t()}

Sends a single request to the Anthropic Messages API and returns the assistant's reply.

Examples

client = Anthropic.Client.new(api_key: System.fetch_env!("ANTHROPIC_API_KEY"))

{:ok, message} =
  Anthropic.Messages.create(client,
    model: "claude-opus-4-8",
    max_tokens: 1024,
    messages: [%{role: "user", content: "Hello, Claude"}]
  )

create!(client, opts)

@spec create!(Anthropic.Client.t(), create_opts()) :: Anthropic.Messages.Message.t()

Like create/2, but returns the message directly and raises Anthropic.Error on failure.

stream(client, opts)

@spec stream(Anthropic.Client.t(), create_opts()) :: Enumerable.t()

Returns a lazy Stream.t() of Anthropic.Messages.StreamEvent.t() structs.

Request-setup errors (invalid params) raise immediately, before any stream is returned. Errors that occur once the connection is open (rate limits, connection drops, decode failures) are delivered as a final %Anthropic.Messages.StreamEvent.Error{} element rather than raising mid-Stream, so callers can pattern-match on it without wrapping every iteration in try/rescue.

Examples

client
|> Anthropic.Messages.stream(model: "claude-opus-4-8", max_tokens: 1024,
     messages: [%{role: "user", content: "Write a haiku about Elixir"}])
|> Stream.each(fn
  %Anthropic.Messages.StreamEvent.ContentBlockDelta{delta: %{"type" => "text_delta", "text" => text}} ->
    IO.write(text)

  _other ->
    :ok
end)
|> Stream.run()

stream_to_message(event_stream)

@spec stream_to_message(Enumerable.t()) ::
  {:ok, Anthropic.Messages.Message.t()} | {:error, Anthropic.Error.t()}

Consumes the result of stream/2 and folds it into a final Message.t() — analogous to the official SDKs' get_final_message().

Examples

{:ok, message} =
  client
  |> Anthropic.Messages.stream(model: "claude-opus-4-8", max_tokens: 1024,
       messages: [%{role: "user", content: "Write a haiku about Elixir"}])
  |> Anthropic.Messages.stream_to_message()