LLM

TypeScript SDK reference

An LLM call. Emits a chat span with gen_ai.* attributes.

Created by weave.startLLM() (or turn.startLLM()) and terminated with end(). Only one LLM may be active in an async context at a time; nest tool/subagent calls under it via startTool / startSubagent.

Populate inputMessages / outputMessages / usage / reasoning directly, or via the helper functions (output, think, attachMedia, record).

All recorded data is flushed to the span at end().

Defined in: src/genai/llm.ts:86

Examples

const llm = weave.startLLM({model: 'gpt-4o-mini', providerName: 'openai'});

try {
  llm.inputMessages = [{role: 'user', content: prompt}];
  const resp = await openai.chat.completions.create({...});
  llm.output(resp.choices[0].message.content ?? '');
  llm.record({usage: {inputTokens: resp.usage?.prompt_tokens}});
} finally {
  llm.end();
}

const llm = weave.startLLM({
  model: 'gpt-4o-mini',
  providerName: 'openai',
  systemInstructions: ['You are a helpful weather bot.'],
  startTime: new Date('2026-05-29T10:00:00.000Z'),
});

try {
  // ... call the LLM, populate llm.outputMessages / usage ...
} finally {
  llm.end();
}

Extends

• SpanBase

Properties

inputMessages

inputMessages: Message[] = []

Input messages sent to the model. Flushed to gen_ai.input.messages on end().

Defined in: src/genai/llm.ts:93

---

model

readonly model: string

Defined in: src/genai/llm.ts:117

---

outputMessages

outputMessages: Message[] = []

Assistant messages returned by the model. Flushed to gen_ai.output.messages on end().

Defined in: src/genai/llm.ts:98

---

providerName

readonly providerName: string

Defined in: src/genai/llm.ts:118

---

reasoning

optional reasoning: Reasoning

Chain-of-thought content. Folded into the last assistant message as a ReasoningPart at serialization time.

Defined in: src/genai/llm.ts:105

---

usage

usage: Usage = {}

Token counts and cache stats. Flushed to gen_ai.usage.* on end().

Defined in: src/genai/llm.ts:100

Methods

addEvent()

Deprecated. Record this data via setAttributes instead. OpenTelemetry is phasing out the Span Event API (Span.addEvent). This method still works and existing span-event data stays valid. See https://opentelemetry.io/blog/2026/deprecating-span-events/

addEvent(name, attributes?, startTime?): this

Add a named event to the span. Useful for marking non-span moments such as context compaction, tool-loop detection, or guardrail trips. Warns and no-ops after end(). Mirrors OTel Span.addEvent.

Defined in: src/genai/spanBase.ts:82

Parameters

name

string

attributes?

Attributes

startTime?

TimeInput

Returns

this

Example

span.addEvent('context_compacted', {removedMessages: 12});

Inherited from

SpanBase.addEvent

---

attachMedia()

attachMedia(opts): this

Stage a media attachment for the LLM call. Pick exactly one of content (inline base64 bytes), uri (URI reference), or fileId (pre-uploaded file id). The attachment is glued onto the last user message in inputMessages on end().

Defined in: src/genai/llm.ts:183

Parameters

opts

AttachMediaOpts

Returns

this

---

attachMediaUrl()

attachMediaUrl(url, opts): this

Convenience for attachMedia({uri, modality}).

Defined in: src/genai/llm.ts:192

Parameters

url

string

opts

modality

Modality

Returns

this

---

end()

end(opts?): void

Flush accumulated state and close the span. Idempotent. Pass error to mark failed; pass endTime to backdate the close.

Defined in: src/genai/llm.ts:274

Parameters

opts?

SpanEndOptions

Returns

void

---

output()

output(content): this

Append an assistant message to the response.

Defined in: src/genai/llm.ts:155

Parameters

content

string

Returns

this

---

record()

record(opts): this

Bulk-set any subset of the mutable fields. Replaces (does not merge). Useful for assigning everything at once after a provider call returns.

Defined in: src/genai/llm.ts:203

Parameters

opts

finishReasons?

string[]

inputMessages?

Message[]

mediaAttachments?

AttachMediaOpts[]

outputMessages?

Message[]

outputType?

string

reasoning?

Reasoning

responseId?

string

responseModel?

string

usage?

Usage

Returns

this

---

setAttributes()

setAttributes(attributes): this

Set multiple attributes on the span at once. Warns and no-ops after end(). Mirrors OTel Span.setAttributes (and the Python SDK’s set_attributes).

Defined in: src/genai/spanBase.ts:63

Parameters

attributes

Attributes

Returns

this

Example

span.setAttributes({'weave.tag': 'prod', 'gen_ai.response.id': id});

Inherited from

SpanBase.setAttributes

---

startSubagent()

startSubagent(opts): SubAgent

Start a child SubAgent span nested under this LLM.

Defined in: src/genai/llm.ts:261

Parameters

opts

SubAgentInit

Returns

SubAgent

---

startTool()

startTool(opts): Tool

Start a child Tool span nested under this LLM.

Defined in: src/genai/llm.ts:252

Parameters

opts

ToolInit

Returns

Tool

---

think()

think(content): this

Set or extend the model’s reasoning/chain-of-thought content. Accumulates into this.reasoning.content. Folded into the last assistant message as a ReasoningPart at serialization time, matching the Python SDK’s on-the-wire shape.

Defined in: src/genai/llm.ts:167

Parameters

content

string

Returns

this