BoundActivities

Defined in: packages/ai/src/activities/chat/agents/bound.ts:197

Activity functions bound to one child run. Each takes the same options as the plain function, but threadId is optional: the child run fills it. Options you pass win over the bound defaults.

Properties#

chat#

chat: <TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware, TAgents>(options) => TextActivityResult<TSchema, TStream, TTools>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:198

Type Parameters#

TAdapter#

TAdapter extends AnyTextAdapter

TSchema#

TSchema extends SchemaInput | undefined = undefined

TStream#

TStream extends boolean = boolean

TTools#

TTools extends | readonly ( | Omit<Tool<any, any, any, any>, "execute"> & object & object | ProviderTool<string, TAdapter["~types"]["toolCapabilities"][number]>)[] | undefined = | readonly ( | Omit<Tool<any, any, any, any>, "execute"> & object & object | ProviderTool<string, TAdapter["~types"]["toolCapabilities"][number]>)[] | undefined

TInterrupts#

TInterrupts extends readonly InterruptDefinition<any, any, any, any, any>[] = []

TContext#

TContext = unknown

TMiddleware#

TMiddleware extends unknown[] | undefined = undefined

TAgents#

TAgents extends readonly DefinedAgent<string, readonly SubagentTool[], SchemaInput | undefined, readonly InterruptDefinition<any, any, any, any, any>[], any, unknown, AgentProduces | undefined>[] = readonly DefinedAgent<string, readonly SubagentTool[], SchemaInput | undefined, readonly InterruptDefinition<any, any, any, any, any>[], any, unknown, AgentProduces | undefined>[]

Parameters#

options#

BoundTextActivityOptions<TAdapter, TSchema, TStream, TTools, TInterrupts, TContext, TMiddleware, TAgents>

Returns#

TextActivityResult<TSchema, TStream, TTools>

decide#

decide: <TAdapter, TQuestions>(options) => Promise<{ [K in string | number | symbol]: InferEvaluateAnswer<TQuestions[K]> } & object>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:292

Ask typed questions about state and get answers your code can branch on.

You have state (a ticket, a record, a log) and you need typed answers, not prose. Pass questions built with choice, score, and boolean. Then branch on result.queue.value in ordinary TypeScript.

The question key meta is reserved. Throws if questions is empty or uses that key.

When the adapter throws an EvaluateError that carries usage, decide() reports that usage through onUsage and the evaluate:usage event, then runs onError and rethrows the same error.

Type Parameters#

TAdapter#

TAdapter extends EvaluateAdapter<string, EvaluateProviderOptions<TAdapter>>

TQuestions#

TQuestions extends Record<string, WireQuestion>

Parameters#

options#

EvaluateActivityOptions<TAdapter, TQuestions>

Returns#

Promise<{ [K in string | number | symbol]: InferEvaluateAnswer<TQuestions[K]> } & object>

Example#

Route a support ticket

import { decide, choice, score, boolean } from '@tanstack/ai'
import { typesafeDecider } from '@tanstack/ai-typesafe'

const result = await decide({
  adapter: typesafeDecider('jev-latest'),
  state: ticket,
  questions: {
    queue: choice({
      instructions: 'Which team should handle this ticket?',
      options: {
        billing: 'Payments, invoices, refunds',
        tech: 'Bugs, outages, integrations',
        sales: 'Pricing, upgrades, new accounts',
      },
    }),
    urgency: score({
      instructions: 'How urgent is this ticket?',
      levels: ['low', 'medium', 'high'],
    }),
    refund: boolean({
      instructions: 'Is the customer asking for a refund?',
    }),
  },
})

result.queue.value
result.meta.model
result.meta.usage

embed#

embed: <TAdapter>(options) => Promise<EmbeddingResult>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:290

Embed activity - generates embedding vectors from text and image inputs.

Accepts a single item or an array of items; the result always carries an embeddings array with one vector per input item, in input order.

Type Parameters#

TAdapter#

TAdapter extends EmbeddingAdapter<string, any, any, any>

Parameters#

options#

EmbedOptions<TAdapter>

Returns#

Promise<EmbeddingResult>

Examples#

Embed a single text

import { embed } from '@tanstack/ai'
import { openaiEmbedding } from '@tanstack/ai-openai'

const result = await embed({
  adapter: openaiEmbedding('text-embedding-3-small'),
  input: 'a red guitar',
})

console.log(result.embeddings[0].vector)

Batch with requested dimensions

const result = await embed({
  adapter: openaiEmbedding('text-embedding-3-large'),
  input: ['a red guitar', 'a blue drum kit'],
  dimensions: 1024,
})

Multimodal embedding (text + image fused into one vector)

import { cohereEmbedding } from '@tanstack/ai-cohere'

// A nested array of parts fuses them into a single vector. The outer array
// is the item list, so this embeds one fused item into one vector.
const result = await embed({
  adapter: cohereEmbedding('embed-v4.0'),
  input: [
    [
      { type: 'text', content: 'product photo' },
      { type: 'image', source: { type: 'data', value: base64, mimeType: 'image/png' } },
    ],
  ],
  modelOptions: { inputType: 'search_document' },
})

generateAudio#

generateAudio: <TAdapter, TStream>(options) => AudioActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:245

Type Parameters#

TAdapter#

TAdapter extends AudioAdapter<string, AudioProviderOptions<TAdapter>>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<AudioActivityOptions<TAdapter, TStream>>

Returns#

AudioActivityResult<TStream>

generateImage#

generateImage: <TAdapter, TStream>(options) => ImageActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:233

Type Parameters#

TAdapter#

TAdapter extends ImageAdapter<string, any, any, any, ModelInputModalitiesByName>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<ImageActivityOptions<TAdapter, TStream>>

Returns#

ImageActivityResult<TStream>

generateLiveVideo#

generateLiveVideo: <TAdapter, TStream>(options) => LiveVideoActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:281

Type Parameters#

TAdapter#

TAdapter extends LiveVideoAdapter<string, LiveVideoProviderOptions<TAdapter>>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<LiveVideoActivityOptions<TAdapter, TStream>>

Returns#

LiveVideoActivityResult<TStream>

generateSpeech#

generateSpeech: <TAdapter, TStream>(options) => TTSActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:251

Type Parameters#

TAdapter#

TAdapter extends TTSAdapter<string, TTSProviderOptions<TAdapter>>

TStream#

TStream extends boolean = false

Parameters#

options#

Omit<TTSActivityOptionsBase<TAdapter, TStream>, "threadId"> & object & TTSTextOrTurns

Returns#

TTSActivityResult<TStream>

generateTranscription#

generateTranscription: <TAdapter, TStream>(options) => TranscriptionActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:264

Type Parameters#

TAdapter#

TAdapter extends TranscriptionAdapter<string, TranscriptionProviderOptions<TAdapter>>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<TranscriptionActivityOptions<TAdapter, TStream>>

Returns#

TranscriptionActivityResult<TStream>

generateVideo#

generateVideo: <TAdapter, TStream>(options) => TStream extends true ? AsyncIterable<AGUIEvent, any, any> : Promise<VideoJobResult>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:239

Type Parameters#

TAdapter#

TAdapter extends VideoAdapter<string, any, any, any, any, any>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<VideoCreateOptions<TAdapter, TStream>>

Returns#

TStream extends true ? AsyncIterable<AGUIEvent, any, any> : Promise<VideoJobResult>

generateVoice#

generateVoice: <TAdapter, TStream>(options) => VoiceActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:258

Type Parameters#

TAdapter#

TAdapter extends VoiceAdapter<string, VoiceProviderOptions<TAdapter>>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<VoiceActivityOptions<TAdapter, TStream>>

Returns#

VoiceActivityResult<TStream>

generateWorld#

generateWorld: <TAdapter, TStream>(options) => WorldActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:275

Type Parameters#

TAdapter#

TAdapter extends WorldAdapter<string, WorldProviderOptions<TAdapter>>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<WorldActivityOptions<TAdapter, TStream>>

Returns#

WorldActivityResult<TStream>

rerank#

rerank: <TAdapter, TDocument>(options) => Promise<RerankResult<TDocument>>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:291

Rerank activity - reorders documents by relevance to a query.

Type Parameters#

TAdapter#

TAdapter extends RerankAdapter<string, RerankProviderOptions<TAdapter>>

TDocument#

TDocument extends string | object = string

Parameters#

options#

RerankActivityOptions<TAdapter, TDocument>

Returns#

Promise<RerankResult<TDocument>>

Examples#

Basic reranking

import { rerank } from '@tanstack/ai'
import { cohereRerank } from '@tanstack/ai-cohere'

const { ranking, rerankedDocuments } = await rerank({
  adapter: cohereRerank('rerank-v3.5'),
  query: 'talk about rain',
  documents: ['sunny day at the beach', 'rainy afternoon in the city'],
  topN: 2,
})

console.log(rerankedDocuments[0]) // 'rainy afternoon in the city'

Reranking object documents

const { ranking } = await rerank({
  adapter: cohereRerank('rerank-v3.5'),
  query: 'best laptop for travel',
  documents: [
    { id: 1, text: 'A heavy gaming desktop' },
    { id: 2, text: 'A lightweight ultrabook with all-day battery' },
  ],
})

// ranking[0].document is the original object, fully typed.
console.log(ranking[0].document.id)

summarize#

summarize: <TAdapter, TStream>(options) => SummarizeActivityResult<TStream>;

Defined in: packages/ai/src/activities/chat/agents/bound.ts:227

Type Parameters#

TAdapter#

TAdapter extends SummarizeAdapter<string, object>

TStream#

TStream extends boolean = false

Parameters#

options#

WithOptionalThreadId<SummarizeActivityOptions<TAdapter, TStream>>

Returns#

SummarizeActivityResult<TStream>