Class: Turn

TypeScript SDK reference

weave / Turn

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.

Example

const turn = weave.startTurn({agentName: 'research-bot', model: MODEL});
try {
  const llm = turn.startLLM({model: MODEL, providerName: 'openai'});
  // ...
  llm.end();
} finally {
  turn.end();
}

Hierarchy

• SpanBase

  ↳ Turn

Table of contents

Properties

• agentName
• model

Methods

• addEvent
• end
• setAttribute
• setAttributes
• startLLM
• startSubagent
• startTool
• create

Properties

agentName

• Readonly agentName: string

Defined in

src/genai/turn.ts:57

---

model

• Readonly model: string

Defined in

src/genai/turn.ts:58

Methods

addEvent

▸ 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.

Parameters

Name	Type
name	string
attributes?	Attributes
startTime?	TimeInput

Returns

this

Example

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

Inherited from

SpanBase.addEvent

Defined in

src/genai/spanBase.ts:77

---

end

▸ end(opts?): void

Close the Turn span. Idempotent. Pass error to mark it as failed; pass endTime to backdate the close.

Parameters

Name	Type
opts?	SpanEndOptions

Returns

void

Defined in

src/genai/turn.ts:144

---

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

Parameters

Name	Type
key	string
value	AttributeValue

Returns

this

Defined in

src/genai/turn.ts:136

---

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).

Parameters

Name	Type
attributes	Attributes

Returns

this

Example

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

Inherited from

SpanBase.setAttributes

Defined in

src/genai/spanBase.ts:63

---

startLLM

▸ startLLM(opts): LLM

Start a child LLM span under this Turn.

Parameters

Name	Type
opts	LLMInit

Returns

LLM

Defined in

src/genai/turn.ts:104

---

startSubagent

▸ startSubagent(opts): SubAgent

Start a child SubAgent span under this Turn.

Parameters

Name	Type
opts	SubAgentInit

Returns

SubAgent

Defined in

src/genai/turn.ts:122

---

startTool

▸ startTool(opts): Tool

Start a child Tool span under this Turn.

Parameters

Name	Type
opts	ToolInit

Returns

Tool

Defined in

src/genai/turn.ts:113

---

create

▸ create(opts?): Turn

Parameters

Name	Type
opts	TurnInit & { conversationId?: string }

Returns

Turn

Defined in

src/genai/turn.ts:63