Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 32 ยท Agents and Tools

The Tool-Calling Loop

Understand tool calling in LangChain: bind_tools, AIMessage.tool_calls, ToolMessage and tool_call_id, parallel calls. Run a stand-in message loop in Python.

Underneath every agent is one simple exchange. You send messages and tool schemas to a chat model. The model replies with an AIMessage. If that message contains tool_calls, you run each one and send back a ToolMessage with the result. When the reply has no tool calls, it is the final answer. Understanding this exchange makes agents far less mysterious, and it lets you build a loop by hand when create_agent is more than you need.

The real langchain packages are not available on this site. Real code is read-only; the runnable examples use stand-in message classes and a scripted "model" so you can follow the message flow without a network.

bind_tools and tool_calls

bind_tools attaches tool schemas to a chat model so each request includes them.

Python
# Real LangChain (read-only)
from langchain.chat_models import init_chat_model
from langchain.tools import tool

@tool
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

@tool
def multiply(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b

model = init_chat_model("anthropic:claude-sonnet-4-5")
model_with_tools = model.bind_tools([add, multiply])

ai = model_with_tools.invoke("What is 3 times 4, and what is 10 plus 5?")
print(ai.tool_calls)
# a list of dicts such as {"name": "multiply", "args": {"a": 3, "b": 4}, "id": "call_..."}

ai.tool_calls is a list. Each entry has a name, args and a unique id. Models can return several tool calls in one reply (parallel tool calling), which is common when the sub-questions are independent, as in the example above.

Messages in the loop

A conversation with tools is a list of messages of four kinds:

Message Meaning
SystemMessage Instructions for the model
HumanMessage What the user said
AIMessage The model's reply; may carry tool_calls
ToolMessage A tool's result; carries tool_call_id matching the call

The tool_call_id matters: the provider checks that every tool call has exactly one matching result. If you forget one, the next request fails.

sequenceDiagram
    participant U as You
    participant M as Model
    participant T as Tools
    U->>M: HumanMessage
    M-->>U: AIMessage(tool_calls=[a, b])
    U->>T: run a and b
    T-->>U: results
    U->>M: ToolMessage(a), ToolMessage(b)
    M-->>U: AIMessage(final text)

One round of tool calling with two parallel calls.

The loop by hand

Here is the whole loop written in real LangChain without create_agent.

Python
# Real LangChain (read-only)
from langchain.messages import HumanMessage, ToolMessage

tools = {"add": add, "multiply": multiply}
messages = [HumanMessage("What is 3 times 4, and what is 10 plus 5?")]

for _ in range(6):                       # step limit
    ai = model_with_tools.invoke(messages)
    messages.append(ai)
    if not ai.tool_calls:
        break
    for call in ai.tool_calls:
        result = tools[call["name"]].invoke(call["args"])
        messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))

print(messages[-1].content)

Fifteen lines are all an agent really is. create_agent adds the things you would otherwise write yourself: state management, error handling, streaming, persistence and middleware.

A stand-in message loop

This runnable version uses small dataclasses in place of the LangChain message classes, and a scripted model that issues two parallel calls and then writes a final answer.

Python Stand-in: messages, tool_calls and ToolMessage

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

You can see both calls handled in a single turn and answered with two ToolMessage objects, each carrying the id of the call it belongs to.

Matching results to calls

When several calls arrive together, you must answer each id. A common bug is to collapse the results into one message. The stand-in below checks the pairing rule that providers enforce.

Python Stand-in: check that every call has a result

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Executing calls safely

When you run calls yourself, handle three realities.

  • Unknown tool names. The model can name a tool that does not exist. Return an error ToolMessage, do not raise.
  • Exceptions. Catch them and return the message as the result. The model can often recover.
  • Independent calls can run in parallel, for example with a thread pool or asyncio.gather, which cuts latency when tools are slow network calls.

ToolNode in LangGraph and create_agent do all of this for you, including running parallel calls concurrently.

Forcing or forbidding tools

Most providers let you control tool use: let the model decide (the default), require some tool (tool_choice="any"), require a specific one, or disable tools for one request. Forcing a specific tool is a handy way to get structured output, and requiring any tool is useful for classification-like agents that must always act.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does a ToolMessage need so the provider can match it to a request?

    Each ToolMessage must carry the tool_call_id of the AIMessage tool call it responds to.
  2. 2. What is parallel tool calling?

    One AIMessage can contain multiple independent tool_calls, which you can execute concurrently.
  3. 3. What does bind_tools do?

    bind_tools returns a model that includes the schemas in every request so it can emit tool calls.
  4. 4. The model requests a tool that does not exist. What is best?

    Every call needs a result; an error message lets the model correct itself.

Summary

  • The loop is: model reply, run any tool_calls, append ToolMessage results, repeat until a reply has no tool calls.
  • bind_tools sends schemas; each call has a name, args and id.
  • Every call id needs exactly one matching ToolMessage.
  • Handle unknown tools and exceptions by returning errors; run independent calls in parallel.

Next: ReAct Agents and create_agent