Модель умеет только писать текст, но агенты отправляют письма, ищут в базах и правят код. Между текстом и действием стоит механизм вызова функций: модель пишет просьбу, программа её проверяет и выполняет, результат возвращается модели. Разберём, как выглядит этот обмен, как описать инструмент, как устроен цикл из нескольких шагов, как ловить ошибки и опасные действия и что такое MCP, о котором постоянно пишут в новостях. Весь код на странице мы запускали, и все выводы — из этих запусков; данные заказов и заметок придуманы для примера.
Все дорожки — /put. Прошлая — как модель режет текст на токены.
Зачем это в работе. Почти каждый агент из новостей — помощник в коде, браузерный агент, бот поддержки — устроен одинаково: языковая модель решает, какое действие сделать, а обычная программа это действие выполняет. Механизм, который их соединяет, называется вызовом функций (function calling, или tool use — использование инструментов). Пока ты его не понимаешь, агент кажется магией, и непонятно, где его чинить, когда он ошибается. Когда понимаешь, видно, что это обычный обмен сообщениями, который можно прочитать, проверить и ограничить.
Главное: модель ничего не выполняет сама. Она умеет только писать текст, токен за токеном, как на прошлой дорожке. Вызов функции — это особый вид ответа: вместо фразы для человека модель пишет структурированную просьбу «вызови функцию с таким именем и такими аргументами». Аргументы — это значения, которые функция получает на вход, например номер заказа. Просьбу получает твоя программа, сама решает, выполнять ли её, выполняет и возвращает результат обратно модели новым сообщением.
По шагам это выглядит так. Первый шаг: ты отправляешь сервису вопрос пользователя и список инструментов — у каждого имя, описание словами и схема аргументов. Второй шаг: модель читает всё это как часть своего входа и решает, ответить сразу или попросить вызов. Если просит, сервис возвращает не текст, а объект вызова с именем функции, аргументами и номером вызова (id). Третий шаг: твой код находит функцию по имени, запускает её и записывает результат в историю переписки с тем же номером. Четвёртый шаг: ты снова отправляешь модели всю историю, и теперь она пишет ответ человеку, опираясь на результат.
Отсюда два ограничения. Первое: модель видит описания инструментов как обычный текст во входе, поэтому они занимают окно контекста и стоят денег при каждом запросе. Десять подробных инструментов могут занять тысячи токенов ещё до вопроса. Второе: модель не знает, что функция на самом деле делает. Она видит только имя и описание, и если описание вводит в заблуждение, модель позовёт не то или не так.
Не путай вызов функций со структурированным ответом, про который была дорожка о формате ответа. Структурированный ответ — это когда модель отдаёт JSON (текст в виде объекта с полями), и на этом всё заканчивается. Вызов функции — это JSON, после которого программа что-то делает и возвращает модели результат, и разговор продолжается. Внутри это одна и та же способность писать объект по схеме, но смысл разный: в первом случае это итог, во втором — шаг цикла.
Подробный пример. Ниже весь обмен для вопроса «Где мой заказ A-102?» в формате Chat Completions — интерфейса OpenAI, который повторяют многие другие сервисы и открытые серверы моделей. Это форма данных, а не запись настоящего запроса: номер вызова call_7f3 и статус заказа придуманы для примера.
# Форма обмена в Chat Completions (OpenAI). Номера вызовов — пример данных.
tools = [{
"type": "function",
"function": {
"name": "get_order_status",
"description": "Узнать статус заказа по номеру вида A-123.",
"parameters": {
"type": "object",
"properties": {"order_id": {"type": "string"}},
"required": ["order_id"],
},
},
}]
# 1) мы отправляем вопрос и список инструментов
messages = [{"role": "user", "content": "Где мой заказ A-102?"}]
# 2) модель отвечает не текстом, а просьбой вызвать функцию
assistant = {"role": "assistant", "content": None, "tool_calls": [{
"id": "call_7f3", "type": "function",
"function": {"name": "get_order_status", "arguments": "{\"order_id\": \"A-102\"}"},
}]}
# 3) НАША программа выполняет функцию и кладёт результат в историю
tool_result = {"role": "tool", "tool_call_id": "call_7f3",
"content": "в пути, ожидается 22.10"}
# 4) мы отправляем модели всю историю ещё раз — теперь она пишет ответ человеку
messages += [assistant, tool_result]
Обрати внимание на три детали. Аргументы во втором сообщении — это строка с JSON внутри, а не готовый объект: твой код должен разобрать её сам, и она может оказаться битой. Результат функции в третьем сообщении — тоже просто текст, модель прочитает его как любой другой текст. Номер call_7f3 связывает просьбу и результат: если вызовов несколько, только по номеру понятно, какой результат к какому вызову. У Anthropic та же идея оформлена иначе: вызов приходит блоком tool_use с аргументами уже в виде объекта, а результат ты возвращаешь блоком tool_result с полем tool_use_id. В более новом интерфейсе OpenAI (Responses) названия полей тоже другие. Механизм один и тот же.
Где обычно ошибаются.
Вызов функций (function calling, tool use). способ, при котором модель пишет просьбу вызвать функцию, а программа её выполняет и возвращает результат.
Инструмент (tool). функция, которую программа разрешила модели просить; у неё есть имя, описание и схема аргументов.
Аргументы. значения, которые функция получает на вход, например номер заказа.
Номер вызова (tool call id). метка, которая связывает просьбу модели и результат, который ты вернул.
Результат инструмента (tool result). сообщение в истории, где лежит то, что вернула функция.
Chat Completions. интерфейс OpenAI для переписки с моделью, формат которого повторяют многие сервисы.
tool_use и tool_result. названия блоков просьбы и результата в интерфейсе Anthropic.
Зачем это в работе. Чаще всего агент ошибается не потому, что модель слабая, а потому, что инструменты описаны плохо: два похожих имени, описание в три слова, аргумент «data» без пояснений. Описание инструмента — это подсказка, которую модель перечитывает на каждом шаге. Хорошо написанные описания и строгая схема убирают большую часть неверных вызовов ещё до того, как ты начнёшь что-то ловить кодом.
Описание инструмента состоит из трёх частей. Имя — короткое, глаголом, без двусмысленности: find_notes понятнее, чем notes. Описание словами — когда вызывать, когда не вызывать и что функция вернёт. Схема аргументов — формальное описание, какие поля бывают, какого они типа и какие обязательны. Схему пишут на языке JSON Schema: это стандартный способ сказать «поле limit — целое число от 1 до 10», «поле folder — одно из трёх слов».
Модель выбирает инструмент так же, как выбирает любое следующее слово: по тому, что написано во входе. Поэтому описание работает как инструкция. Фраза «не вызывай для общих знаний» реально снижает лишние вызовы; перечень допустимых значений (enum) не даёт модели выдумать своё значение. Чем больше инструментов и чем сильнее они похожи друг на друга, тем чаще модель путает их между собой, поэтому лучше пять ясных инструментов, чем двадцать пересекающихся.
Есть настройка, которая решает, обязана ли модель звать инструмент: выбор инструмента (tool_choice). В Chat Completions у неё значения auto (модель решает сама), none (не звать), required (обязательно позвать какой-то) или имя конкретной функции. У Anthropic похожие варианты: auto, any, tool и none. Ещё есть строгий режим (strict): если включить его в описании функции у OpenAI, сервис гарантирует, что аргументы будут точно соответствовать схеме. Цена строгости — правила к схеме: все поля должны быть перечислены как обязательные, а лишние поля запрещены (additionalProperties: false).
Ограничение схемы: она проверяет форму, а не смысл. Схема скажет, что limit — число, но не скажет, что пользователь просил три заметки, а модель передала десять. Схема скажет, что email — строка, но не проверит, что это адрес именно того человека. Смысл проверяется отдельно, на ступени про ошибки.
Подробный пример. Описание инструмента поиска по заметкам и проверка пяти вариантов аргументов, которые модель могла бы прислать. Проверка сделана библиотекой jsonschema (ставится командой pip install jsonschema) — той же схемой, что отдаётся модели. Так ты ловишь неверные аргументы даже без строгого режима сервиса.
import json
from jsonschema import Draft202012Validator
FIND_NOTES = {
"name": "find_notes",
"description": ("Искать в личных заметках пользователя по смыслу. "
"Вызывай, когда вопрос касается его проектов, планов или прошлых записей. "
"Не вызывай для общих знаний. Возвращает до limit заметок с датой."),
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Что искать, своими словами, 3–10 слов"},
"folder": {"type": "string", "enum": ["work", "study", "home"],
"description": "Папка; если неясно — study"},
"limit": {"type": "integer", "minimum": 1, "maximum": 10},
},
"required": ["query", "folder", "limit"],
"additionalProperties": False,
},
}
check = Draft202012Validator(FIND_NOTES["parameters"])
attempts = [
'{"query": "план по RAG", "folder": "study", "limit": 3}',
'{"query": "план по RAG", "folder": "учёба", "limit": 3}',
'{"query": "план по RAG", "limit": "три"}',
'{"query": "план по RAG", "folder": "study", "limit": 3, "sort": "new"}',
'{"query": "план по RAG", "folder": "study", "limit": 3',
]
for raw in attempts:
try:
args = json.loads(raw)
except json.JSONDecodeError as e:
print("НЕ JSON:", e.msg); continue
errors = [e.message for e in check.iter_errors(args)]
print("ок" if not errors else "ОШИБКИ: " + "; ".join(errors))
У нас этот код напечатал пять строк. Первый вариант прошёл. Второй отклонён: модель написала папку по-русски «учёба», а в списке только work, study, home. Третий отклонён сразу по двум причинам: «три» вместо числа и пропущенная папка. Четвёртый отклонён из-за лишнего поля sort, которого в схеме нет. Пятый вообще не разобрался как JSON — не хватает закрывающей скобки. Каждый такой случай без проверки превратился бы либо в падение программы, либо, хуже, в молчаливый вызов с неверными данными.
Где обычно ошибаются.
required в выборе инструмента и удивляются, что модель зовёт функцию даже на «спасибо». Обязательный вызов нужен для конкретного шага, а не для всего разговора.JSON Schema. стандартный язык, которым описывают, какие поля бывают в JSON-объекте и какого они типа.
Обязательные поля (required). список полей, без которых аргументы считаются неверными.
Перечень значений (enum). список допустимых значений поля; всё остальное схема отклонит.
Запрет лишних полей (additionalProperties: false). правило схемы, которое отклоняет поля, не описанные в ней.
Выбор инструмента (tool_choice). настройка запроса: может ли модель звать инструменты, обязана ли, и какой именно.
Строгий режим (strict). настройка OpenAI, при которой сервис гарантирует, что аргументы совпадут со схемой.
jsonschema. библиотека на Python, которая проверяет JSON-объект по схеме и перечисляет ошибки.
Зачем это в работе. Реальная задача редко решается одним вызовом: найти заказ, потом посмотреть доставку, потом посчитать срок. Агент — это цикл «модель просит, программа выполняет, модель читает результат» до тех пор, пока модель не ответит текстом. Этот цикл пишешь ты сам или фреймворк за тебя, и от того, как он устроен, зависят цена, скорость и то, не зациклится ли агент на всю ночь.
По шагам цикл такой. Отправить модели историю. Если в ответе есть вызовы — выполнить каждый, добавить результаты в историю, вернуться к началу. Если вызовов нет — это окончательный ответ, цикл закончен. Каждый круг — это новый полный запрос к модели со всей накопленной историей, поэтому цена растёт быстрее, чем число шагов: на десятом шаге модель заново читает и вопрос, и девять предыдущих результатов. Здесь помогает кэш одинакового начала запроса, о котором была дорожка о цене и скорости.
Модель может попросить несколько вызовов за один ход — это параллельные вызовы (parallel tool calls). Например, узнать статус двух заказов сразу. Твоя программа может выполнить их одновременно, а вернуть надо все результаты, каждый со своим номером вызова. Если какие-то вызовы зависят друг от друга, параллельность мешает; тогда её отключают: в Chat Completions параметром parallel_tool_calls: false, у Anthropic — флагом disable_parallel_tool_use.
Обязательная часть цикла — стоп-кран: предел числа шагов. Модель может зациклиться: звать один и тот же инструмент с теми же аргументами, получать тот же ответ и снова звать. Без предела такой цикл тратит деньги, пока не кончится окно или терпение. Предел ставят по числу кругов, по времени или по сумме потраченных токенов; при остановке агент честно сообщает, что не справился, вместо того чтобы молча выдать недоделанный ответ.
Чем цикл вызовов отличается от «агента» в целом, про которого была дорожка про инструмент. Цикл — это механика: как ходят сообщения. Агент — это цикл плюс правила: какие инструменты дать, что разрешено без человека, как записывается журнал и как проверяется итог.
Подробный пример. Цикл можно запустить без доступа к сервису: вместо настоящей модели стоит заглушка, которая ведёт себя так, как вела бы модель. Первая заглушка за один ход просит два параллельных вызова, вторая зацикливается. Код работает на чистом Python, без библиотек.
import json
ORDERS = {"A-101": "доставлен 18.10", "A-102": "в пути, ожидается 22.10"}
def get_order_status(order_id: str) -> str:
return ORDERS.get(order_id, "заказ не найден")
TOOLS = {"get_order_status": get_order_status}
def fake_model(messages):
"""Заглушка вместо настоящей модели: ведёт себя как модель с вызовом функций."""
last = messages[-1]
if last["role"] == "user":
# модель решила вызвать функцию дважды за один ход (параллельные вызовы)
return {"role": "assistant", "content": None, "tool_calls": [
{"id": "call_1", "type": "function",
"function": {"name": "get_order_status", "arguments": '{"order_id": "A-101"}'}},
{"id": "call_2", "type": "function",
"function": {"name": "get_order_status", "arguments": '{"order_id": "A-102"}'}},
]}
results = {m["tool_call_id"]: m["content"] for m in messages if m["role"] == "tool"}
return {"role": "assistant",
"content": f"A-101: {results['call_1']}; A-102: {results['call_2']}."}
def run(user_text, model=fake_model, max_steps=5):
messages = [{"role": "user", "content": user_text}]
for step in range(1, max_steps + 1):
reply = model(messages)
messages.append(reply)
calls = reply.get("tool_calls") or []
if not calls: # вызовов нет — это окончательный ответ
print(f"шаг {step}: ответ -> {reply['content']}")
return reply["content"]
for c in calls:
args = json.loads(c["function"]["arguments"]) # аргументы приходят строкой JSON
out = TOOLS[c["function"]["name"]](**args)
print(f"шаг {step}: {c['id']} {c['function']['name']}({args}) -> {out}")
messages.append({"role": "tool", "tool_call_id": c["id"], "content": out})
print(f"стоп: лимит {max_steps} шага исчерпан, ответа нет")
return None
run("Где мои заказы A-101 и A-102?")
def stuck_model(messages): # модель, которая зациклилась на одном и том же вызове
return {"role": "assistant", "content": None, "tool_calls": [
{"id": f"call_{len(messages)}", "type": "function",
"function": {"name": "get_order_status", "arguments": '{"order_id": "A-999"}'}}]}
run("Где заказ A-999?", model=stuck_model, max_steps=3)
У нас этот код напечатал вот что. Для первого вопроса: на шаге 1 выполнены два вызова, call_1 вернул «доставлен 18.10», call_2 — «в пути, ожидается 22.10»; на шаге 2 модель ответила текстом, цикл закончился. Для второго вопроса заглушка три раза подряд просила один и тот же заказ A-999 и трижды получала «заказ не найден», после чего сработал предел: «стоп: лимит 3 шага исчерпан, ответа нет». Замени заглушку на настоящий вызов сервиса — и это будет рабочий агент; цикл и стоп-кран останутся теми же.
Где обычно ошибаются.
Цикл агента (agent loop). повторение «запрос к модели — выполнение вызовов — возврат результатов», пока модель не ответит текстом.
Ход (turn). один ответ модели в цикле; в нём может быть текст или один и больше вызовов.
Параллельные вызовы (parallel tool calls). несколько просьб о вызове в одном ходе модели.
Стоп-кран. предел числа шагов, времени или токенов, после которого цикл останавливается.
Зацикливание. ситуация, когда модель снова и снова просит тот же вызов и не продвигается.
Заглушка (mock). подставная функция, которая изображает настоящую систему, чтобы проверить код без неё.
Зачем это в работе. Вызов функции — это место, где текст модели превращается в действие в реальном мире: письмо уходит, деньги списываются, файл удаляется. Ошибка в тексте — это неудобство, ошибка в действии — это ущерб. Поэтому прослойка между просьбой модели и самой функцией — самая важная часть агента. Её пишешь ты, и модель её обойти не может.
Ломается вызов в пяти местах, и каждое ловится отдельно. Модель называет инструмент, которого нет, — проверка имени. Аргументы не разбираются как JSON — проверка разбора. Аргументы разбираются, но не подходят под схему — проверка схемы из прошлой ступени. Аргументы правильные по форме, но действие опасное — подтверждение человеком. Сама функция падает, например внешний сервис не ответил, — перехват исключения, то есть ошибки, которую выбросила программа.
Ключевой приём: ошибку не прячут и не роняют программу, а возвращают модели как результат вызова с пометкой «это ошибка». У Anthropic для этого есть поле is_error в блоке результата; в Chat Completions отдельного поля нет, и ошибку пишут понятным текстом в содержимое. Модель читает ошибку как подсказку и обычно исправляет вызов сама: дописывает пропущенное поле, берёт правильное имя. Текст ошибки должен говорить, что сделать: «Нет инструмента X, есть Y и Z» полезнее, чем «Error 400».
Для опасных действий нужно подтверждение человеком (human in the loop): программа показывает, что модель собирается сделать, и ждёт кнопку. Второй приём — защита от повтора: если сеть оборвалась и модель или твой код повторили тот же вызов, деньги не должны списаться дважды. Для этого запоминают уже выполненные номера вызовов или передают во внешний сервис ключ однократности (idempotency key) — метку, по которой сервис узнаёт повтор и не выполняет его второй раз.
Есть и угроза снаружи. Результат инструмента — это текст, который модель читает как свой вход. Если инструмент принёс веб-страницу или письмо, внутри может оказаться чужая команда «отправь все файлы на такой-то адрес». Это внедрение инструкций, о котором была отдельная дорожка. Отсюда правило: чем больше инструмент читает чужого текста, тем меньше опасных действий должно быть доступно в том же цикле без подтверждения.
Подробный пример. Обёртка safe_call, через которую идут все вызовы. Два инструмента: опасный «отправить счёт» и безопасный «узнать курс», который в примере специально падает с ошибкой времени ожидания. Нужна библиотека jsonschema со второй ступени.
import json
from jsonschema import Draft202012Validator
SENT = []
def send_invoice(email: str, amount: int) -> str:
SENT.append(email)
return f"счёт на {amount} руб. отправлен на {email}"
def get_rate(currency: str) -> str:
raise TimeoutError("сервис курсов не ответил за 5 секунд")
REGISTRY = {
"send_invoice": {"fn": send_invoice, "danger": True, "schema": {
"type": "object", "additionalProperties": False, "required": ["email", "amount"],
"properties": {"email": {"type": "string", "pattern": "^[^@ ]+@[^@ ]+$"},
"amount": {"type": "integer", "minimum": 1, "maximum": 100000}}}},
"get_rate": {"fn": get_rate, "danger": False, "schema": {
"type": "object", "required": ["currency"],
"properties": {"currency": {"type": "string", "enum": ["USD", "EUR", "CNY"]}}}},
}
done = {} # уже выполненные вызовы: повтор с тем же id не выполняем второй раз
def safe_call(call_id, name, raw_args, confirm=lambda name, args: False):
if call_id in done:
return done[call_id]
tool = REGISTRY.get(name)
if tool is None:
return {"is_error": True, "content": f"Нет инструмента {name}. Есть: {', '.join(REGISTRY)}"}
try:
args = json.loads(raw_args)
except json.JSONDecodeError:
return {"is_error": True, "content": "Аргументы не являются JSON. Пришли объект заново."}
errs = [e.message for e in Draft202012Validator(tool["schema"]).iter_errors(args)]
if errs:
return {"is_error": True, "content": "Неверные аргументы: " + "; ".join(errs)}
if tool["danger"] and not confirm(name, args):
return {"is_error": True, "content": "Человек не подтвердил действие. Не повторяй вызов, спроси пользователя."}
try:
result = {"is_error": False, "content": tool["fn"](**args)}
except Exception as e:
result = {"is_error": True, "content": f"{type(e).__name__}: {e}. Можно попробовать позже."}
done[call_id] = result
return result
print(safe_call("c1", "send_invoce", '{}'))
print(safe_call("c2", "send_invoice", '{"email": "roy@example", "amount": 0}'))
print(safe_call("c3", "send_invoice", '{"email": "roy@example.com", "amount": 1500}'))
yes = lambda name, args: True # здесь в настоящей программе — кнопка «Подтвердить»
print(safe_call("c4", "send_invoice", '{"email": "roy@example.com", "amount": 1500}', confirm=yes))
print(safe_call("c4", "send_invoice", '{"email": "roy@example.com", "amount": 1500}', confirm=yes))
print(safe_call("c5", "get_rate", '{"currency": "USD"}'))
print("реально отправлено счетов:", len(SENT))
У нас этот код напечатал по строке на каждый вызов. Опечатка в имени send_invoce вернула ошибку со списком настоящих инструментов. Сумма 0 отклонена схемой. При этом адрес roy@example без точки и домена схему прошёл — шаблон в ней слишком мягкий, и это хороший пример того, что схема ловит форму, а не смысл. Третий вызов с правильными аргументами остановлен, потому что человек не подтвердил. Четвёртый, с подтверждением, отправил счёт. Пятый повторил тот же номер вызова c4 и получил тот же ответ, но функция второй раз не запускалась: последняя строка — «реально отправлено счетов: 1». Падение сервиса курсов превратилось в понятное сообщение для модели, а не в обрыв программы.
Где обычно ошибаются.
safe_call.Прослойка вызовов. твой код между просьбой модели и функцией, который проверяет, подтверждает и перехватывает ошибки.
Исключение (exception). ошибка, которую программа выбрасывает, когда что-то пошло не так, например сервис не ответил.
Пометка ошибки (is_error). поле результата у Anthropic, которое говорит модели, что вызов не удался.
Подтверждение человеком (human in the loop). правило, при котором опасное действие ждёт явного согласия человека.
Ключ однократности (idempotency key). метка вызова, по которой сервис узнаёт повтор и не выполняет действие дважды.
Время ожидания (timeout). предел, сколько программа ждёт ответа внешнего сервиса, прежде чем считать вызов неудачным.
Опасное действие. вызов, который меняет мир и плохо отменяется: отправка, оплата, удаление.
Зачем это в работе. В новостях про агентов постоянно встречается MCP: «вышел MCP-сервер для базы», «редактор поддерживает MCP». Без понимания, что это, непонятно, чем MCP-сервер отличается от функции из прошлых ступеней и почему вокруг него столько разговоров о безопасности. Для работы это важно ещё и практически: один раз написанный MCP-сервер можно подключить к разным программам с моделями без переделки.
MCP (Model Context Protocol, протокол контекста модели) — открытый стандарт, который Anthropic опубликовала в ноябре 2024 года. Он описывает, как программа с моделью находит инструменты и вызывает их, если инструменты живут в отдельной программе. Участников три. Хост — приложение, где работает модель, например редактор кода или чат. Клиент — часть хоста, которая держит связь с одним сервером. Сервер — отдельная программа, которая предлагает инструменты, например «поиск по заметкам» или «запрос к базе».
Общаются они сообщениями в формате JSON-RPC — это простое правило записи «вызови метод с такими параметрами и верни ответ с тем же номером». Клиент спрашивает у сервера список инструментов методом tools/list и получает имена, описания и схемы аргументов — ровно то, что на второй ступени мы писали руками. Когда модель просит вызов, клиент отправляет серверу tools/call с именем и аргументами и получает результат с пометкой ошибки. Кроме инструментов сервер может отдавать ресурсы (данные для чтения, например файлы) и заготовки подсказок. Связь идёт либо через стандартный ввод и вывод (stdio), когда хост запускает сервер у себя на компьютере, либо по сети через HTTP.
Чем MCP отличается от вызова функций. Вызов функций — это договор между моделью и твоей программой: в каком виде модель просит и в каком получает результат. MCP — это договор между твоей программой и внешними инструментами: как их найти и запустить. Модель про MCP ничего не знает. Хост берёт описания у MCP-сервера, превращает их в обычный список инструментов для модели, а просьбу модели пересылает серверу. Цикл, проверки и подтверждения из прошлых ступеней остаются твоей заботой.
Ограничение — доверие. Сервер сам пишет описания своих инструментов, и модель читает их как инструкцию. Сервер из непроверенного источника может положить в описание чужую команду или делать не то, что обещает. В протоколе есть подсказки вроде «инструмент только читает» или «инструмент удаляет» (annotations), но это заявления самого сервера, а не защита. Поэтому подключают серверы из понятных источников, смотрят, какие инструменты они дают, и оставляют подтверждение опасных действий за хостом.
Подробный пример. Самый маленький MCP-сервер на официальной библиотеке для Python (ставится командой pip install mcp). Мы проверяли на версии 2.3.0: в версиях 2.x класс называется MCPServer, а в старых 1.x он назывался FastMCP, и код из старых статей с from mcp.server.fastmcp import FastMCP на новой версии падает с подсказкой о переименовании.
from mcp.server.mcpserver import MCPServer
NOTES = {
"rag": "Поиск по своим файлам: сначала найти куски, потом отвечать по ним.",
"tokens": "Токен — кусок текста из словаря модели.",
}
server = MCPServer("notes")
@server.tool()
def find_note(topic: str) -> str:
"""Вернуть заметку по короткой теме (rag, tokens). Если темы нет — сказать об этом."""
return NOTES.get(topic, f"Заметки на тему '{topic}' нет. Есть: {', '.join(NOTES)}")
if __name__ == "__main__":
server.run() # по умолчанию общается через stdin/stdout
Описание инструмента и схему аргументов библиотека строит сама: из подсказок типов в объявлении функции (topic: str) и из строки описания под ней. Проверить сервер можно, не подключая никакую модель: клиент из той же библиотеки умеет подключаться к серверу прямо внутри одной программы.
import asyncio
from mcp import Client
from mcp_notes import server
async def main():
async with Client(server) as client: # подключение прямо в процессе, для проверки
tools = await client.list_tools()
for t in tools.tools:
print(t.name, "|", t.description)
print(t.input_schema)
res = await client.call_tool("find_note", {"topic": "rag"})
print(res.content[0].text, "| ошибка:", res.is_error)
res = await client.call_tool("find_note", {"topic": "agents"})
print(res.content[0].text, "| ошибка:", res.is_error)
res = await client.call_tool("find_note", {})
print(res.content[0].text[:120], "| ошибка:", res.is_error)
asyncio.run(main())
У нас эта проверка напечатала: инструмент find_note с нашим описанием и схемой {'type': 'object', 'properties': {'topic': {'title': 'Topic', 'type': 'string'}}, 'required': ['topic'], ...}; на тему rag — текст заметки и «ошибка: False»; на тему agents — «Заметки на тему 'agents' нет. Есть: rag, tokens» и тоже «ошибка: False»; на пустые аргументы — сообщение о проверке «Field required» и «ошибка: True». Видно, что сервер сам проверяет аргументы по схеме и возвращает ошибку текстом, как обёртка с прошлой ступени. А «темы нет» — это не ошибка, а нормальный ответ, и формулировать его так, чтобы модель поняла, что делать дальше, — по-прежнему твоя работа.
Где обычно ошибаются.
MCP (Model Context Protocol). открытый стандарт, по которому программа с моделью находит инструменты во внешних программах и вызывает их.
Хост (host). приложение, в котором работает модель и которое подключает MCP-серверы.
MCP-клиент. часть хоста, которая держит связь с одним сервером.
MCP-сервер. отдельная программа, которая предлагает инструменты, ресурсы и заготовки подсказок.
JSON-RPC. простой формат сообщений «вызови метод с параметрами — вот ответ с тем же номером».
tools/list и tools/call. методы MCP: получить список инструментов и вызвать один из них.
stdio. связь через стандартный ввод и вывод, когда хост запускает сервер как программу на том же компьютере.
Подсказки о поведении (annotations). заявления сервера вроде «только читает» или «удаляет», которым нельзя доверять как защите.
Словарь целиком — /slovar, новости — /novosti. Все дорожки — /put.