LangChain.Message.ToolCall (LangChain v0.9.2)

Represents an LLM's request to use tool. It specifies the tool to execute and may provide arguments for the tool to use.

Example

ToolCall.new!(%{
  call_id: "call_123",
  name: "give_greeting"
  arguments: %{"name" => "Howard"}
})

Summary

Functions

arguments_as_map(tool_call)

Return the tool call's arguments as a map, suitable for serializing to a provider API that expects a JSON object.

complete(tool_call)

Ensure the ToolCall's status is set to :complete. The process of completing it parses the tool arguments, which may be invalid. Any problems parsing are returned as a changeset error.

execution_status(tool_call, default \\ "identified")

Get the execution status from a ToolCall's metadata.

merge(primary, call_part)

The left side, or primary, is the ToolCall that is being accumulated. The call_part is being merged into the primary.

new(attrs \\ %{})

Build a new ToolCall and return an :ok/:error tuple with the result.

new!(attrs \\ %{})

Build a new ToolCall and return it or raise an error if invalid.

set_execution_status(tool_call, status)

Set the execution status on a ToolCall's metadata.

Types

t()

@type t() :: %LangChain.Message.ToolCall{
  arguments: term(),
  call_id: term(),
  display_text: term(),
  index: term(),
  metadata: term(),
  name: term(),
  status: term(),
  type: term()
}

Functions

arguments_as_map(tool_call)

@spec arguments_as_map(t()) :: map()

Return the tool call's arguments as a map, suitable for serializing to a provider API that expects a JSON object.

arguments are only parsed from a JSON string into a map by complete/1 (via validate_and_parse_arguments/1), which runs when a tool call reaches status: :complete. A tool call that is serialized without going through that path (e.g. a persisted/replayed :incomplete call, or one accumulated from a truncated stream) can still hold a raw string. Passing that string to a provider results in an API error like Anthropic's "Input should be an object".

This normalizes any shape into a map:

a map is returned unchanged
a JSON-object string is decoded
nil, an empty string, and undecodable/non-object strings become %{}

Examples

iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: %{"a" => 1}})
%{"a" => 1}

iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: ~s({"a":1})})
%{"a" => 1}

iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: ""})
%{}

iex> LangChain.Message.ToolCall.arguments_as_map(%LangChain.Message.ToolCall{arguments: nil})
%{}

complete(tool_call)

@spec complete(t()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

Ensure the ToolCall's status is set to :complete. The process of completing it parses the tool arguments, which may be invalid. Any problems parsing are returned as a changeset error.

execution_status(tool_call, default \\ "identified")

@spec execution_status(t(), String.t()) :: String.t()

Get the execution status from a ToolCall's metadata.

Returns the status string ("identified", "executing", "completed", "failed") or the default value if not set.

merge(primary, call_part)

@spec merge(nil | t(), t()) :: t()

The left side, or primary, is the ToolCall that is being accumulated. The call_part is being merged into the primary.

Used to process streamed deltas where a single tool call can be split over many smaller parts.

new(attrs \\ %{})

@spec new(attrs :: map()) :: {:ok, t()} | {:error, Ecto.Changeset.t()}

Build a new ToolCall and return an :ok/:error tuple with the result.

new!(attrs \\ %{})

@spec new!(attrs :: map()) :: t() | no_return()

Build a new ToolCall and return it or raise an error if invalid.

set_execution_status(tool_call, status)

@spec set_execution_status(t(), String.t()) :: t()

Set the execution status on a ToolCall's metadata.