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 session.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();
}

Table of contents

Properties

• agentName
• model

Methods

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

Properties

agentName

• Readonly agentName: string

Defined in

genai/turn.ts:60

---

model

• Readonly model: string

Defined in

genai/turn.ts:61

Methods

addEvent

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

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

Parameters

Name	Type
name	string
attributes?	Attributes
startTime?	TimeInput

Returns

this

Example

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

Defined in

genai/turn.ts:152

---

end

▸ end(opts?): void

Close the Turn span. Idempotent. Pass error to mark it as failed.

Parameters

Name	Type
opts?	Object
opts.error?	Error

Returns

void

Defined in

genai/turn.ts:159

---

setAttribute

▸ setAttribute(key, value): this

Set a single attribute on the Turn span. Useful for stamping running totals (e.g. cumulative cost, token usage) or other metadata that becomes known mid-turn. No-op after end(). Mirrors OTel Span.setAttribute.

Parameters

Name	Type
key	string
value	AttributeValue

Returns

this

Example

turn.setAttribute('gen_ai.usage.input_tokens', totalInputTokens);

Defined in

genai/turn.ts:138

---

startLLM

▸ startLLM(opts): LLM

Start a child LLM span under this Turn.

Parameters

Name	Type
opts	LLMInit

Returns

LLM

Defined in

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

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

genai/turn.ts:113

---

create

▸ create(opts?): Turn

Parameters

Name	Type
opts	TurnInit & { conversationId?: string }

Returns

Turn

Defined in

genai/turn.ts:64