Interface: GenerateTextResult
Defined in: packages/agentos/src/api/generateText.ts:1076
The completed result returned by generateText.
Extended by
Properties
agentCalls?
optionalagentCalls: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?
optionalcacheDiagnostics: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?
optionalfallback: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":maxTokenslimit reached."tool-calls": loop exhaustedmaxStepswhile 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?
optionalgrounding: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?
optionalguardReport: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?
optionalhistoryOmitted: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?
optionalmemoryRecall: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?
optionalparsed: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?
optionalplan: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?
optionalproviderMessageId: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?
optionalrefusal: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?
optionalresponseModel: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?
optionalserviceTier: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?
optionalservingProvider: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?
optionaltrace: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?
optionaltranscriptDelta: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.