ToolRuntime и Runtime: окружение вызова в инструменте | Курс LangChain урок 10

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

Тот же модуль, что course_model.py уроков 4 и 5, без изменений: у 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 урока 10: конфигурация запуска через context и context_schema.

Один и тот же вопрос от двух разных пользователей. Идентификатора пользователя
нет в схеме для модели, поэтому модель не может его подставить. Он приходит в
агента отдельным аргументом context, а инструмент читает его через runtime.context.
"""

from dataclasses import dataclass

from langchain.agents import create_agent
from langchain.tools import ToolRuntime, tool

from course_model import build_model


@dataclass
class SessionContext:
    """Конфигурация запуска: кто спрашивает и из какого отдела."""

    user_id: str
    department: str


TICKETS = {
    "u-101": ["T-5501 не приходит письмо о доставке", "T-5502 задвоился платёж"],
    "u-202": ["T-6100 не открывается отчёт по продажам"],
}


@tool
def list_my_tickets(runtime: ToolRuntime[SessionContext]) -> str:
    """Вернуть список обращений текущего пользователя."""
    user_id = runtime.context.user_id
    tickets = TICKETS.get(user_id, [])

    if not tickets:
        return "Открытых обращений нет."

    return "\n".join(tickets)


agent = create_agent(
    model=build_model(temperature=0, max_tokens=512),
    tools=[list_my_tickets],
    system_prompt="Вы помощник службы поддержки. Отвечайте по-русски и коротко.",
    context_schema=SessionContext,
)

QUESTION = "Какие у меня открыты обращения?"

for user_id in ("u-101", "u-202"):
    result = agent.invoke(
        {"messages": [{"role": "user", "content": QUESTION}]},
        context=SessionContext(user_id=user_id, department="support"),
    )
    answer = result["messages"][-1].text.replace("\n", " ")
    print(f"ПОЛЬЗОВАТЕЛЬ {user_id}: {answer}")

print()
print("АРГУМЕНТЫ, КОТОРЫЕ ВИДИТ МОДЕЛЬ:", list_my_tickets.args)

# Вывод:
# ПОЛЬЗОВАТЕЛЬ u-101:  Вот ваши открытые обращения:  1. **T-5501** — не приходит письмо о доставке 2. **T-5502** — задвоился платёж  Могу подробнее разобрать любое из них. Что вас интересует?
# ПОЛЬЗОВАТЕЛЬ u-202: У вас открыто одно обращение:  **T-6100** — не открывается отчёт по продажам.  Могу я чем-то ещё помочь?
#
# АРГУМЕНТЫ, КОТОРЫЕ ВИДИТ МОДЕЛЬ: {}

"""Пример 2 урока 10: что из подписи инструмента попадает в схему для модели.

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

from typing import Any

from langchain.tools import ToolRuntime, tool


@tool
def weather_plain(city: str) -> str:
    """Вернуть погоду в городе."""
    return f"В городе {city} ясно."


@tool
def weather_with_runtime(city: str, runtime: ToolRuntime) -> str:
    """Вернуть погоду в городе и номер вызова инструмента."""
    return f"В городе {city} ясно. Вызов {runtime.tool_call_id}."


@tool
def weather_bad_runtime(city: str, runtime: str) -> str:
    """Вернуть погоду в городе с пометкой о режиме работы."""
    return f"В городе {city} ясно. Режим {runtime}."


@tool
def weather_bad_config(city: str, config: dict) -> str:
    """Вернуть погоду в городе с учётом настроек."""
    return f"В городе {city} ясно. Настройки {config}."


def full_schema_fields(some_tool: Any) -> list[str]:
    """Имена полей полной схемы инструмента.

    У инструмента, собранного из функции, args_schema это модель Pydantic.
    Защитная ветка нужна на случай схемы, заданной словарём JSON Schema.
    """
    schema = some_tool.args_schema

    if isinstance(schema, dict):
        return sorted(schema.get("properties", {}))

    return sorted(schema.model_fields)


TOOLS = [
    weather_plain,
    weather_with_runtime,
    weather_bad_runtime,
    weather_bad_config,
]

print(f"{'инструмент':<22} {'полная схема':<34} схема для модели")
for item in TOOLS:
    full = ", ".join(full_schema_fields(item))
    visible = ", ".join(sorted(item.args))
    print(f"{item.name:<22} {full:<34} {visible}")

print()
print("ПОДРОБНО ПРО weather_with_runtime")
print("  тип поля runtime в полной схеме:", weather_with_runtime.args_schema.model_fields["runtime"].annotation)
print("  описание для модели:", weather_with_runtime.description)

# Вывод:
# инструмент             полная схема                       схема для модели
# weather_plain          city                               city
# weather_with_runtime   city, runtime                      city
# weather_bad_runtime    city, runtime                      city, runtime
# weather_bad_config     city, config                       city, config
#
# ПОДРОБНО ПРО weather_with_runtime
#   тип поля runtime в полной схеме: <class 'langgraph.prebuilt.tool_node.ToolRuntime'>
#   описание для модели: Вернуть погоду в городе и номер вызова инструмента.

"""Пример 3 урока 10: инструмент читает состояние разговора.

Инструмент подсчитывает сообщения разговора к моменту вызова и возвращает
сводку. Это короткая память: она существует один запуск агента и обнуляется
вместе с ним.
"""

from collections import Counter

from langchain.agents import create_agent
from langchain.tools import ToolRuntime, tool

from course_model import build_model


@tool
def conversation_summary(runtime: ToolRuntime) -> str:
    """Вернуть сводку по текущему разговору: сколько сообщений и каких."""
    messages = runtime.state["messages"]
    kinds = Counter(type(message).__name__ for message in messages)

    first = messages[0].text.replace("\n", " ") if messages else ""
    if len(first) > 40:
        first = first[:37] + "..."

    parts = ", ".join(f"{name} {count}" for name, count in sorted(kinds.items()))
    return f"Сообщений {len(messages)} ({parts}). Первое: {first!r}"


agent = create_agent(
    model=build_model(temperature=0, max_tokens=512),
    tools=[conversation_summary],
    system_prompt=(
        "Вы помощник по разговору. Про состояние разговора отвечайте только по "
        "данным инструмента, ничего не придумывайте. Отвечайте по-русски и коротко."
    ),
)

DIALOG = [
    {"role": "user", "content": "Здравствуйте, у меня задвоился платёж по заказу 4412."},
    {"role": "assistant", "content": "Здравствуйте. Проверяю списания по заказу 4412."},
    {"role": "user", "content": "Сколько сообщений уже в нашем разговоре?"},
]

result = agent.invoke({"messages": DIALOG})

print("ОТВЕТ:", result["messages"][-1].text.replace("\n", " "))
print()
print("СОСТОЯНИЕ ПОСЛЕ ПРОГОНА")
for number, message in enumerate(result["messages"], start=1):
    text = message.text.replace("\n", " ")
    if len(text) > 50:
        text = text[:47] + "..."
    print(f"  {number}. {type(message).__name__:<14} {text!r}")

# Вывод:
# ОТВЕТ:  В нашем разговоре пока 4 сообщения. По вашему вопросу о задвоенном платеже по заказу 4412 я уже начал проверку — уточните, пожалуйста, какую именно информацию вам нужно получить?
#
# СОСТОЯНИЕ ПОСЛЕ ПРОГОНА
#   1. HumanMessage   'Здравствуйте, у меня задвоился платёж по заказу...'
#   2. AIMessage      'Здравствуйте. Проверяю списания по заказу 4412.'
#   3. HumanMessage   'Сколько сообщений уже в нашем разговоре?'
#   4. AIMessage      ' '
#   5. ToolMessage    'Сообщений 4 (AIMessage 2, HumanMessage 2). Перв...'
#   6. AIMessage      ' В нашем разговоре пока 4 сообщения. По вашему ...'

"""Пример 4 урока 10: инструмент пишет в состояние.

Обычный инструмент возвращает строку, и она становится сообщением для модели.
Этот инструмент возвращает Command с полем update и записывает в состояние,
какой команде передано обращение. Поле escalated_to добавлено в своей схеме
состояния, поэтому после прогона его видно рядом с messages.
"""

from langchain.agents import AgentState, create_agent
from langchain.messages import ToolMessage
from langchain.tools import ToolRuntime, tool
from langgraph.types import Command

from course_model import build_model


class SupportState(AgentState):
    """Состояние агента поддержки: к messages добавлено поле передачи."""

    escalated_to: str


@tool
def escalate(team: str, runtime: ToolRuntime[None, SupportState]) -> Command:
    """Передать обращение другой команде. Название команды на латинице."""
    return Command(
        update={
            "escalated_to": team,
            "messages": [
                ToolMessage(
                    content=f"Обращение передано команде {team}.",
                    tool_call_id=runtime.tool_call_id,
                )
            ],
        }
    )


agent = create_agent(
    model=build_model(temperature=0, max_tokens=512),
    tools=[escalate],
    system_prompt=(
        "Вы первая линия поддержки. Вопросы про деньги и списания передавайте "
        "команде billing, вопросы про доставку команде logistics. Отвечайте "
        "по-русски и коротко."
    ),
    state_schema=SupportState,
)

result = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "С меня дважды списали деньги за заказ 4412."}
        ]
    }
)

print("ОТВЕТ:", result["messages"][-1].text.replace("\n", " "))
print("КЛЮЧИ СОСТОЯНИЯ:", sorted(result))
print("ПОЛЕ escalated_to:", result.get("escalated_to", "<поля нет>"))
print()
print("СООБЩЕНИЯ В СОСТОЯНИИ")
for number, message in enumerate(result["messages"], start=1):
    text = message.text.replace("\n", " ")
    if len(text) > 50:
        text = text[:47] + "..."
    print(f"  {number}. {type(message).__name__:<14} {text!r}")

# Вывод:
# ОТВЕТ:  Ваш вопрос передан команде billing. Они разберутся с двойным списанием по заказу 4412 и свяжутся с вами.
# КЛЮЧИ СОСТОЯНИЯ: ['escalated_to', 'messages']
# ПОЛЕ escalated_to: billing
#
# СООБЩЕНИЯ В СОСТОЯНИИ
#   1. HumanMessage   'С меня дважды списали деньги за заказ 4412.'
#   2. AIMessage      ' Я передам ваш вопрос команде billing, так как ...'
#   3. ToolMessage    'Обращение передано команде billing.'
#   4. AIMessage      ' Ваш вопрос передан команде billing. Они разбер...'

"""Пример 5 урока 10: инструмент читает и пишет долгую память.

Два запуска агента подряд. Сообщения первого запуска во второй не попадают,
а хранилище у них общее, поэтому записанное в первом запуске достаётся во
втором.
"""

from dataclasses import dataclass

from langchain.agents import create_agent
from langchain.tools import ToolRuntime, tool
from langgraph.store.memory import InMemoryStore

from course_model import build_model

NAMESPACE = ("preferences",)


@dataclass
class SessionContext:
    """Конфигурация запуска: кто спрашивает."""

    user_id: str


@tool
def save_preference(preference: str, runtime: ToolRuntime[SessionContext]) -> str:
    """Запомнить пожелание пользователя о том, как ему отвечать."""
    if runtime.store is None:
        return "Хранилище не подключено, запомнить нечем."

    runtime.store.put(NAMESPACE, runtime.context.user_id, {"preference": preference})
    return f"Запомнил: {preference}"


@tool
def get_preference(runtime: ToolRuntime[SessionContext]) -> str:
    """Вернуть ранее сохранённое пожелание пользователя."""
    if runtime.store is None:
        return "Хранилище не подключено, вспомнить нечем."

    item = runtime.store.get(NAMESPACE, runtime.context.user_id)
    if item is None:
        return "Пожеланий не сохранено."

    return item.value["preference"]


store = InMemoryStore()

agent = create_agent(
    model=build_model(temperature=0, max_tokens=512),
    tools=[save_preference, get_preference],
    system_prompt=(
        "Вы помощник. Пожелания пользователя о форме ответа сохраняйте "
        "инструментом и доставайте инструментом, по памяти не отвечайте. "
        "Отвечайте по-русски и коротко."
    ),
    context_schema=SessionContext,
    store=store,
)

context = SessionContext(user_id="u-101")

first = agent.invoke(
    {"messages": [{"role": "user", "content": "Запомните: отвечайте мне без списков."}]},
    context=context,
)
print("ЗАПУСК 1:", first["messages"][-1].text.replace("\n", " "))
print("  сообщений в состоянии:", len(first["messages"]))

second = agent.invoke(
    {"messages": [{"role": "user", "content": "Как я просил вам отвечать?"}]},
    context=context,
)
print("ЗАПУСК 2:", second["messages"][-1].text.replace("\n", " "))
print("  сообщений в состоянии:", len(second["messages"]))

print()
item = store.get(NAMESPACE, "u-101")
print("В ХРАНИЛИЩЕ ПОСЛЕ ДВУХ ЗАПУСКОВ:", item.value if item else "<пусто>")

# Вывод:
# ЗАПУСК 1:  Запомнил. Буду отвечать без списков.
#   сообщений в состоянии: 4
# ЗАПУСК 2: Вы просили отвечать без списков. Учту это в дальнейшем.
#   сообщений в состоянии: 4
#
# В ХРАНИЛИЩЕ ПОСЛЕ ДВУХ ЗАПУСКОВ: {'preference': 'Отвечать без списков'}

"""Пример 6 урока 10: два объекта, Runtime и ToolRuntime, в одном прогоне.

Middleware получает Runtime, инструмент получает ToolRuntime. Конфигурация
запуска, хранилище и запись в поток у них общие, а состояние, объект config,
идентификатор вызова и список инструментов есть только у второго.

Чекпойнтер подключён, как в приложении с памятью сессии, а thread_id передан
в config: из него заполняется поле execution_info.thread_id. Память сессии
разбирается в уроке 12.
"""

from dataclasses import dataclass

from langchain.agents import AgentState, create_agent
from langchain.agents.middleware import before_model
from langchain.tools import ToolRuntime, tool
from langgraph.checkpoint.memory import InMemorySaver
from langgraph.runtime import Runtime

from course_model import build_model


@dataclass
class SessionContext:
    """Конфигурация запуска."""

    user_id: str


@before_model
def show_runtime(state: AgentState, runtime: Runtime[SessionContext]) -> None:
    """Печатает поля Runtime перед вызовом модели."""
    info = runtime.execution_info
    print("MIDDLEWARE, объект Runtime")
    print("  context.user_id:", runtime.context.user_id)
    print("  store:", runtime.store)
    print("  server_info:", runtime.server_info)
    print("  есть ли поле config:", hasattr(runtime, "config"))
    print("  execution_info.thread_id:", info.thread_id if info else None)
    print("  сообщений в состоянии:", len(state["messages"]))
    return None


@tool
def whoami(runtime: ToolRuntime[SessionContext]) -> str:
    """Вернуть идентификатор текущего пользователя."""
    info = runtime.execution_info
    configurable = runtime.config.get("configurable", {})

    print("ИНСТРУМЕНТ, объект ToolRuntime")
    print("  context.user_id:", runtime.context.user_id)
    print("  tool_call_id:", runtime.tool_call_id)
    print("  сообщений в состоянии:", len(runtime.state["messages"]))
    print("  config configurable thread_id:", configurable.get("thread_id"))
    print("  execution_info.thread_id:", info.thread_id if info else None)
    print("  execution_info.node_attempt:", info.node_attempt if info else None)
    print("  инструментов в runtime.tools:", len(runtime.tools))

    return runtime.context.user_id


agent = create_agent(
    model=build_model(temperature=0, max_tokens=512),
    tools=[whoami],
    system_prompt="Вы помощник. Отвечайте по-русски одним предложением.",
    context_schema=SessionContext,
    middleware=[show_runtime],
    checkpointer=InMemorySaver(),
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Под каким идентификатором я вошёл?"}]},
    config={"configurable": {"thread_id": "session-1"}},
    context=SessionContext(user_id="u-101"),
)

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

# Вывод:
# MIDDLEWARE, объект Runtime
#   context.user_id: u-101
#   store: None
#   server_info: None
#   есть ли поле config: False
#   execution_info.thread_id: session-1
#   сообщений в состоянии: 1
# ИНСТРУМЕНТ, объект ToolRuntime
#   context.user_id: u-101
#   tool_call_id: call_06889f8154da40d38e463a3a
#   сообщений в состоянии: 2
#   config configurable thread_id: session-1
#   execution_info.thread_id: session-1
#   execution_info.node_attempt: 1
#   инструментов в runtime.tools: 1
# MIDDLEWARE, объект Runtime
#   context.user_id: u-101
#   store: None
#   server_info: None
#   есть ли поле config: False
#   execution_info.thread_id: session-1
#   сообщений в состоянии: 3
#
# ОТВЕТ: Вы вошли под идентификатором **u-101**.

"""Пример 7 урока 10: старые механизмы внедрения рядом с нынешним.

Два инструмента делают одно и то же. Первый собран по-старому, четырьмя разными
механизмами: InjectedState, InjectedStore, InjectedToolCallId и вызов
get_runtime внутри тела. Второй берёт то же самое из одного параметра
ToolRuntime. Схема для модели у обоих должна быть одинаковой.

Каждый агент получает свой единственный инструмент, иначе выбор между ними
остаётся за моделью и прогон перестаёт быть сравнением.
"""

from dataclasses import dataclass
from typing import Annotated

from langchain.agents import create_agent
from langchain.tools import (
    InjectedState,
    InjectedStore,
    InjectedToolCallId,
    ToolRuntime,
    tool,
)
from langgraph.runtime import get_runtime
from langgraph.store.base import BaseStore
from langgraph.store.memory import InMemoryStore

from course_model import build_model

NAMESPACE = ("plans",)


@dataclass
class SessionContext:
    """Конфигурация запуска."""

    user_id: str


@tool
def old_style_report(
    topic: str,
    state: Annotated[dict, InjectedState],
    store: Annotated[BaseStore, InjectedStore],
    tool_call_id: Annotated[str, InjectedToolCallId],
) -> str:
    """Собрать служебную справку по теме обращения."""
    try:
        user_id = get_runtime(SessionContext).context.user_id
    except Exception as error:  # noqa: BLE001
        # Защитная ветка: get_runtime работает только внутри прогона графа.
        user_id = f"<{type(error).__name__}>"

    item = store.get(NAMESPACE, user_id)
    plan = item.value["plan"] if item else "неизвестен"

    return (
        f"тема={topic} пользователь={user_id} тариф={plan} "
        f"сообщений={len(state['messages'])} вызов={tool_call_id[:8]}"
    )


@tool
def new_style_report(topic: str, runtime: ToolRuntime[SessionContext]) -> str:
    """Собрать служебную справку по теме обращения."""
    user_id = runtime.context.user_id

    item = runtime.store.get(NAMESPACE, user_id) if runtime.store else None
    plan = item.value["plan"] if item else "неизвестен"

    return (
        f"тема={topic} пользователь={user_id} тариф={plan} "
        f"сообщений={len(runtime.state['messages'])} "
        f"вызов={runtime.tool_call_id[:8]}"
    )


store = InMemoryStore()
store.put(NAMESPACE, "u-101", {"plan": "premium"})

QUESTION = "Соберите справку по теме billing."

for report_tool in (old_style_report, new_style_report):
    agent = create_agent(
        model=build_model(temperature=0, max_tokens=512),
        tools=[report_tool],
        system_prompt=(
            "Вы помощник поддержки. Справку собирайте инструментом и возвращайте "
            "пользователю ровно ту строку, которую вернул инструмент, без правок."
        ),
        context_schema=SessionContext,
        store=store,
    )

    print(f"ИНСТРУМЕНТ {report_tool.name}")
    print("  видит модель:", sorted(report_tool.args))

    try:
        result = agent.invoke(
            {"messages": [{"role": "user", "content": QUESTION}]},
            context=SessionContext(user_id="u-101"),
        )
    except Exception as error:  # noqa: BLE001
        # Защитная ветка: прежняя схема могла перестать работать.
        print(f"  ОТКАЗ: {type(error).__name__}: {error}")
        continue

    tool_results = [
        message.text.replace("\n", " ")
        for message in result["messages"]
        if type(message).__name__ == "ToolMessage"
    ]
    print("  вернул инструмент:", tool_results)
    print("  ответ агента:", result["messages"][-1].text.replace("\n", " "))

# Вывод:
# ИНСТРУМЕНТ old_style_report
#   видит модель: ['topic']
#   вернул инструмент: ['тема=billing пользователь=u-101 тариф=premium сообщений=2 вызов=call_8e8']
#   ответ агента: тема=billing пользователь=u-101 тариф=premium сообщений=2 вызов=call_8e8
# ИНСТРУМЕНТ new_style_report
#   видит модель: ['topic']
#   вернул инструмент: ['тема=billing пользователь=u-101 тариф=premium сообщений=2 вызов=call_ba6']
#   ответ агента: тема=billing пользователь=u-101 тариф=premium сообщений=2 вызов=call_ba6

"""Пример 8 урока 10: старый способ, config configurable, рядом с новым.

Один и тот же агент запускается дважды. В первом запуске идентификатор
пользователя приходит аргументом context, во втором тем способом, которым
это делали до версии 1: словарём configurable внутри config. Инструмент
возвращает оба источника одной строкой, поэтому видно, что в каждом запуске
пришло, а что нет.
"""

from dataclasses import dataclass

from langchain.agents import create_agent
from langchain.tools import ToolRuntime, tool

from course_model import build_model


@dataclass
class SessionContext:
    """Конфигурация запуска."""

    user_id: str


@tool
def whoami(runtime: ToolRuntime[SessionContext]) -> str:
    """Вернуть идентификатор текущего пользователя из обоих источников."""
    # Защитная ветка: без аргумента context поле runtime.context равно None.
    from_context = getattr(runtime.context, "user_id", None)
    from_configurable = runtime.config.get("configurable", {}).get("user_id")

    return f"context={from_context} configurable={from_configurable}"


agent = create_agent(
    model=build_model(temperature=0, max_tokens=512),
    tools=[whoami],
    system_prompt=(
        "Вы помощник. Идентификатор пользователя берите инструментом и "
        "возвращайте ровно ту строку, которую он вернул, без правок."
    ),
    context_schema=SessionContext,
)

QUESTION = "Под каким идентификатором я вошёл?"


def run(title, **invoke_kwargs):
    """Один запуск агента со своим способом передачи данных."""
    print(title)
    result = agent.invoke(
        {"messages": [{"role": "user", "content": QUESTION}]}, **invoke_kwargs
    )

    for message in result["messages"]:
        if type(message).__name__ == "ToolMessage":
            print("  инструмент вернул:", message.text.replace("\n", " "))

    print("  ответ агента:", result["messages"][-1].text.replace("\n", " "))


run("ЗАПУСК 1, новый способ: аргумент context", context=SessionContext(user_id="u-101"))
print()
run(
    "ЗАПУСК 2, старый способ: config configurable",
    config={"configurable": {"user_id": "u-303"}},
)

# Вывод:
# ЗАПУСК 1, новый способ: аргумент context
#   инструмент вернул: context=u-101 configurable=None
#   ответ агента:  Вы вошли под идентификатором: `context=u-101 configurable=None`
#
# ЗАПУСК 2, старый способ: config configurable
#   инструмент вернул: context=None configurable=u-303
#   ответ агента:  Вы вошли под идентификатором: **u-303**

# Неправильно: имя занято фреймворком
@tool
def render(template: str, runtime: str) -> str:
    """Отрисовать шаблон в заданном режиме."""
    return f"{template} в режиме {runtime}"

# Правильно: своему аргументу своё имя
@tool
def render(template: str, mode: str) -> str:
    """Отрисовать шаблон в заданном режиме."""
    return f"{template} в режиме {mode}"

# Неправильно: аннотация описывает то, что лежит внутри
@tool
def whoami(runtime: SessionContext) -> str:
    """Вернуть идентификатор пользователя."""
    return runtime.user_id

# Правильно: аннотация описывает окружение, данные достаются из поля
@tool
def whoami(runtime: ToolRuntime[SessionContext]) -> str:
    """Вернуть идентификатор пользователя."""
    return runtime.context.user_id

# Неправильно: поле обновили, а ответа на вызов инструмента нет
@tool
def escalate(team: str, runtime: ToolRuntime[None, SupportState]) -> Command:
    """Передать обращение другой команде."""
    return Command(update={"escalated_to": team})

# Правильно: в обновление кладётся и сообщение с идентификатором вызова
@tool
def escalate(team: str, runtime: ToolRuntime[None, SupportState]) -> Command:
    """Передать обращение другой команде."""
    return Command(
        update={
            "escalated_to": team,
            "messages": [
                ToolMessage(
                    content=f"Обращение передано команде {team}.",
                    tool_call_id=runtime.tool_call_id,
                )
            ],
        }
    )

# Неправильно: агент собран без store, и поле пустое
@tool
def remember(fact: str, runtime: ToolRuntime) -> str:
    """Запомнить факт о пользователе."""
    runtime.store.put(("facts",), "last", {"fact": fact})
    return "Запомнил"

# Правильно
@tool
def remember(fact: str, runtime: ToolRuntime) -> str:
    """Запомнить факт о пользователе."""
    if runtime.store is None:
        return "Хранилище не подключено, запомнить нечем."

    runtime.store.put(("facts",), "last", {"fact": fact})
    return "Запомнил"