MCP

Uai \ wai \. Mineiro Portuguese, all-purpose interjection.

Low-level primitives for building AI agents with Effect.

effect-uai is not a framework. There's no runtime to learn, no orchestrator to override, no graph to fight. You get typed streaming primitives (one turn, one tool call) and compose the loop yourself.

OpenAI Responses, Anthropic, Gemini, and any OpenAI-compatible gateway normalize to one TurnEvent union. State is yours. The loop is yours.

Status

While we're in 0.x, minor releases may include breaking changes. Each one ships with a migration guide written in operator form ("if you see X, write Y"), so pointing Claude Code at the page makes upgrades mechanical.

Why effect-uai

Most agent libraries decide how your loop works: state shape, retry policy, tool dispatch, cancellation. When you need something they didn't plan for (approval gates, mid-stream cancel, fallback, auto-compaction), you fight the framework.

effect-uai owns the wire (HTTP, SSE, event normalization, validation). You own the policy. They meet at a Stream<TurnEvent> and a plain state record.

Features

• Explicit control. No black-box magic. You stay in full control of your agent loop.
• Built on Effect. Retries, streams, concurrency, errors: handled by Effect, not reinvented.
• Composable primitives. Small building blocks you assemble into your own agentic loops.
• Recipes for the hard parts. Copy-paste solutions for model council, auto-compaction, pause and resume, and more.
• Streaming first. Everything's a stream you can transform, filter, and collect when ready.
• Typed errors. Match RateLimited, Unavailable, or Timeout directly. No string parsing.
• Carry your own state. History, budget, scratchpad. Track whatever your agent needs. It's just a value.

Quick taste

The canonical agent loop: stream a turn, run any tools the model asks for, append the outputs, continue until it stops.

export const conversation = loop(initial, (state) =>
  Effect.gen(function* () {
    const oai = yield* Responses // swap for Anthropic / Gemini any turn
    return oai
      .streamTurn({ history: state.history, model, tools: toolkit }) // stream text, reasoning, tool events
      .pipe(
        onTurnComplete((turn) =>
          Effect.sync(() => {
            const calls = Turn.getToolCalls(turn) // approve, deny, audit, batch (it's your code)
            if (calls.length === 0) return stop() // stop on a final answer, a budget, your call
            return Toolkit.run(toolkit, calls).pipe(
              // run typed Effect tools
              Toolkit.continueWithResults(
                Toolkit.appendToolResults(state, turn), // fold results back into your state
              ),
            )
          }),
        ),
      )
  }),
)

For tools, approvals, multi-turn loops, sandboxes, and cross-provider fallback, see the docs or the recipes.

Packages

Each provider is its own package - edge / browser builds only pull in what you actually use.

Repo layout

.
├── packages/
│   ├── core/                  # @effect-uai/core - primitives, no provider deps
│   ├── compat/
│   │   └── ai-sdk/            # @effect-uai/ai-sdk - Vercel AI SDK UI Message Stream
│   └── providers/
│       ├── responses/         # @effect-uai/responses - OpenAI Responses
│       ├── chat-completions/  # @effect-uai/chat-completions - gateway base
│       ├── anthropic/         # @effect-uai/anthropic
│       ├── google/            # @effect-uai/google - Gemini + speech + Live + images + Lyria
│       ├── mistral/           # @effect-uai/mistral - LLM + Voxtral speech (STT/TTS)
│       ├── openai/            # @effect-uai/openai - Responses + embeddings + speech + realtime + images
│       ├── fal/               # @effect-uai/fal - image generation (FLUX, Seedream, Qwen)
│       ├── elevenlabs/        # @effect-uai/elevenlabs - speech + music
│       ├── inworld/           # @effect-uai/inworld - speech
│       ├── jina/              # @effect-uai/jina - embeddings + rerank + web read
│       ├── typesafe-ai/       # @effect-uai/typesafe-ai - Jev decision model
│       ├── perplexity/        # @effect-uai/perplexity - web search
│       ├── exa/               # @effect-uai/exa - web search + web read
│       ├── tavily/            # @effect-uai/tavily - web search + web read
│       ├── firecrawl/         # @effect-uai/firecrawl - web read
│       ├── browser/           # @effect-uai/browser - CDP browser control
│       ├── mcp/               # @effect-uai/mcp - MCP client
│       ├── microsandbox/      # @effect-uai/microsandbox - local sandboxes
│       ├── deno/              # @effect-uai/deno - hosted sandboxes
│       ├── telegram/          # @effect-uai/telegram - Messenger over the Bot API
│       ├── discord/           # @effect-uai/discord - Messenger over gateway + REST
│       └── slack/             # @effect-uai/slack - Messenger over Socket Mode + Web API
│   └── retrieval/             # @effect-uai/retrieval - chunking, rank fusion, tokenizer
├── recipes/                   # 42 worked recipes (type-checked, tested) covering
│                              # tools, approvals, fallback, voice, realtime, retrieval, MCP, chat bots, …
├── recipes-extras/            # 3 recipes needing extra infra (agentic-search,
│                              # contextual-retrieval, sandbox-code-interpreter)
├── docs/                      # Source for the docs site (concepts, recipes, providers)
├── webpage/                   # Astro/Starlight site that renders docs/
├── skills/                    # Agent skills that teach a coding agent this library
├── examples/                  # Standalone apps; installed on their own, not workspace-globbed
└── integration-tests/         # Live-system smoke tests; run manually, not part of CI

A recipe folder typically contains:

• recipe.ts - the building blocks (tools, state, body), reusable in tests
• app.ts - provider wiring and rendering, runtime-agnostic
• run-node.ts / run-bun.ts / run-deno.ts - attach that runtime's HttpClient
• recipe.test.ts - vitest tests against MockProvider
• README.md - the page that's mirrored in the docs site

Older recipes still use a flatter index.ts / index.test.ts / run.ts shape; both are current, and recipes migrate as they're touched.

Docs / learn

Full docs: https://effect-uai.betalyra.com

Prefer video? Watch the 47 minute intro first.

Recommended reading order:

1. One turn is a stream - the smallest provider-agnostic primitive.
2. Basic usage - the core agent harness: state, stream, tools, continuation.
3. The loop primitive - what loop is, its shape, and streamUntilComplete.
4. Items and turns - the conversation as a flat list, the assembled turn, the event stream.
5. Tools and toolkits - Tool.make (with progress via emit), Toolkit.make, approval planners, ToolEvent.
6. MCP - point at an MCP server and its tools become a Toolkit.

Then dip into recipes for whatever pattern you need.

Local development

pnpm install
pnpm test          # vitest run across all workspaces
pnpm typecheck     # tsc --noEmit

To run a recipe end-to-end against real providers:

OPENAI_API_KEY=sk-... pnpm tsx recipes/basic-usage/run-node.ts

Nix dev shell (optional)

This repo ships a flake.nix that provides a dev shell with the exact toolchain CI uses - Node 24, the pinned pnpm version (via corepack), and Deno for the integration tests. It is 100% optional: if you already have Node and pnpm installed, ignore this entirely and use the commands above.

If you do use Nix with flakes enabled:

nix develop          # drops you into a shell with node, pnpm and deno

The repo also ships an .envrc, so with direnv installed the shell loads automatically when you cd in - just run direnv allow once. Without direnv the file is inert and ignored.

Contributors

Thanks to everyone who has contributed to effect-uai.

License

MIT - see LICENSE.