Инструменты и цикл вызова | Курс LangChain урок 9

"""Общая сборка модели для примеров урока 9.

Тот же модуль, что course_model.py уроков 4-8, без изменений: у build_model есть
необязательный первый аргумент с именем модели, а рядом лежит gateway_kwargs()
для примеров, которые собирают модель сами.

Файл .env берётся тот же, что в уроке 0. Положите его рядом с этой папкой или
выше по дереву: load_dotenv() ищет файл начиная с папки этого модуля и поднимается
вверх.
"""

import os

from dotenv import load_dotenv
from langchain.chat_models import init_chat_model

load_dotenv()


def gateway_kwargs():
    """Возвращает аргументы доступа к провайдеру: имя, адрес, ключ.

    Нужны примерам, которые вызывают init_chat_model сами. У настраиваемой модели
    имени модели при создании нет, поэтому build_model ей не подходит.
    """
    base_url = os.getenv("MODEL_BASE_URL")

    if base_url:
        return {
            "model_provider": "openai",
            "base_url": base_url,
            "api_key": os.environ["OPENAI_API_KEY"],
        }

    return {}


def build_model(model_name=None, **kwargs):
    """Собирает модель курса.

    model_name без значения означает модель из переменной MODEL_NAME. Явное имя
    нужно примерам, где моделей в приложении больше одной.

    Все именованные аргументы уходят в init_chat_model как есть: temperature,
    max_tokens, timeout, max_retries, rate_limiter, profile и прочее из раздела
    Parameters.
    """
    model_name = model_name or os.environ["MODEL_NAME"]
    access = gateway_kwargs()

    if access:
        # Путь для любого адреса, совместимого с OpenAI Chat Completions API.
        return init_chat_model(model=model_name, **access, **kwargs)

    # Путь напрямую к провайдеру.
    return init_chat_model(model_name, **kwargs)

"""Пример 1. Что декоратор @tool делает с обычной функцией.

Модель здесь не вызывается. Пример печатает объект инструмента и вызывает его двумя способами.
"""

import json

from langchain.tools import tool


@tool
def get_order_status(order_id: str) -> str:
    """Узнать статус заказа в магазине по его номеру."""
    catalog = {
        "A-1001": "собран, ждёт курьера",
        "A-1002": "в пути, доставка завтра",
        "A-1003": "отменён покупателем",
    }
    return catalog.get(order_id, "заказ с таким номером не найден")


print("ТИП ОБЪЕКТА:", type(get_order_status).__name__)
print("ИМЯ:", get_order_status.name)
print("ОПИСАНИЕ:", get_order_status.description)
print("АРГУМЕНТЫ:", get_order_status.args)

print()
print("СХЕМА, КОТОРУЮ УВИДИТ МОДЕЛЬ:")
schema = get_order_status.tool_call_schema.model_json_schema()
print(json.dumps(schema, ensure_ascii=False, indent=2))

print()
print("ВЫЗОВ СЛОВАРЁМ АРГУМЕНТОВ:")
print(repr(get_order_status.invoke({"order_id": "A-1002"})))

print()
print("ВЫЗОВ ТАК, КАК ЭТО ДЕЛАЕТ АГЕНТ:")
fake_call = {
    "name": "get_order_status",
    "args": {"order_id": "A-1003"},
    "id": "call_demo_1",
    "type": "tool_call",
}
message = get_order_status.invoke(fake_call)
print("тип результата:", type(message).__name__)
print("tool_call_id:", message.tool_call_id)
print("status:", message.status)
print("содержимое:", message.content)

ТИП ОБЪЕКТА: StructuredTool
ИМЯ: get_order_status
ОПИСАНИЕ: Узнать статус заказа в магазине по его номеру.
АРГУМЕНТЫ: {'order_id': {'title': 'Order Id', 'type': 'string'}}

СХЕМА, КОТОРУЮ УВИДИТ МОДЕЛЬ:
{
  "description": "Узнать статус заказа в магазине по его номеру.",
  "properties": {
    "order_id": {
      "title": "Order Id",
      "type": "string"
    }
  },
  "required": [
    "order_id"
  ],
  "title": "get_order_status",
  "type": "object"
}

ВЫЗОВ СЛОВАРЁМ АРГУМЕНТОВ:
'в пути, доставка завтра'

ВЫЗОВ ТАК, КАК ЭТО ДЕЛАЕТ АГЕНТ:
тип результата: ToolMessage
tool_call_id: call_demo_1
status: success
содержимое: отменён покупателем

"""Пример 2. Цикл вызова инструмента, собранный руками.

Показывает, из чего состоит шаг агента: модель возвращает вызов инструмента,
вызов исполняется вручную, результат кладётся обратно в список сообщений.
"""

from course_model import build_model
from langchain.messages import ToolMessage
from langchain.tools import tool


@tool
def get_order_status(order_id: str) -> str:
    """Узнать статус заказа в магазине по его номеру."""
    catalog = {
        "A-1001": "собран, ждёт курьера",
        "A-1002": "в пути, доставка завтра",
        "A-1003": "отменён покупателем",
    }
    return catalog.get(order_id, "заказ с таким номером не найден")


model = build_model(temperature=0)
model_with_tools = model.bind_tools([get_order_status])

messages = [{"role": "user", "content": "Что с заказом A-1002?"}]

# Этап 1. Модель решает, нужен ли инструмент, и возвращает вызов.
ai_message = model_with_tools.invoke(messages)
messages.append(ai_message)

print("ТЕКСТ ПЕРВОГО ОТВЕТА:", repr(ai_message.text))
print("ЗАПРОШЕНО ВЫЗОВОВ:", len(ai_message.tool_calls))
for call in ai_message.tool_calls:
    print(f"  {call['name']} {call['args']} id={call['id']}")

# Этап 2. Инструменты исполняются вручную, ответы собираются в список.
tool_messages = []
for call in ai_message.tool_calls:
    if call["name"] == get_order_status.name:
        tool_messages.append(get_order_status.invoke(call))
    else:
        # Модель может назвать инструмент, которого нет в списке. Ответ нужен и на такой вызов.
        tool_messages.append(
            ToolMessage(
                content=f"инструмента {call['name']} нет",
                tool_call_id=call["id"],
                status="error",
            )
        )

messages.extend(tool_messages)

print()
print("ОТВЕТОВ ИНСТРУМЕНТА:", len(tool_messages))
for message in tool_messages:
    print(f"  id={message.tool_call_id} -> {message.content}")

ids_requested = {call["id"] for call in ai_message.tool_calls}
ids_answered = {message.tool_call_id for message in tool_messages}
print("ВЫЗОВЫ И ОТВЕТЫ СОВПАДАЮТ:", ids_requested == ids_answered)

# Этап 3. Результаты уходят обратно в модель за финальным ответом.
final = model_with_tools.invoke(messages)
messages.append(final)

print()
print("СООБЩЕНИЙ В ИСТОРИИ:", len(messages))
print("ТИПЫ:", [type(m).__name__ if hasattr(m, "type") else "dict" for m in messages])
print("ФИНАЛЬНЫЙ ОТВЕТ:", final.text)

ТЕКСТ ПЕРВОГО ОТВЕТА: ''
ЗАПРОШЕНО ВЫЗОВОВ: 1
  get_order_status {'order_id': 'A-1002'} id=call_d0b5ebc81a39492db0f8dc8f

ОТВЕТОВ ИНСТРУМЕНТА: 1
  id=call_d0b5ebc81a39492db0f8dc8f -> в пути, доставка завтра
ВЫЗОВЫ И ОТВЕТЫ СОВПАДАЮТ: True

СООБЩЕНИЙ В ИСТОРИИ: 4
ТИПЫ: ['dict', 'AIMessage', 'ToolMessage', 'AIMessage']
ФИНАЛЬНЫЙ ОТВЕТ: Заказ **A-1002** находится **в пути**, доставка ожидается **завтра**. 🚚

"""Пример 3. Тот же цикл, его выполняет агент.

Инструмент и вопрос те же, что в примере 2. Разница в том, что этапы 1-3
здесь не написаны: их делает create_agent.
"""

from course_model import build_model
from langchain.agents import create_agent
from langchain.tools import tool


@tool
def get_order_status(order_id: str) -> str:
    """Узнать статус заказа в магазине по его номеру."""
    catalog = {
        "A-1001": "собран, ждёт курьера",
        "A-1002": "в пути, доставка завтра",
        "A-1003": "отменён покупателем",
    }
    return catalog.get(order_id, "заказ с таким номером не найден")


agent = create_agent(
    model=build_model(temperature=0),
    tools=[get_order_status],
    system_prompt="Вы отвечаете на вопросы о заказах. Номер заказа берите из вопроса.",
)

result = agent.invoke({"messages": [{"role": "user", "content": "Что с заказом A-1002?"}]})

print("СООБЩЕНИЙ В СОСТОЯНИИ:", len(result["messages"]))
for number, message in enumerate(result["messages"], start=1):
    kind = type(message).__name__
    if kind == "AIMessage" and message.tool_calls:
        detail = "просит вызвать: " + ", ".join(
            f"{call['name']}({call['args']})" for call in message.tool_calls
        )
    elif kind == "ToolMessage":
        detail = f"{message.name} -> {message.content}"
    else:
        detail = message.text
    print(f"{number}. {kind}: {detail}")

print()
print("ОТВЕТ ПОЛЬЗОВАТЕЛЮ:", result["messages"][-1].text)

СООБЩЕНИЙ В СОСТОЯНИИ: 4
1. HumanMessage: Что с заказом A-1002?
2. AIMessage: просит вызвать: get_order_status({'order_id': 'A-1002'})
3. ToolMessage: get_order_status -> в пути, доставка завтра
4. AIMessage: Статус заказа **A-1002**: заказ **в пути**, доставка ожидается **завтра**. 🚚📦

ОТВЕТ ПОЛЬЗОВАТЕЛЮ: Статус заказа **A-1002**: заказ **в пути**, доставка ожидается **завтра**. 🚚📦

"""Пример 4. Docstring это часть промпта: четыре варианта одного инструмента.

Модель здесь не вызывается. Пример печатает то, что уйдёт в модель вместе с запросом:
описание инструмента и схему его аргументов.
"""

from langchain.tools import tool


@tool
def search_orders_v1(query: str, limit: int = 5) -> str:
    """Поиск заказов."""
    return f"{limit} заказов по запросу {query}"


@tool
def search_orders_v2(query: str, limit: int = 5) -> str:
    """Найти заказы покупателя по строке поиска.

    Args:
        query: номер заказа, имя покупателя или название товара
        limit: сколько заказов вернуть, по умолчанию 5
    """
    return f"{limit} заказов по запросу {query}"


@tool(parse_docstring=True)
def search_orders_v3(query: str, limit: int = 5) -> str:
    """Найти заказы покупателя по строке поиска.

    Args:
        query: номер заказа, имя покупателя или название товара
        limit: сколько заказов вернуть, по умолчанию 5
    """
    return f"{limit} заказов по запросу {query}"


@tool(
    "order_search",
    description="Искать заказы. Вызывайте, только когда в вопросе есть номер заказа.",
)
def search_orders_v4(query: str, limit: int = 5) -> str:
    """Этот текст в модель не уйдёт: description его перекрывает."""
    return f"{limit} заказов по запросу {query}"


def show(title, tool_object):
    print("=" * 70)
    print(title)
    print("имя:", tool_object.name)
    print("описание:", repr(tool_object.description))
    schema = tool_object.tool_call_schema.model_json_schema()
    print("описания аргументов:")
    for name, field in schema["properties"].items():
        print(f"  {name}: {field.get('description', '<нет>')}")
    print()


show("1. Короткий docstring", search_orders_v1)
show("2. Docstring с блоком Args, parse_docstring не задан", search_orders_v2)
show("3. То же самое с parse_docstring=True", search_orders_v3)
show("4. Своё имя и своё описание в декораторе", search_orders_v4)

======================================================================
1. Короткий docstring
имя: search_orders_v1
описание: 'Поиск заказов.'
описания аргументов:
  query: <нет>
  limit: <нет>

======================================================================
2. Docstring с блоком Args, parse_docstring не задан
имя: search_orders_v2
описание: 'Найти заказы покупателя по строке поиска.

    Args:
        query: номер заказа, имя покупателя или название товара
        limit: сколько заказов вернуть, по умолчанию 5'
описания аргументов:
  query: <нет>
  limit: <нет>

======================================================================
3. То же самое с parse_docstring=True
имя: search_orders_v3
описание: 'Найти заказы покупателя по строке поиска.'
описания аргументов:
  query: номер заказа, имя покупателя или название товара
  limit: сколько заказов вернуть, по умолчанию 5

======================================================================
4. Своё имя и своё описание в декораторе
имя: order_search
описание: 'Искать заказы. Вызывайте, только когда в вопросе есть номер заказа.'
описания аргументов:
  query: <нет>
  limit: <нет>

"""Пример 5. Схема аргументов на Pydantic вместо аннотаций.

Схема добавляет к подписи функции описание каждого поля,
закрытый список допустимых значений и границы чисел.
"""

import json
from typing import Literal

from course_model import build_model
from langchain.agents import create_agent
from langchain.tools import tool
from pydantic import BaseModel, Field

ORDERS = [
    {"id": "A-1001", "customer": "Иванов", "status": "shipped", "sum": 4300},
    {"id": "A-1002", "customer": "Иванов", "status": "new", "sum": 1200},
    {"id": "A-1003", "customer": "Петрова", "status": "cancelled", "sum": 890},
    {"id": "A-1004", "customer": "Иванов", "status": "shipped", "sum": 15600},
]


class OrderSearch(BaseModel):
    """Параметры поиска по журналу заказов."""

    customer: str = Field(description="Фамилия покупателя ровно так, как в вопросе")
    status: Literal["new", "shipped", "cancelled"] = Field(
        default="new",
        description="Статус заказа: new это новый, shipped это отправлен, "
        "cancelled это отменён",
    )
    limit: int = Field(default=5, ge=1, le=50, description="Сколько заказов вернуть")


@tool(args_schema=OrderSearch)
def search_orders(customer: str, status: str = "new", limit: int = 5) -> str:
    """Найти заказы покупателя с указанным статусом."""
    found = [o for o in ORDERS if o["customer"] == customer and o["status"] == status]
    if not found:
        return "ничего не найдено"
    return "; ".join(f"{o['id']} на {o['sum']} рублей" for o in found[:limit])


print("СХЕМА, КОТОРУЮ УВИДИТ МОДЕЛЬ:")
print(json.dumps(search_orders.tool_call_schema.model_json_schema(), ensure_ascii=False, indent=2))

agent = create_agent(
    model=build_model(temperature=0),
    tools=[search_orders],
    system_prompt="Вы помощник менеджера магазина. Отвечайте одним предложением.",
)

question = "Какие отправленные заказы есть у Иванова?"
result = agent.invoke({"messages": [{"role": "user", "content": question}]})

print()
print("ВОПРОС:", question)
for message in result["messages"]:
    if type(message).__name__ == "AIMessage" and message.tool_calls:
        for call in message.tool_calls:
            print("МОДЕЛЬ ПРИСЛАЛА АРГУМЕНТЫ:", call["args"])
    if type(message).__name__ == "ToolMessage":
        print("ИНСТРУМЕНТ ВЕРНУЛ:", message.content)

print("ОТВЕТ:", result["messages"][-1].text)

СХЕМА, КОТОРУЮ УВИДИТ МОДЕЛЬ:
{
  "description": "Найти заказы покупателя с указанным статусом.",
  "properties": {
    "customer": {
      "description": "Фамилия покупателя ровно так, как в вопросе",
      "title": "Customer",
      "type": "string"
    },
    "status": {
      "default": "new",
      "description": "Статус заказа: new это новый, shipped это отправлен, cancelled это отменён",
      "enum": [
        "new",
        "shipped",
        "cancelled"
      ],
      "title": "Status",
      "type": "string"
    },
    "limit": {
      "default": 5,
      "description": "Сколько заказов вернуть",
      "maximum": 50,
      "minimum": 1,
      "title": "Limit",
      "type": "integer"
    }
  },
  "required": [
    "customer"
  ],
  "title": "search_orders",
  "type": "object"
}

ВОПРОС: Какие отправленные заказы есть у Иванова?
МОДЕЛЬ ПРИСЛАЛА АРГУМЕНТЫ: {'customer': 'Иванов', 'status': 'shipped'}
ИНСТРУМЕНТ ВЕРНУЛ: A-1001 на 4300 рублей; A-1004 на 15600 рублей
ОТВЕТ: У Иванова есть два отправленных заказа: A-1001 на 4300 рублей и A-1004 на 15600 рублей.

"""Пример 6. Что происходит, когда инструмент падает.

Две сборки одного агента с одним и тем же ломающимся инструментом.
Первая, без обработки: исключение выходит наружу из agent.invoke.
Вторая, с middleware wrap_tool_call: исключение превращается
в ToolMessage, и агент доходит до ответа.
"""

from collections.abc import Callable

from course_model import build_model
from langchain.agents import create_agent
from langchain.agents.middleware import wrap_tool_call
from langchain.messages import ToolMessage
from langchain.tools import tool
from langchain.tools.tool_node import ToolCallRequest


@tool
def get_balance(account: str) -> str:
    """Узнать остаток на счёте по его номеру."""
    if account != "40817":
        # Внешняя система отвечает отказом. В рабочем приложении это был бы
        # таймаут базы, 500 от API или отсутствующая запись.
        raise ValueError(f"счёт {account} не найден в реестре")
    return "остаток 12 400 рублей"


QUESTION = "Сколько денег на счёте 99999?"
SYSTEM = "Вы банковский помощник. Остаток узнавайте только инструментом."


def build_agent(middleware):
    return create_agent(
        model=build_model(temperature=0),
        tools=[get_balance],
        system_prompt=SYSTEM,
        middleware=middleware,
    )


print("СБОРКА 1: без обработки ошибок")
try:
    result = build_agent([]).invoke({"messages": [{"role": "user", "content": QUESTION}]})
    print("агент дошёл до ответа:", result["messages"][-1].text)
except Exception as error:
    print("agent.invoke упал:", type(error).__name__)
    print("текст:", error)

print()


@wrap_tool_call
def handle_tool_errors(
    request: ToolCallRequest,
    handler: Callable[[ToolCallRequest], ToolMessage],
) -> ToolMessage:
    """Превращает исключение инструмента в сообщение, понятное модели."""
    try:
        return handler(request)
    except Exception as error:
        return ToolMessage(
            content=f"Инструмент не отработал: {error}. Не повторяйте вызов, "
            "скажите пользователю, что счёт не найден.",
            tool_call_id=request.tool_call["id"],
            name=request.tool_call["name"],
            status="error",
        )


print("СБОРКА 2: то же самое с middleware wrap_tool_call")
result = build_agent([handle_tool_errors]).invoke(
    {"messages": [{"role": "user", "content": QUESTION}]}
)

for message in result["messages"]:
    kind = type(message).__name__
    if kind == "ToolMessage":
        print(f"ToolMessage status={message.status}: {message.content}")
    elif kind == "AIMessage" and message.tool_calls:
        print("AIMessage просит:", [c["args"] for c in message.tool_calls])

print("ОТВЕТ ПОЛЬЗОВАТЕЛЮ:", result["messages"][-1].text)

СБОРКА 1: без обработки ошибок
agent.invoke упал: ValueError
текст: счёт 99999 не найден в реестре

СБОРКА 2: то же самое с middleware wrap_tool_call
AIMessage просит: [{'account': '99999'}]
ToolMessage status=error: Инструмент не отработал: счёт 99999 не найден в реестре. Не повторяйте вызов, скажите пользователю, что счёт не найден.
ОТВЕТ ПОЛЬЗОВАТЕЛЮ: Извините, счёт с номером **99999** не найден в нашем реестре. Проверьте, пожалуйста, правильность номера счёта, и попробуйте снова.

"""Пример 7. Несколько вызовов инструмента на одном шаге идут одновременно.

Инструмент спит секунду. Пример печатает, сколько вызовов модель
запросила на одном шаге и сколько времени заняло их исполнение.
"""

import threading
import time

from course_model import build_model
from langchain.agents import create_agent
from langchain.tools import tool

LOG = []
LOCK = threading.Lock()
START = time.perf_counter()


@tool
def check_stock(city: str) -> str:
    """Узнать остаток товара на складе города. Запрос идёт около секунды."""
    began = time.perf_counter() - START
    time.sleep(1.0)
    ended = time.perf_counter() - START
    with LOCK:
        LOG.append((city, began, ended, threading.current_thread().name))
    return f"на складе {city} осталось 7 штук"


agent = create_agent(
    model=build_model(temperature=0),
    tools=[check_stock],
    system_prompt=(
        "Вы отвечаете про остатки на складах. Если в вопросе несколько городов, "
        "запросите все города сразу, одним ответом."
    ),
)

question = "Сколько товара на складах в Казани, Самаре и Перми?"


def run(title, config=None):
    LOG.clear()
    began = time.perf_counter()
    result = agent.invoke({"messages": [{"role": "user", "content": question}]}, config=config)
    spent = time.perf_counter() - began

    calls_per_turn = [
        len(m.tool_calls)
        for m in result["messages"]
        if type(m).__name__ == "AIMessage" and m.tool_calls
    ]
    print(title)
    print("  шагов с вызовами:", len(calls_per_turn), "вызовов по шагам:", calls_per_turn)
    print("  всего исполнений инструмента:", len(LOG))
    print(f"  время всего прогона: {spent:.2f} с")
    for city, start_at, end_at, thread_name in sorted(LOG, key=lambda row: row[1]):
        print(f"  {city}: {start_at:.2f} -> {end_at:.2f} ({thread_name})")
    print()


run("ПРОГОН 1: как есть")
run("ПРОГОН 2: max_concurrency=1", config={"max_concurrency": 1})

ПРОГОН 1: как есть
  шагов с вызовами: 1 вызовов по шагам: [3]
  всего исполнений инструмента: 3
  время всего прогона: 5.48 с
  Казань: 4.13 -> 5.13 (ThreadPoolExecutor-2_0)
  Самара: 4.13 -> 5.13 (ThreadPoolExecutor-3_0)
  Пермь: 4.13 -> 5.13 (ThreadPoolExecutor-4_0)

ПРОГОН 2: max_concurrency=1
  шагов с вызовами: 1 вызовов по шагам: [3]
  всего исполнений инструмента: 3
  время всего прогона: 7.23 с
  Казань: 9.08 -> 10.08 (ThreadPoolExecutor-6_0)
  Самара: 10.08 -> 11.08 (ThreadPoolExecutor-7_0)
  Пермь: 11.08 -> 12.08 (ThreadPoolExecutor-8_0)

"""Пример 8. return_direct: выход из цикла сразу после инструмента.

Два прогона. В первом единственный инструмент помечен return_direct=True,
и агент отдаёт его вывод как есть. Во втором в системном промпте указано
вызвать оба инструмента на одном шаге. Если модель так и сделает, выход
сразу не срабатывает.
"""

from course_model import build_model
from langchain.agents import create_agent
from langchain.tools import tool

PAYMENT_LINK = "https://pay.example.com/invoice/A-1002?sum=1200"


@tool(return_direct=True)
def create_payment_link(order_id: str) -> str:
    """Выдать ссылку на оплату заказа. Ответ показывается пользователю дословно."""
    return f"Ссылка на оплату заказа {order_id}: {PAYMENT_LINK}"


@tool
def get_order_sum(order_id: str) -> str:
    """Узнать сумму заказа в рублях."""
    return "1200"


def report(title, agent, question):
    result = agent.invoke({"messages": [{"role": "user", "content": question}]})
    messages = result["messages"]
    print(title)
    print("  типы сообщений:", [type(m).__name__ for m in messages])
    print("  вызовов модели:", sum(1 for m in messages if type(m).__name__ == "AIMessage"))
    last = messages[-1]
    print("  последнее сообщение:", type(last).__name__)
    print("  его содержимое:", last.content)
    print()


report(
    "ПРОГОН 1: один инструмент с return_direct=True",
    create_agent(
        model=build_model(temperature=0),
        tools=[create_payment_link],
        system_prompt="Вы помощник магазина. Ссылку на оплату выдавайте инструментом.",
    ),
    "Дайте ссылку на оплату заказа A-1002.",
)

report(
    "ПРОГОН 2: рядом обычный инструмент, вызваны оба",
    create_agent(
        model=build_model(temperature=0),
        tools=[create_payment_link, get_order_sum],
        system_prompt=(
            "Вы помощник магазина. Когда просят ссылку на оплату, сначала одним ответом "
            "вызовите оба инструмента: сумму заказа и ссылку на оплату."
        ),
    ),
    "Дайте ссылку на оплату заказа A-1002 и скажите его сумму.",
)

ПРОГОН 1: один инструмент с return_direct=True
  типы сообщений: ['HumanMessage', 'AIMessage', 'ToolMessage']
  вызовов модели: 1
  последнее сообщение: ToolMessage
  его содержимое: Ссылка на оплату заказа A-1002: https://pay.example.com/invoice/A-1002?sum=1200

ПРОГОН 2: рядом обычный инструмент, вызваны оба
  типы сообщений: ['HumanMessage', 'AIMessage', 'ToolMessage', 'ToolMessage', 'AIMessage']
  вызовов модели: 2
  последнее сообщение: AIMessage
  его содержимое: Вот информация по заказу **A-1002**:

- 💰 **Сумма заказа:** 1 200 рублей
- 🔗 **Ссылка на оплату:** [https://pay.example.com/invoice/A-1002?sum=1200](https://pay.example.com/invoice/A-1002?sum=1200)

Если понадобится ещё что-то, обращайтесь! 😊

# Неправильно: в схеме нет типа аргумента
@tool
def get_order_status(order_id):
    """Узнать статус заказа."""
    return "..."

# Правильно
@tool
def get_order_status(order_id: str) -> str:
    """Узнать статус заказа."""
    return "..."

# Неправильно: свой идентификатор вместо идентификатора вызова
return ToolMessage(content="ошибка сервиса", tool_call_id="error-1")

# Правильно
return ToolMessage(content="ошибка сервиса", tool_call_id=request.tool_call["id"])

# Неправильно: агент собран без обработки, инструмент обращается к сети
agent = create_agent(model=model, tools=[fetch_from_partner])

# Правильно: отказ внешнего сервиса становится сообщением для модели
agent = create_agent(model=model, tools=[fetch_from_partner], middleware=[handle_tool_errors])

# Неправильно: три вызова одного шага одновременно меняют счётчик
CALLS = 0

@tool
def check_stock(city: str) -> str:
    """Остаток на складе."""
    global CALLS
    CALLS += 1
    return "..."

# Правильно: изменение общего состояния под блокировкой
LOCK = threading.Lock()

@tool
def check_stock(city: str) -> str:
    """Остаток на складе."""
    global CALLS
    with LOCK:
        CALLS += 1
    return "..."