@tanstack/ai-effect

Effect 4 bindings for TanStack AI. Each function takes the options of the core function and returns an Effect Effect or Stream. For a walkthrough, start with Effect.

Installation#

npm i @tanstack/ai @tanstack/ai-effect effect

pnpm add @tanstack/ai @tanstack/ai-effect effect

yarn add @tanstack/ai @tanstack/ai-effect effect

bun add @tanstack/ai @tanstack/ai-effect effect

Peer dependencies: @tanstack/ai and effect 4.1 or later.

chat(options)#

Runs core chat() as an Effect. See Effect.

import * as AI from '@tanstack/ai-effect'
import { openaiText } from '@tanstack/ai-openai'

const stream = AI.chat({
  adapter: openaiText('gpt-6.1-sol'),
  messages: [{ role: 'user', content: 'Hello' }],
  threadId: 'hello',
})

Options#

The options of core chat, with two changes:

• abortController is not an option. Interruption aborts the run.
• tools can also hold serverTool values.

Returns#

R is the union of the services of the serverTool values in tools. With no serverTool, R is never.

serverTool(definition, execute)#

Makes a server tool from a tool definition and a function that returns an Effect. See Effect tools.

function serverTool<TDef, E, R>(
  definition: TDef,
  execute: (
    input: InferSchemaType<TDef['inputSchema']>,
    context: ToolExecutionContext,
  ) => Effect.Effect<InferSchemaType<TDef['outputSchema']>, E, R>,
): EffectServerTool<TDef, R>

• definition: the result of toolDefinition() from @tanstack/ai.
• execute: gets the parsed input and the tool context. It returns an Effect of the output.

A failure of the Effect goes to the model as a tool error. The run continues. If the run aborts, the tool fiber is interrupted.

toolSchema(schema)#

Turns an Effect Schema into an inputSchema or outputSchema for toolDefinition().

function toolSchema<S extends Schema.Constraint>(
  schema: S,
): StandardJSONSchemaV1<S['Encoded'], S['Type']>

• Every object in the JSON Schema has additionalProperties: false. This lets providers such as OpenAI use strict mode.
• The tool input in serverTool gets the type of the schema.

EffectServerTool<TDef, R>#

The type that serverTool returns. Pass it in the tools of chat.

AIError#

The error of every function in this package. It wraps a throw or a rejection from TanStack AI.

class AIError extends Data.TaggedError('AIError')<{
  readonly message: string
  readonly cause: unknown
}> {}

• _tag: 'AIError'. Catch it with Effect.catchTag('AIError', ...).
• message: the message of the original error.
• cause: the original error.

A RUN_ERROR chunk does not fail a Stream. It is a normal chunk. See Effect activities.

Activities#

Each activity takes the options of its core function, without abortSignal. It returns Effect.Effect<Result, AIError>. With stream: true, it returns Stream.Stream<StreamChunk, AIError>.

For the core options and results, see @tanstack/ai. For examples, see Effect activities.