AI-агенты

01Идея: модель в цикле с tools

Чат-бот отвечает один раз. Агент работает как джун, которому дали цель и набор инструментов: думает о следующем шаге, использует tool, смотрит на результат и продолжает, пока не закончит или не застрянет. Технически это tool-use API в цикле. Вы отправляете цель и определения tools; модель отвечает вызовом tool; ваш код выполняет его и возвращает результат; повторяете, пока модель не завершит ход. «Планирование» — это в основном рассуждения модели между шагами, иногда им помогает просьба сначала написать план или to-do список. Качество агента зависит от четырёх вещей: модели, tools, которые вы ей даёте, контекста, который она видит, и guardrails вокруг неё. Совет Anthropic стоит повторить: начинайте с самого простого решения и добавляйте агентную сложность, только когда она явно улучшает результат.

• Workflow: шаги определяет ваш код; LLM заполняет отдельные части
• Agent: шаги определяет LLM; ваш код предоставляет tools и ограничения
• Большинство продакшен-систем сочетают оба подхода

02Минимальный цикл агента

Вот базовый цикл на Claude Messages API в TypeScript. Он продолжает вызывать модель, пока та просит tools, выполняет каждый запрошенный tool и возвращает все результаты в одном user-сообщении. Важные детали: максимальное число шагов, чтобы запутавшийся агент не крутился вечно; ошибки возвращаются модели как tool result с is_error, чтобы она могла адаптироваться, а не падать; в историю добавляется весь content каждого ответа assistant, а не только текст. В реальных проектах можно использовать хелпер tool runner из SDK (он сам крутит этот цикл), Claude Agent SDK (обвязку Claude Code в виде библиотеки со встроенными tools для файлов, shell и веба) или хостинговые варианты вроде Claude Managed Agents. В других экосистемах есть похожие SDK; цикл под капотом тот же.

1const messages: Anthropic.MessageParam[] = [{ role: "user", content: goal }];
2for (let step = 0; step < 20; step++) {
3  const res = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 8000, tools, messages });
4  messages.push({ role: "assistant", content: res.content });
5  if (res.stop_reason !== "tool_use") return res;
6 
7  const results: Anthropic.ToolResultBlockParam[] = [];
8  for (const block of res.content) {
9    if (block.type !== "tool_use") continue;
10    try {
11      const out = await runTool(block.name, block.input, currentUser); // your code, your auth
12      results.push({ type: "tool_result", tool_use_id: block.id, content: JSON.stringify(out) });
13    } catch (e) {
14      results.push({ type: "tool_result", tool_use_id: block.id, content: String(e), is_error: true });
15    }
16  }
17  messages.push({ role: "user", content: results });
18}
19throw new Error("Agent hit the step limit");

03Проектирование tools, которыми модель умеет пользоваться

Tools — это руки агента, и большинство провалов агентов — это провалы в дизайне tools. Дайте каждому tool одну понятную задачу, имя, которое говорит, что он делает, и описание, объясняющее, когда его использовать, что он возвращает и где типичные подводные камни, — как будто пишете документацию для нового коллеги. Лучше несколько высокоуровневых tools («search_orders» с фильтрами), чем десятки тонких обёрток над каждым эндпоинтом. Возвращайте компактные релевантные результаты: агент, получивший 5 MB JSON-дампа, тратит контекст впустую и путается, поэтому делайте пагинацию, суммируйте и включайте id для последующих вызовов. Делайте ошибки полезными («customer_id не найден; сначала используй search_customers»). Где возможно, делайте пишущие tools идемпотентными и отделяйте читающие tools от пишущих, чтобы выдавать им разные права. Тестируйте tools, наблюдая за реальными транскриптами: там, где модель неправильно использует tool, обычно нужно доработать описание.

04MCP: подключаем агентов к системам

Model Context Protocol (MCP) — открытый стандарт, предложенный Anthropic и теперь поддерживаемый многими AI-инструментами и провайдерами, для подключения AI-приложений к tools и данным. MCP-сервер предоставляет tools (действия), resources (данные для чтения) и prompts (шаблоны) по стандартному протоколу JSON-RPC — локально через stdio или удалённо по HTTP. Любой MCP-клиент — Claude Code, приложения Claude, IDE и другие хосты агентов — может использовать его без самописного клея. Это значит, что интеграцию «tickets» или «database» вы пишете один раз и переиспользуете в разных агентах. Удалённые MCP-серверы используют OAuth для авторизации, так что агент действует с делегированными пользователем ограниченными правами. Относитесь к сторонним MCP-серверам как к любой устанавливаемой зависимости: проверяйте, к чему у них есть доступ, фиксируйте версии и предпочитайте серверы от надёжных издателей.

1{
2  "mcpServers": {
3    "tickets": {
4      "command": "node",
5      "args": ["./mcp/tickets-server.js"],
6      "env": { "TICKETS_API_URL": "https://api.example.com" }
7    }
8  }
9}

05Контекст: рабочая память агента

Всё, что агент знает во время задачи, живёт в его context window: инструкции, определения tools, история вызовов и результатов. Длинные задачи заполняют его, и качество падает, когда контекст становится шумным. Хорошие обвязки активно управляют контекстом. Держите system prompt сфокусированным на целях, ограничениях и способе проверки работы. Подгружайте tools по требованию, когда их много (tool search). Удаляйте старые объёмные результаты tools, когда они больше не нужны (context editing), или суммируйте раннюю историю (compaction). Дайте агенту scratchpad или memory-файл для заметок, которые должны сохраниться, — плана, решений, прогресса. Большие задачи делите между субагентами: каждый исследует в своём свежем контексте и возвращает главному агенту только краткий результат. Так кодинг-агенты продолжают работать с большими репозиториями, не утопая в содержимом файлов.

06Guardrails и human-in-the-loop

Агент может выполнять реальные действия, поэтому ограничения проектируются так же, как для нового сотрудника с доступом к продакшену. Least privilege: давайте только те tools, которые нужны задаче, с учётными данными, ограниченными пользователем или узким сервисным аккаунтом. Уровни прав: tools только на чтение работают свободно; запись требует подтверждения или выполняется в sandbox; деструктивные действия (платежи, удаления, письма клиентам) всегда требуют человека. Бюджеты: лимиты шагов, бюджеты токенов или стоимости и таймауты по реальному времени. Sandboxing: запускайте код и shell-команды в изолированных контейнерах без секретов и с ограниченной сетью. Проверка: объясните агенту, как проверить свою работу — запустить тесты, перечитать результат, — и где возможно проверяйте сами в коде. Аудит: логируйте каждый вызов tool с входами, выходами и личностью, от имени которой он выполнялся.

• Чтение: разрешено · Запись: подтверждение или sandbox · Необратимое: одобрение человека
• Бюджеты шагов, токенов и времени на каждый запуск
• Секреты остаются в слое tools, никогда в промпте

07Context engineering для долгоиграющих агентов

Долгий запуск агента — это задача о бюджете контекста. Каждый шаг добавляет рассуждения модели, вызов tool и его результат; через несколько десятков шагов большая часть окна — это устаревшие логи. Приёмы, примерно в порядке применения: делайте выходы tools маленькими по дизайну (сводки, пагинация, id вместо целых объектов); удаляйте старые результаты tools, которые модели больше не нужны, сохраняя сам факт вызова (context editing); периодически сжимайте историю в сводку, с которой агент продолжает (compaction); храните долговременное состояние вне окна — файл прогресса, список задач, memory store, — чтобы свежий контекст мог продолжить работу; делегируйте исследование субагентам, которые возвращают сжатые выводы. Prompt caching взаимодействует со всем этим: для попаданий в кэш нужен стабильный префикс, поэтому дописывайте историю, а не переписывайте её, и редактируйте контекст через поддерживаемые механизмы API, а не изменением ранних сообщений, — на текущих моделях это ещё и может инвалидировать сохранённые рассуждения модели.

08Prompt injection и «смертельная триада»

Исследователи безопасности описывают опасное для агентов сочетание: доступ к приватным данным, контакт с недоверенным контентом и возможность отправлять данные наружу (email-tool, HTTP-запрос, даже рендеринг URL картинки). При наличии всех трёх вредоносная веб-страница или документ могут велеть агенту прочитать секреты и вывести их наружу. Поскольку ни одна модель не защищена от injection полностью, разрушайте это сочетание структурно. Где можно, уберите одну «ногу»: никакой исходящей сети в sandbox или никакого доступа к приватным данным во время браузинга. Применяйте allow-list для доменов и получателей. Требуйте подтверждения для любого действия, отправляющего данные вовне. Держите учётные данные в слое tools, чтобы модель их никогда не видела, и используйте токены, ограниченные конкретным пользователем, чтобы ущерб не превышал того, что мог бы сделать этот пользователь. Логируйте и алертьте необычные последовательности вызовов tools и проводите red-teaming агента документами с инъекциями в рамках eval-набора.

09Создание MCP-сервера

MCP-сервер — это небольшая программа, которая объявляет tools со входами в виде JSON Schema и обрабатывает вызовы. Официальные SDK есть для TypeScript, Python и других языков. Локальные серверы общаются через stdio и наследуют права пользователя на машине; удалённые используют Streamable HTTP и должны реализовывать OAuth, чтобы каждый пользователь выдавал ограниченный доступ. Проектируйте tools для агентов, а не ради полноты API: мало tools, понятные описания, компактные результаты. Валидируйте каждый вход и проверяйте авторизацию на стороне сервера. Версионируйте сервер и документируйте breaking changes, потому что агенты зависят от имён и формы tools. Перед разработкой сверьтесь с актуальной спецификацией MCP и документацией SDK — протокол развивается.

1import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3import { z } from "zod";
4 
5const server = new McpServer({ name: "tickets", version: "1.0.0" });
6 
7server.registerTool(
8  "get_ticket",
9  {
10    description: "Fetch one support ticket by id, including status and last 5 messages.",
11    inputSchema: { id: z.string().describe("Ticket id, e.g. T-1042") },
12  },
13  async ({ id }) => {
14    const t = await fetchTicket(id); // your API, your auth
15    return { content: [{ type: "text", text: JSON.stringify(t) }] };
16  },
17);
18 
19await server.connect(new StdioServerTransport());

10Инженерия стоимости и надёжности

Стоимость агента — это токены на шаг, умноженные на шаги на задачу, и оба множителя тихо растут. Измеряйте стоимость и успешность на выполненную задачу, а не на запрос. Рычаги: prompt caching на стабильном префиксе (system prompt и tools), что очень важно, потому что каждый шаг заново отправляет историю; более низкий effort или модель поменьше для субагентов и простых шагов; меньше, но лучше tools, чтобы агенту требовалось меньше вызовов; бюджеты задач, которые позволяют модели самой распределять темп, а не обрываться посреди шага. Для надёжности делайте tools идемпотентными, а ретраи — безопасными, сохраняйте чекпоинты прогресса, чтобы упавший запуск можно было продолжить, задавайте лимиты по реальному времени и обрабатывайте «неудачные» stop reasons (max_tokens, refusal, лимит шагов) с понятным итогом, а не молчанием. Длинные задачи запускайте как фоновые джобы с обновлениями статуса, а не внутри HTTP-запроса.