@tanstack/ai 0.57.0 → 0.59.0

package/src/activities/chat/agents/define-agent.ts

@@ -0,0 +1,121 @@
+import type { SubagentInfo as AGUISubagentInfo } from '@ag-ui/core'
+import type { InterruptDefinition } from '../../../interrupt-definition'
+import type {
+  AnyTool,
+  ModelMessage,
+  RunAgentResumeItem,
+  SchemaInput,
+  StreamChunk,
+  UIMessage,
+} from '../../../types'
+import type { AnyClientTool } from '../tools/tool-definition'
+
+/**
+ * Context the library passes into {@link defineAgent} `run`.
+ */
+export interface SubagentRunContext {
+  messages: Array<UIMessage | ModelMessage>
+  abortSignal?: AbortSignal
+  threadId: string
+  /** Run id for the child `chat()`. */
+  runId: string
+  /**
+   * The run this child run continues. It is the parent chat run on the first
+   * run, and the interrupted parent run on a resume. Pass it to the child
+   * `chat()`.
+   */
+  parentRunId: string
+  /** Answers to this child's interrupts. Pass it to the child `chat()`. */
+  resume?: Array<RunAgentResumeItem>
+  /**
+   * The child's AG-UI run id. Stays the same when an interrupted child
+   * continues. Pass it to the child `chat()` so its middleware sees
+   * `ctx.subagentRunId`.
+   */
+  subagentRunId: string
+  parentSubagentRunId?: string
+}
+
+/**
+ * A tool a child agent can carry into client part types.
+ * Server tools and client tools both qualify.
+ */
+export type SubagentTool = AnyTool | AnyClientTool
+
+/**
+ * A named child agent. `run` is a `chat()` call (or any stream of AG-UI chunks).
+ * `TTools` and `TSchema` stay on the object so `useChat({ subagents })` can
+ * type that child's parts.
+ */
+export interface DefinedAgent<
+  TName extends string = string,
+  TTools extends ReadonlyArray<SubagentTool> = ReadonlyArray<SubagentTool>,
+  TSchema extends SchemaInput | undefined = SchemaInput | undefined,
+  TInterrupts extends ReadonlyArray<InterruptDefinition<any, any, any, any>> =
+    ReadonlyArray<InterruptDefinition<any, any, any, any>>,
+> extends AGUISubagentInfo {
+  name: TName
+  /** Required here: the router and the synthetic tool both read it. */
+  description: string
+  run: (
+    ctx: SubagentRunContext,
+  ) => AsyncIterable<StreamChunk> | Promise<AsyncIterable<StreamChunk>>
+  tools?: TTools
+  interrupts?: TInterrupts
+  outputSchema?: TSchema
+  subagents?: unknown
+}
+
+/**
+ * Choice options for a `decide()` router. `main` is required plus every agent name.
+ */
+export type SubagentChoiceOptions<TAgents extends ReadonlyArray<DefinedAgent>> =
+  { main: string } & {
+    [K in TAgents[number]['name']]: string
+  }
+
+/**
+ * Define a named child agent. Pass the same object to `chat({ subagents })`.
+ * Pass the agents array to `useChat({ subagents })` when you render parts
+ * yourself. The hook uses it for types only. It does not call `run`.
+ *
+ * @example
+ * ```ts
+ * const researcher = defineAgent({
+ *   name: 'researcher',
+ *   description: 'Looks up facts',
+ *   run: (ctx) =>
+ *     chat({
+ *       adapter: openaiText('gpt-5.6'),
+ *       messages: ctx.messages,
+ *       threadId: ctx.threadId,
+ *       runId: ctx.runId,
+ *       parentRunId: ctx.parentRunId,
+ *       subagentRunId: ctx.subagentRunId,
+ *       resume: ctx.resume,
+ *     }),
+ * })
+ * ```
+ */
+export function defineAgent<
+  const TName extends string,
+  const TTools extends ReadonlyArray<SubagentTool> = readonly [],
+  TSchema extends SchemaInput | undefined = undefined,
+  const TInterrupts extends ReadonlyArray<
+    InterruptDefinition<any, any, any, any>
+  > = readonly [],
+>(agent: DefinedAgent<TName, TTools, TSchema, TInterrupts>) {
+  if (agent.name.trim() === '') {
+    throw new Error('defineAgent requires a non-empty name')
+  }
+  // A router returns 'main' to keep the turn on the parent.
+  if (agent.name.trim() === 'main') {
+    throw new Error(
+      "defineAgent cannot use the name 'main'. A router uses it for the parent.",
+    )
+  }
+  if (agent.description.trim() === '') {
+    throw new Error('defineAgent requires a non-empty description')
+  }
+  return agent
+}

package/src/activities/chat/agents/route.ts

@@ -0,0 +1,115 @@
+import { boolean, choice } from '../../evaluate/index'
+import type { DefinedAgent } from './define-agent'
+import type { SubagentOrder, SubagentRouterPick } from './spawn'
+
+const ORDER_KEY = 'order'
+
+export interface SubagentRouteOptions<
+  TAgents extends ReadonlyArray<DefinedAgent>,
+> {
+  /**
+   * Question text for every agent. The key is the agent name.
+   * Omit this and each question uses that agent's description.
+   */
+  when?: { [K in TAgents[number]['name']]: string }
+  /**
+   * Agents that run after the other selected agents. The lead group starts
+   * together. The `then` agents then run one after another in list order, and
+   * each reads the text so far. Used only when the router picks at least one
+   * agent from each group. Otherwise `pick` returns `{ names, order }`.
+   */
+  then?: ReadonlyArray<TAgents[number]['name']>
+}
+
+type RouteQuestions<TAgents extends ReadonlyArray<DefinedAgent>> = {
+  [K in TAgents[number]['name']]: ReturnType<typeof boolean>
+} & {
+  order: ReturnType<
+    typeof choice<{
+      parallel: string
+      sequence: string
+    }>
+  >
+}
+
+type RouteAnswers<TAgents extends ReadonlyArray<DefinedAgent>> = {
+  [K in TAgents[number]['name']]: { value: boolean }
+} & {
+  order: { value: SubagentOrder }
+}
+
+/**
+ * Build `decide()` questions for a subagent router.
+ *
+ * One yes/no question per agent, plus an `order` choice.
+ * `pick` returns `main`, one name, `{ names, order }`, or `{ steps }`.
+ * Names follow the `agents` array order.
+ * `{ names, order }` overrides `subagents.order` for that turn.
+ * `then`: agents that run after the other selected agents. The lead group
+ * starts together. The `then` agents then run one after another in list
+ * order, and each reads the text so far. Used only when the router picks at
+ * least one agent from each group. Otherwise `pick` returns `{ names, order }`.
+ */
+export function subagentRoute<
+  const TAgents extends ReadonlyArray<DefinedAgent>,
+>(agents: TAgents, options?: SubagentRouteOptions<TAgents>) {
+  const namesInList = new Set(agents.map((agent) => agent.name))
+  for (const agent of agents) {
+    if (agent.name === ORDER_KEY) {
+      throw new Error(
+        'subagentRoute cannot use an agent named "order". Rename that agent.',
+      )
+    }
+  }
+  for (const name of options?.then ?? []) {
+    if (!namesInList.has(name)) {
+      throw new Error(`subagentRoute then includes unknown agent "${name}".`)
+    }
+  }
+
+  const questions: Record<string, unknown> = {
+    order: choice({
+      instructions: 'When more than one agent runs, how must they run?',
+      options: {
+        parallel:
+          'Start them together. Use this when no agent must read text from another agent. Working on the same topic is not a reason to wait.',
+        sequence:
+          'Run them in agent-list order. Use this only when a later agent must read the earlier agent text, such as research notes and then a draft article.',
+      },
+    }),
+  }
+
+  for (const agent of agents) {
+    const when = options?.when?.[agent.name as TAgents[number]['name']]
+    questions[agent.name] = boolean({
+      instructions: when ?? agent.description,
+    })
+  }
+
+  function pick(result: RouteAnswers<TAgents>): SubagentRouterPick {
+    const names = agents
+      .map((agent) => agent.name)
+      .filter((name) => result[name as TAgents[number]['name']].value)
+    if (names.length === 0) return 'main'
+    const only = names.length === 1 ? names[0] : undefined
+    if (only !== undefined) return only
+    const later = new Set(options?.then ?? [])
+    const lead = names.filter((name) => !later.has(name))
+    const tail = names.filter((name) => later.has(name))
+    if (lead.length === 0 || tail.length === 0) {
+      return { names, order: result.order.value }
+    }
+    return {
+      steps: [
+        lead.length > 1
+          ? { names: lead, order: 'parallel' as const }
+          : { names: lead },
+        tail.length > 1
+          ? { names: tail, order: 'sequence' as const }
+          : { names: tail },
+      ],
+    }
+  }
+
+  return { questions: questions as RouteQuestions<TAgents>, pick }
+}