AI-агенты — легко собрать демо, сложно сделать надёжными. За последние месяцы я много работал с AI-кодингом и столкнулся с классической проблемой: быстро собрать прототип — вопрос пары строчек, а вот чтобы он стабильно работал в реальной инженерной среде, нужно гораздо больше.
Подключить LLM к API — не сложно. Гораздо сложнее продумать, что делать, если API не отвечает, данные пришли не те, или агент сделал неверное предположение. В своих бекенд-проектах я давно юзаю Effect.ts — это библиотека для декларативного управления эффектами, валидации, обработки ошибок и DI. И решил применить её к AI-агентам.
Расскажу, как я строил простой, но надёжный AI-планировщик задач на TypeScript с Effect.ts и чем это круто для агентного кодинга.
Проблема: агент должен не просто “врубиться”, а быть устойчивым
Частая ошибка при разработке AI-агентов — доверять всему, что приходит с внешних сервисов, и не учитывать реальные ошибки. В итоге, агент либо ломается, либо начинает “фантазировать”, когда что-то пошло не так.
Для меня важна предсказуемость: если API недоступен — агент должен об этом честно сказать, если данные невалидные — обработать это, не падая. Иначе никакой автоматизации, а только хаос.
Здесь на помощь приходит Effect.ts. Это не просто ещё одна либра для промисов, а полноценная система описания эффектов с типами ошибок, зависимостями и композициями. Можно явно задекларировать, какие ошибки и когда возможны, а потом с ними работать в коде.
Архитектура простого AI-планировщика с Effect.ts
Представим задачу: есть внутренняя система тикетов (например, ENG-142). Нужно, чтобы AI-ассистент прочитал тикет, извлёк из него контекст и инженерные рекомендации, и предложил план реализации с тестами и вопросами.
Важно, что это read-only ассистент — никакого изменения кода, тикетов или деплоя. Только чтение.
1. Валидация данных из API
Даже если мы доверяем своей системе управления задачами, API — внешний источник. Его ответ надо валидировать. Это классика в vibe coding: никакого “any” и невалидных данных в основной код.
import { Schema } from "effect";
const Ticket = Schema.Struct({
id: Schema.String,
title: Schema.String,
description: Schema.String,
area: Schema.Literal("backend", "frontend"),
});
type Ticket = typeof Ticket.Type;
Теперь в приложении мы работаем с типами, а не с набором JSON-полей, которые могут быть чем угодно.
2. Сервис для получения тикета с явными ошибками
Effect.ts позволяет не только вернуть данные, но и типизировать ошибки с помощью TaggedError.
import { Context, Data, Effect } from "effect";
class TicketNotFound extends Data.TaggedError("TicketNotFound")<{ id: string }> {}
class InvalidTicket extends Data.TaggedError("InvalidTicket")<{ id: string }> {}
class TicketService extends Context.Tag("TicketService")<
TicketService,
{ get: (id: string) => Effect.Effect<Ticket, TicketNotFound | InvalidTicket> }
>() {}
Функция get возвращает эффект, который либо выдаст тикет, либо одну из ошибок. Агенту не важно, откуда данные (ClickUp, GitHub, локальный API). Он работает по контракту.
Это сильно облегчает тестирование: можно мокать сервис и не тратить токены на реальные запросы.
3. Контекст — знания команды, а не модель
Чтобы AI не гадал, как у вас устроен бекенд или фронт, я сделал отдельный сервис с инженерными гайдами.
class ContextService extends Context.Tag("ContextService")<
ContextService,
{ forArea: (area: Ticket["area"]) => Effect.Effect<string> }
>() {}
Этот сервис выдаёт релевантные инструкции (валидация, архитектура, тестирование) для области тикета. Так знания не теряются, не зависят от одной сессии в чате и доступны агенту в коде.
4. Собираем инструментарий агента
Теперь можно описать инструмент, который агент может вызвать.
import { generateText, stepCountIs, tool } from "ai";
import { Effect } from "effect";
import { z } from "zod";
const readTicketContext = tool({
description: "Read a ticket and its engineering guidelines",
inputSchema: z.object({ id: z.string().regex(/^ENG-\d+$/) }),
execute: async ({ id }) =>
Effect.runPromise(
loadPlanningContext(id).pipe(
Effect.map((data) => ({ ok: true as const, data })),
Effect.catchTags({
TicketNotFound: () => Effect.succeed({ ok: false as const, error: "Not found" }),
InvalidTicket: () => Effect.succeed({ ok: false as const, error: "Invalid ticket" }),
}),
Effect.provide(AppLayer),
),
),
});
const result = await generateText({
model: process.env.AI_MODEL!,
system: `You are a planning assistant.
Read the ticket context before writing a plan.
Propose implementation steps, tests, and unknowns.
Never claim that code was changed or tested.`,
prompt: "Prepare an implementation plan for ENG-142.",
stopWhen: stepCountIs(3),
tools: { readTicketContext },
});
console.log(result.text);
Обрати внимание: агент не получает произвольный доступ к API, БД или shell. Только к валидному, проверенному сервису чтения контекста. Ошибки возвращаются в явном виде — агент может объяснить, что произошло, вместо генерации левых ответов.
Практические уроки и риски
- Тестируем вне модели. Не нужно сразу проверять, что LLM выдаст точный текст — это непредсказуемо. Сначала проверяй сервисы, валидацию, обработку ошибок, контекст. Это делает систему предсказуемой.
- Отделяй логику агента от API-интеграций. Когда что-то ломается, важно понять, где именно — модель сгенерила что-то странное или упал API.
- Effect.ts — не панацея, но мощный скаффолд. Для простых прототипов хватит try/catch и Zod. Но когда система растёт, появляются таймауты, ретраи, объединение сервисов, — Effect становится незаменимым.
- Контекст команды — важнее истории чата. AI сам по себе не знает, как вы кодите и тестируете. Делайте знания доступными через сервисы, а не надеетесь на память модели.
Кому и зачем это полезно
Если ты хочешь сделать AI-агентов частью инженерных процессов, а не просто демо для презентаций — берись за подобный подход. Особенно если у тебя несколько API, сложные зависимости и важна надёжность.
Риски: система получается сложнее, чем “просто вызвать модель”. Нужно продумывать архитектуру, писать больше тестов и не ждать от LLM идеальных ответов.
Что попробовать дальше
- Добавить approval workflows: отправлять план на ревью перед выполнением.
- Расширить набор инструментов агента — например, чтение архитектурных решений, запуск статического анализа.
- Внедрить RAG (retrieval-augmented generation) для подтягивания свежей документации.
- Использовать agentic workflows: несколько агентов, взаимодействующих для сложных задач.
В итоге, модель — самая непредсказуемая часть. Всё остальное должно быть инженерно выстроено, чтобы предсказуемо обрабатывать ошибки, зависимости и контекст. Это не про запреты, а про контроль, который даёт возможность строить действительно надёжные AI-агенты для реальной работы.
Попробуй сам: Cursor — AI-редактор для разработчиков.
Источник: https://dev.to/martinpersson/building-reliable-ai-agents-with-typescript-and-effectts-2557