effect-uai — скилл

---
name: effect-uai
description: Use when building AI agents and AI media workflows with effect-uai (Effect-based primitives for agent loops, tools, streaming, structured output, embeddings, retrieval, reranking, speech, realtime voice and camera sessions, messenger bots, browser chat UIs, music, and image generation). Covers design philosophy, core primitives, provider wiring, and a recipe library for retry, fallback, tool approval, RAG and hybrid retrieval, transcription, speech synthesis, voice loops, realtime voice agents, Telegram/Discord/Slack bots, music generation, image generation and editing, SSE/JSONL, and more.
license: MIT
---

# effect-uai

Low-level Effect primitives for building AI agents as ordinary programs.
The library does not own your control flow; it gives you the pieces and
gets out of the way.

## Design philosophy

Use this mental model when writing or recommending code:

1. **State is a record you own.** History is `ReadonlyArray<Items.HistoryItem>`.
   Add whatever else your app needs (turn index, budget, tenant id,
   pendingPrompts, ...). The library never inspects it.
2. **One turn is a `Stream<TurnEvent>`.** Text deltas, reasoning, tool
   calls, usage updates, and the terminal `TurnComplete` (carrying the
   assembled `Turn`) all flow through one typed stream.
3. **The loop is a pull-based combinator.** `loop((state) => Stream<Step<A, S>>)`
   threads state across iterations. Each body returns a stream that
   forwards values, then ends with `Loop.next(state)` to continue or
   `Loop.stop()` / `Loop.stop(state)` to exit.
4. **Tools are typed Effects (or Streams).** A `Tool` declares an input
   schema and a `run(input)` returning an Effect, or a Stream of snapshots
   of its own output type. Tools are grouped into a name-indexed `Toolkit`,
   and `Toolkit.run(toolkit, calls)` returns a stream of `ToolEvent.Partial`
   (every stream element, as it is produced) and `ToolEvent.Output` (a typed
   `Result`), so the UI sees progress while only the final value goes back
   to the model.
5. **Providers are Layers.** `LanguageModel` is a single service; each
   provider package (`@effect-uai/responses`, `@effect-uai/anthropic`,
   `@effect-uai/google`) ships a `layer({ apiKey })` that implements it.
   The program shape stays identical across providers.

When the user asks for a "framework feature" (auto-retry, mid-stream
abort, pause/resume, streaming JSONL, multi-model voting, ...), the
answer is almost always "compose primitives in the loop body", not
"reach for an integration." Recommend the appropriate recipe pattern
(see catalog below) instead of building wrapper layers.

## Install

```sh
pnpm add @effect-uai/core effect
# pick one or more providers:
pnpm add @effect-uai/openai            # OpenAI: Responses (language) + embeddings + speech + images