Graph node for executing tool calls from AI messages.

Extracts tool_calls from the last %Message.AI{}, dispatches each call to its matching %LangEx.Tool{} in parallel, and returns %Message.Tool{} results.

Control-flow tools

A tool function may return a %LangEx.Command{} instead of a plain value. The command's :update is merged into the graph state (a tool updating active_agent, appending its own messages, etc.) and its :goto joins the node's routing. A %Message.Tool{} correlated by tool_call_id is guaranteed for every call — one is synthesized when the command does not carry it — so the provider always sees a reply for each requested call. When no tool returns a command the node keeps returning a plain %{messages_key => [...]} update.

Usage in a graph

tools = [
  %LangEx.Tool{
    name: "get_weather",
    description: "Get weather for a city",
    parameters: %{...},
    function: fn %{"city" => city} -> %{temp: 22, city: city} end
  }
]

graph =
  Graph.new(messages: {[], &Message.add_messages/2})
  |> Graph.add_node(:agent, ChatModel.node(model: "gpt-4o", tools: tools))
  |> Graph.add_node(:tools, LangEx.Tool.Node.node(tools))
  |> Graph.add_conditional_edges(:agent, &LangEx.Tool.Node.tools_condition/1, %{
    tools: :tools,
    __end__: :__end__
  })
  |> Graph.add_edge(:__start__, :agent)
  |> Graph.add_edge(:tools, :agent)
  |> Graph.compile()

Options

• :messages_key — state key holding the message list (default :messages)
• :handle_tool_errors — error handling strategy (default true):
  • true — catch all errors, return error %Message.Tool{}
  • false — let exceptions propagate
  • String.t() — catch all, return this string as error content
  • (Exception.t() -> String.t()) — custom handler
• :wrap_tool_call — interceptor fn(request, execute) -> result
• :max_concurrency — cap on parallel tool tasks (default System.schedulers_online())
• :timeout — per-tool timeout in ms (default 30_000)