Turn - Weights & Biases Documentation

An agent invocation. Typically wraps the work to respond to a single user message. Emits an invoke_agent span and acts as the root of the trace for that turn: it is always started under ROOT_CONTEXT so it never accidentally inherits a parent from another OTel-instrumented library. Created by weave.startTurn() (or conversation.startTurn()) and terminated with end(). Only one Turn may be active in an async chain. Children (LLM, Tool, SubAgent) attach via the startLLM, startTool, startSubagent methods. Defined in: src/genai/turn.ts:98

Examples

const turn = weave.startTurn();

try {
  const llm = turn.startLLM({model: 'gpt-4o', providerName: 'openai'});
  // ...
  llm.end();
} finally {
  turn.end();
}

const turn = weave.startTurn({
  model: 'gpt-4o',
  agentName: 'research-bot',
  agentId: 'research-bot-prod',
  agentDescription: 'Looks up facts on Wikipedia.',
  agentVersion: '1.4.2',
  userMessage: 'What is the weather in Tokyo?',
  systemInstructions: ['You are a helpful weather bot.'],
  startTime: new Date('2026-05-29T10:00:00.000Z'),
});

try {
  const llm = turn.startLLM({model: 'gpt-4o', providerName: 'openai'});
  // ...
  llm.end();
} finally {
  turn.end();
}

Extends

SpanBase

Accessors

agentName

Get Signature

get agentName(): string

Defined in: src/genai/turn.ts:111

Returns

string

model

Get Signature

get model(): string

Defined in: src/genai/turn.ts:115

Returns

string

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:84

Parameters

name

string

attributes?

Attributes

startTime?

TimeInput

Returns

this

Example

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

Inherited from

SpanBase.addEvent

end()

end(opts?): void

Read current field values (to reflect mutations made via record() since start) and close the span. Idempotent. Pass error to mark it as failed; pass endTime to backdate the close. Defined in: src/genai/turn.ts:257

Parameters

opts?

endTime?

TimeInput

error?

Error

Returns

void

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/turn.ts:213

Parameters

opts

agentDescription?

string

agentId?

string

agentName?

string

agentVersion?

string

messages?

Message[]

model?

string

outputMessages?

Message[]

systemInstructions?

string[]

Returns

this

setAttribute()

Deprecated. Use setAttributes instead, which mirrors the Python SDK’s set_attributes and OTel’s Span.setAttributes. Retained as a thin alias so existing single-attribute callers keep working. Only Turn carries this — the other emitters never shipped a singular form.

setAttribute(key, value): this

Defined in: src/genai/turn.ts:205

Parameters

key

string

value

AttributeValue

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:65

Parameters

attributes

Attributes

Returns

this

Example

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

Inherited from

SpanBase.setAttributes

startLLM()

startLLM(opts): LLM

Start a child LLM span under this Turn. Defined in: src/genai/turn.ts:170

Parameters

opts

LLMInit

Returns

LLM

startSubagent()

startSubagent(opts): SubAgent

Start a child SubAgent span under this Turn. Defined in: src/genai/turn.ts:190

Parameters

opts

SubAgentInit

Returns

SubAgent

startTool()

startTool(opts): Tool

Start a child Tool span under this Turn. Defined in: src/genai/turn.ts:180

Parameters

opts

ToolInit

Returns

Tool

​Examples

​Extends

​Accessors

​agentName

​Get Signature

Returns

​model

​Get Signature

Returns

​Methods

​addEvent()

​Parameters

name

attributes?

startTime?

​Returns

​Example

​Inherited from

​end()

​Parameters

opts?

endTime?

error?

​Returns

​record()

​Parameters

opts

agentDescription?

agentId?

agentName?

agentVersion?

messages?

model?

outputMessages?

systemInstructions?

​Returns

​setAttribute()

​Parameters

key

value

​Returns

​setAttributes()

​Parameters

attributes

​Returns

​Example

​Inherited from

​startLLM()

​Parameters

opts

​Returns

​startSubagent()

​Parameters

opts

​Returns

​startTool()

​Parameters

opts

​Returns

Examples

Extends

Accessors

agentName

Get Signature

model

Get Signature

Methods

addEvent()

Parameters

Returns

Example

Inherited from

end()

Parameters

Returns

record()

Parameters

Returns

setAttribute()

Parameters

Returns

setAttributes()

Parameters

Returns

Example

Inherited from

startLLM()

Parameters

Returns

startSubagent()

Parameters

Returns

startTool()

Parameters

Returns