Class: SubAgent

TypeScript SDK reference

weave / SubAgent

A nested agent invocation — used when the current agent hands work to another named agent (e.g. a planner calling a researcher). Emits an invoke_agent span tagged with the sub-agent’s name and (optionally) its model.

Created by weave.startSubagent() (or turn.startAgent(), or llm.startAgent()) and terminated with end().

Example

const sub = weave.startSubagent({name: 'researcher', model: 'gpt-4o'});
try {
  // ... orchestrate the sub-agent's LLM/Tool calls ...
} finally {
  sub.end();
}

Hierarchy

• SpanBase

  ↳ SubAgent

Table of contents

Properties

• model
• name

Methods

• addEvent
• end
• setAttributes
• create

Properties

model

• Readonly model: string

Defined in

src/genai/subagent.ts:41

---

name

• Readonly name: string

Defined in

src/genai/subagent.ts:40

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 SubAgent 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/subagent.ts:72

---

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

---

create

▸ create(opts): SubAgent

Parameters

Name	Type
opts	SubAgentInit & ChildSpanContext

Returns

SubAgent

Defined in

src/genai/subagent.ts:46