Skip to main content

Interface: GenerateTextResult

Defined in: packages/agentos/src/api/generateText.ts:1076

The completed result returned by generateText.

Extended by​

Properties​

agentCalls?​

optional agentCalls: AgentCallRecord[]

Defined in: packages/agentos/src/api/generateText.ts:1164

Ordered records of every sub-agent call made during an agency() run. undefined for plain generateText / agent() calls.


cacheDiagnostics?​

optional cacheDiagnostics: CacheDiagnostics | null

Defined in: packages/agentos/src/api/generateText.ts:1122

Cache-diagnostics verdict from the LAST agentic step (Anthropic beta; present only when the run opted in via GenerateTextOptions.cacheDiagnostics). null = the last step's request matched its predecessor (prefix stable). A populated cacheMissReason names the earliest divergence. Per-step verdicts are available on the onAfterGeneration hook.


fallback?​

optional fallback: FallbackSignal

Defined in: packages/agentos/src/api/generateText.ts:1215

Per-hop provider fallback trail. fired is true when any non-primary provider produced — or was tried for — the result, so callers can flag a degraded run even when the final attempt recovered on the primary. undefined only on legacy code paths that predate the field.


finishReason​

finishReason: "error" | "length" | "stop" | "tool-calls"

Defined in: packages/agentos/src/api/generateText.ts:1148

Reason the model stopped generating.

  • "stop": natural end of response.
  • "length": maxTokens limit reached.
  • "tool-calls": loop exhausted maxSteps while still calling tools.
  • "error": provider returned an error.

An answer the model refused keeps the reason it reports here ("stop", or "length" when the output cap cut the refusal message off) and carries the message in GenerateTextResult.refusal.


grounding?​

optional grounding: VerifiedResponse

Defined in: packages/agentos/src/api/generateText.ts:1188

Per-claim citation verdicts attached when agent({ verifyCitations: … }) is configured. undefined when verification was not requested or could not run for this turn.

See​

VerifyCitationsConfig (exported from @framers/agentos/api) for the verifyCitations options.


guardReport?​

optional guardReport: TextGuardrailReport

Defined in: packages/agentos/src/api/generateText.ts:1217

With guards: what each stage's guards answered, as codes and ids, and whether the reply passed, was rewritten or was replaced.


historyOmitted?​

optional historyOmitted: PromptHistoryOmission

Defined in: packages/agentos/src/api/generateText.ts:1208

On a gmi() or agent({ runtime: 'gmi' }) session's turn: the conversation history the turn's requests left out to fit the prompt engine's history budget (35 percent of the serving model's context window). messages counts the oldest messages left out of the request that left out the most, tokens is their size at the prompt engine's estimate; the session's messages() still lists them. undefined when every request of the turn carried the whole history, and on the default runtime, which sends the whole history.


memoryRecall?​

optional memoryRecall: MemoryRecallCapture

Defined in: packages/agentos/src/api/generateText.ts:1197

On a gmi() or agent({ runtime: 'gmi' }) session's turn with cognitive memory: the recall capture of the model hop that served the turn (every candidate with its ranks, scores and outcome, the legs, the reranker, the hop's budget and delivery, and the timings; never a memory's text or the query's). undefined when the turn assembled no memory block or the manager's recall.capture is 'off'.


model​

model: string

Defined in: packages/agentos/src/api/generateText.ts:1091

Resolved model identifier used for the run.


parsed?​

optional parsed: unknown

Defined in: packages/agentos/src/api/generateText.ts:1174

Parsed structured output from BaseAgentConfig.output, or from agent().generate() with responseSchema. Undefined without a schema.


plan?​

optional plan: Plan

Defined in: packages/agentos/src/api/generateText.ts:1179

The plan produced by the planning phase when planning is enabled. undefined when planning is disabled or was not requested.


provider​

provider: string

Defined in: packages/agentos/src/api/generateText.ts:1089

Provider identifier used for the final run.


providerMessageId?​

optional providerMessageId: string | null

Defined in: packages/agentos/src/api/generateText.ts:1130

Provider message id (msg_...) of the LAST agentic step; present only when the run opted in via GenerateTextOptions.cacheDiagnostics. Persist it and pass it back as the next request's cacheDiagnostics.previousMessageId to thread the comparison across turns. null when the provider reported no id.


refusal?​

optional refusal: string

Defined in: packages/agentos/src/api/generateText.ts:1159

The model's refusal message when it declined the request with one (OpenAI's refusal): present only when the model refused, and possibly the empty string. text is empty then, unless the model wrote text beside the message in the same reply: text keeps that text. finishReason is 'stop' beside a whole message, and 'length' when the output cap cut the message off, with the piece that came here. Read this field to tell a refusal from an empty answer. Set by generateText(); other surfaces that return this shape may leave it unset.


responseModel?​

optional responseModel: string

Defined in: packages/agentos/src/api/generateText.ts:1098

Provider-reported model id of the final step (spec batch-1 C1) — can differ from model across aliases and fallback routing. Undefined on paths where no provider-reported id was captured. model keeps its existing meaning (zero-change).


serviceTier?​

optional serviceTier: string

Defined in: packages/agentos/src/api/generateText.ts:1104

Provider-reported service tier the final step actually ran at (OpenAI service_tier on the response; spec batch-1 C2). Undefined on providers/paths without a tier concept.


servingProvider?​

optional servingProvider: string

Defined in: packages/agentos/src/api/generateText.ts:1113

Upstream host that actually served the request when provider is an aggregator/router (OpenRouter reports e.g. 'Groq' or 'DeepInfra' per completion). Undefined for direct providers, for aggregators that omit it, and on the prompt-shim tool path. Latency attribution: identical model + token counts vary 3-5x in wall-clock by serving host, so telemetry needs this to interpret durations.


text​

text: string

Defined in: packages/agentos/src/api/generateText.ts:1132

Final assistant text after all agentic steps have completed.


toolCalls​

toolCalls: ToolCallRecord[]

Defined in: packages/agentos/src/api/generateText.ts:1136

Ordered list of every tool call made during the run.


trace?​

optional trace: AgencyTraceEvent[]

Defined in: packages/agentos/src/api/generateText.ts:1169

Structured trace events emitted during the run. Populated by the agency orchestrator; undefined for single-agent calls.


transcriptDelta?​

optional transcriptDelta: SessionTranscriptMessage[]

Defined in: packages/agentos/src/api/generateText.ts:1087

Lossless message delta this call appended to the conversation: the request's user turn plus every assistant / tool turn the tool loop recorded, in order, in provider-replayable shape (tool_call ids, parallel results, thinking blocks). Sessions append THIS — never a reconstruction — to their history. Absent only on legacy paths that never seeded a conversation array. The prompt-shim path carries a partial delta (seeded turns only); native providers carry the full trail.


usage​

usage: TokenUsage

Defined in: packages/agentos/src/api/generateText.ts:1134

Aggregated token usage across all steps.