Как сделать AI-агентов надёжными с TypeScript и Effect.ts

#AI coding#agentic development#TypeScript#Effect.ts#vibe coding

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. Только к валидному, проверенному сервису чтения контекста. Ошибки возвращаются в явном виде — агент может объяснить, что произошло, вместо генерации левых ответов.


Практические уроки и риски


Кому и зачем это полезно

Если ты хочешь сделать AI-агентов частью инженерных процессов, а не просто демо для презентаций — берись за подобный подход. Особенно если у тебя несколько API, сложные зависимости и важна надёжность.

Риски: система получается сложнее, чем “просто вызвать модель”. Нужно продумывать архитектуру, писать больше тестов и не ждать от LLM идеальных ответов.


Что попробовать дальше


В итоге, модель — самая непредсказуемая часть. Всё остальное должно быть инженерно выстроено, чтобы предсказуемо обрабатывать ошибки, зависимости и контекст. Это не про запреты, а про контроль, который даёт возможность строить действительно надёжные AI-агенты для реальной работы.


Попробуй сам: Cursor — AI-редактор для разработчиков.


Источник: https://dev.to/martinpersson/building-reliable-ai-agents-with-typescript-and-effectts-2557