Skip to content

effect-uai

Effectful building blocks for agentic ai

Get started View on GitHub

Agents should be ordinary programs: explicit state, typed effects, visible streams, and tools you control. effect-uai gives you the primitives to build that loop without handing your architecture to a framework.

basic-usage / agent loop

hover any line

1export const conversation = loop(initial, (state) =>2  Effect.gen(function* () {3    const oai = yield* Responses4    return oai5      .streamTurn({ history: state.history, model, tools })6      .pipe(7        onTurnComplete((turn) => Effect.sync(() => {8          const calls = Turn.getToolCalls(turn)9          if (calls.length === 0) return stop()10          return Toolkit.run(tools, calls).pipe(11            Toolkit.continueWithResults(12              Toolkit.appendToolResults(state, turn),13            ),14          )15        })),16      )17  }))

Control the turns

Pause, resume, compact, persist, branch, or stop the conversation on your terms.

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.

Powerful building blocks

Small, composable primitives to assemble 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 is a stream you can transform, filter, and collect when ready. Performance built in.

Typed errors

Easy and type-safe error handling. 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.

Recipes

26 and counting

Each recipe shows how to solve a common agent problem with the primitives.

Tool call approval

Pause on sensitive tools. HTTP-bundled or queue-driven verdicts; same primitive.

Live tool updates

Watch tools work. Stream progress and reasoning as they run; the model gets one clean result.

Stream typed objects

Stream data as it arrives. Decode and validate one object at a time as the model writes.

Multi-model fallback

Stay online when a provider fails. Switch automatically on rate limits or outages.

Model escalation

Pay only when needed. The cheap model handles easy questions and escalates hard ones to a more capable model.

Auto-compaction

Never run out of context. Summarize history before the token budget runs dry.

Pause and resume

Pause without losing progress. Hold the loop between turns and continue right where it stopped.

Mid-stream abort

Stop on a dime. Cancel a running turn, drop the HTTP connection, and keep the partial output.

Wait for a long-running tool call. The agent goes quiet while the work runs and wakes up the moment it's done.

Stay online for the whole chat. Pull user messages from a queue; debounce bursts into one batch.

Modify output stream

Format for the wire. Map one function to ship the loop's output as SSE or JSONL.

Retry transient failures. Exponential backoff for rate limits and timeouts; fail fast on the rest.

Multi-model compare

See how models differ. Send one prompt to OpenAI, Google, and Anthropic at once.

Get the best answer. Models judge each other, the winner streams back.

Talk to your agent. Streaming STT, LLM, and TTS composed as Effect fibers; stop-words interrupt mid-sentence.

Run your own AI radio station. An AI DJ writes the next track while you listen to the current one; the same set replays for free.

Run, fix, repeat

Let the model run its own code. It writes Python; the sandbox runs it; tracebacks feed back into the next turn until the answer's right.

Ready to build your loop?

Install the package, copy a recipe, keep your loop explicit.

Get started View on GitHub