generateText

generateText runs a model to completion and resolves once. It is the buffered counterpart to streamChat: the same orchestration (retry, timeout, the canonical delta stream, the agentic loop), but it accumulates every delta for you and hands back a plain object.

When to use it

Reach for generateText when:

• Nobody is watching the output arrive — a background job, a cron task, a classification step inside a larger pipeline.
• You need the whole answer before you can do anything with it (parse it, branch on it, store it).
• You are running an agent whose steps matter more than its tokens, and you will render a summary at the end.
• You want the simplest possible error handling: it is a Promise, so try/catch works.

Reach for streamChat instead when:

• A human is waiting. Time-to-first-token is the number they feel; generateText has none by definition.
• You want live tool-call, reasoning, cost or approval events as they happen.
• You are on a serverless platform with a short response budget and want to start writing bytes early.

Everything else is the same. The two share CommonCallOptions, the same registry, the same retry and timeout policy, and — with tools — the same loop semantics. Switching between them is a one-word change.

Signature

import { generateText } from '@deuz-sdk/core';

const result = await generateText(options);

generateText is async and returns a Promise<GenerateTextResult>. Unlike streamChat, errors reject the promise — wrap the call in try/catch. That asymmetry is deliberate: a promise already has a failure channel, so there is no reason to invent one. See Error handling.

Options

generateText takes the same CommonCallOptions as every other call. The ones you will actually reach for:

Agentic options

These only do anything once tools is present (or one of the other loop-routing options — chat, memory, verifyStep, doneWhen, guardrails, mcp — pulls the call into the loop).

Result shape

interface GenerateTextResult {
  text: string;
  usage: Usage;
  finishReason: FinishReason;
  response: { messages: Message[] };
  steps?: StepResult[];
  toolCalls?: ToolCall[];
  toolResults?: ToolResult[];
  pendingApprovals?: ToolApprovalRequest[];
  warnings?: CallWarning[];
  providerMetadata?: Record<string, Record<string, unknown>>;
  runId?: string;
  memory?: Promise<MemoryMutation[]>;
  observation?: { settled: Promise<void> };
}

A single buffered turn

With no tools, steps / toolCalls / toolResults are absent and exactly one model call happens.

import { generateText } from '@deuz-sdk/core';
import { createAnthropic } from '@deuz-sdk/core/anthropic';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const { text, usage, finishReason } = await generateText({
  model: anthropic('claude-opus-4-8'),
  prompt: 'Name three primary colors.',
});

console.log(text);
console.log(finishReason); // 'stop'
console.log(usage.totalTokens);

With tools (the agentic loop)

Add tools and generateText becomes the loop: call the model, execute any tool calls in parallel (capped by maxToolConcurrency), feed the results back as a new turn, repeat. A thrown execute is caught and fed back as an error tool result — it never rejects the promise.

import { generateText } from '@deuz-sdk/core';
import { createAnthropic } from '@deuz-sdk/core/anthropic';
import { z } from 'zod';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const { text, steps } = await generateText({
  model: anthropic('claude-opus-4-8'),
  prompt: 'What is the weather in Paris?',
  maxSteps: 5, // WITHOUT THIS the loop runs one turn and `text` is empty
  tools: {
    getWeather: {
      description: 'Get the current weather for a city.',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 22, sky: 'sunny' }),
    },
  },
});

console.log(text);            // final natural-language answer
console.log(steps?.length);   // e.g. 2: one tool turn + one final turn

Zod is optional. A raw JSON Schema works with no extra dependency at all:

const tools = {
  getWeather: {
    description: 'Get the current weather for a city.',
    parameters: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
      additionalProperties: false,
    },
    execute: async (args: { city: string }) => ({ city: args.city, tempC: 22 }),
  },
} as const;

For argument types that flow into execute without a cast, wrap the definition in tool().

Step array anatomy

result.steps is a StepResult[] — one entry per model turn, in order.

interface StepResult {
  stepType: 'initial' | 'tool-result';
  text: string;
  reasoningText?: string;
  toolCalls: ToolCall[];
  toolResults: ToolResult[];
  finishReason: FinishReason;
  usage: Usage;
  response: { messages: Message[] };
}

The first step is 'initial'; every step produced by feeding tool results back is 'tool-result'. A step with empty toolCalls is the loop's last step. usage on each step is that step alone; result.usage is the sum.

import { generateText } from '@deuz-sdk/core';
import { createAnthropic } from '@deuz-sdk/core/anthropic';
import { z } from 'zod';

const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY! });

const result = await generateText({
  model: anthropic('claude-opus-4-8'),
  prompt: 'Weather in Paris and Berlin?',
  maxSteps: 5,
  tools: {
    getWeather: {
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ city, tempC: 22 }),
    },
  },
  onStepFinish: (step) => {
    console.log(`[${step.stepType}] ${step.toolCalls.length} tool call(s)`);
  },
});

for (const step of result.steps ?? []) {
  for (const call of step.toolCalls) {
    console.log('called', call.toolName, 'with', call.args);
  }
  for (const r of step.toolResults) {
    console.log('result', r.toolName, r.isError ? '(error)' : '', r.result);
  }
}

Stopping early

stopWhen adds predicate(s) OR-ed with maxSteps. Because they are OR-ed, stopWhen can only make the run shorter; it never extends the step budget.

Five ready-made conditions ship from the package root, so you rarely need to write your own:

import { stepCountIs, totalTokensExceed } from '@deuz-sdk/core';

// Stop at 10 steps or once accumulated usage crosses 50k tokens.
const result = await generateText({
  model: anthropic('claude-opus-4-8'),
  prompt: 'Plan my trip.',
  stopWhen: [stepCountIs(10), totalTokensExceed(50_000)],
  tools: { /* … */ },
});

budget is the same machinery with a friendlier shape and a readable marker:

const result = await generateText({
  model: anthropic('claude-opus-4-8'),
  prompt: 'Research this thoroughly.',
  maxSteps: 20,
  budget: { usd: 0.5, tokens: 200_000 },
  tools: { /* … */ },
});

// 'budget.usd' | 'budget.tokens' | 'totalTokensExceed' | … | undefined when it ended naturally
console.log(result.providerMetadata?.deuz?.stoppedBy);

Custom conditions are plain functions and may be async:

import type { StopCondition } from '@deuz-sdk/core';

// Stop as soon as a step has produced final text (no tool calls).
const untilFinalText: StopCondition = ({ steps }) =>
  (steps.at(-1)?.toolCalls.length ?? 0) === 0;

const result = await generateText({
  model: anthropic('claude-opus-4-8'),
  prompt: 'Plan my trip.',
  maxSteps: 8,
  stopWhen: untilFinalText,
  tools: { /* … */ },
});

Continuing a conversation

response.messages holds only the new turns. Append them; never mutate the array you passed in — stable history is what makes provider prompt-cache hits possible.

import type { Message } from '@deuz-sdk/core';

let messages: Message[] = [{ role: 'user', content: 'Weather in Paris?' }];

const first = await generateText({
  model: anthropic('claude-opus-4-8'),
  messages,
  maxSteps: 5,
  tools: { /* … */ },
});

messages = [...messages, ...first.response.messages];
// next turn reuses the full, stable history (prompt-cache friendly)

Approving tool calls

A tool marked needsApproval is gated before it runs. Two modes, and which one you get depends only on whether you passed approveToolCall:

• Server mode (approveToolCall supplied) — the loop asks your function per gated call and runs it only on true. Returning false or throwing denies it; the denial becomes an is_error tool result and the loop continues. Use this when policy lives on the server.
• Client mode (no approveToolCall) — the gated call breaks the loop and comes back in result.pendingApprovals. Collect verdicts from your user, then call generateText again with the appended history plus approvalResponses. Any pending call without a matching response is denied by default — the safe side.

Error handling

import { generateText, RateLimitError, ContextOverflowError, APICallError } from '@deuz-sdk/core';

try {
  const { text } = await generateText({ model, prompt: 'hi' });
} catch (err) {
  if (err instanceof RateLimitError) console.log('retry after (ms):', err.retryAfterMs);
  else if (err instanceof ContextOverflowError) { /* trim history and retry */ }
  else if (err instanceof APICallError) console.error(err.provider, err.statusCode, err.requestId);
  else throw err;
}

Two things that do not reject:

• A tool that throws. It becomes an is_error tool result fed back to the model, which is usually able to recover. Look for toolResults[i].isError.
• A user abort. It resolves with finishReason: 'aborted' and whatever partial usage accumulated. A TimeoutError, by contrast, rejects — see Abort vs timeout.

Loop guarantees

The loop is self-healing and bounded. The invariants that matter here:

• Client tools (a key present in tools with no execute) cannot be auto-run — the loop stops and returns them in toolCalls so the caller owns the round-trip.
• An unregistered tool name is not a client tool (1.9): a hallucinated name self-heals into an is_error tool_result listing the real tool names, and the loop continues rather than breaking out with a dangling tool_use.
• Runaway guard: the same tool erroring on three consecutive steps hard-stops the loop. Unknown-tool errors and tool timeouts count toward it; approval denials do not.
• Stop on tool count, not finishReason: the loop continues whenever the last step emitted tool calls, even when the provider reported finish: stop. This is a live-verified Gemini behaviour, not a hypothetical.

For the full anatomy — the exact per-step ordering, immutable history, parallel execution, and every guard — see the tool loop reference.

What generateText does not do

• No partial output. If the run fails mid-generation, you get an exception, not the tokens that already arrived. Use streamChat if partial output has value to you.
• No consume() and no lazy start. It is a promise; calling it is starting it.
• No live events. onStepFinish and onUsage are the only progress hooks; there is no per-token callback. streamChat's fullStream is the event channel.
• No structured-output validation. responseFormat: 'json' asks for JSON; it does not check it. Use generateObject for a schema-validated result with a repair retry.

See also

• streamChat — the streaming counterpart; same orchestration, token-by-token output.
• Tool loop — the agentic loop's step-by-step anatomy.
• generateObject — buffered structured output validated against a schema.
• Prompts, instructions & timeouts — the call-shape options in full.
• Error handling — the taxonomy this call rejects with.