Skip to main content
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.

Examples

Extends

  • SpanBase

Accessors

agentName

Get Signature

get agentName(): string
Returns
string

model

Get Signature

get model(): string
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.

Parameters

string
required
Attributes
TimeInput

Returns

this

Example

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.

Parameters

object

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.

Parameters

object
required

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

Parameters

string
required
AttributeValue
required

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

Parameters

Attributes
required

Returns

this

Example

Inherited from

SpanBase.setAttributes

startLLM()

startLLM(opts): LLM
Start a child LLM span under this Turn.

Parameters

LLMInit
required
See LLMInit.

Returns

LLM

startSubagent()

startSubagent(opts): SubAgent
Start a child SubAgent span under this Turn.

Parameters

SubAgentInit
required

Returns

SubAgent

startTool()

startTool(opts): Tool
Start a child Tool span under this Turn.

Parameters

ToolInit
required

Returns

Tool