From cdb98444509d66976b9094443e6a9c06cbe0d348 Mon Sep 17 00:00:00 2001
From: drtangible <dgilbert@coreweave.com>
Date: Tue, 7 Jul 2026 15:21:35 -0500
Subject: [PATCH] docs: Update TS examples to prefer calling startTurn,
 startLLM, startTool, etc. on parent instance.

---
 weave/custom-agents-quickstart.mdx                |  6 +++---
 weave/guides/tracking/trace-agents-attributes.mdx |  2 +-
 weave/guides/tracking/trace-agents.mdx            | 12 ++++++------
 3 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/weave/custom-agents-quickstart.mdx b/weave/custom-agents-quickstart.mdx
index 41e3e2d419..15512bed14 100644
--- a/weave/custom-agents-quickstart.mdx
+++ b/weave/custom-agents-quickstart.mdx
@@ -247,7 +247,7 @@ async function runTurn(history: any[], userMessage: string): Promise<string | nu
   const turn = weave.startTurn({ model: MODEL });
   try {
     // LLM call 1: the model might decide to use a tool.
-    const llm1 = weave.startLLM({ model: MODEL, providerName: 'openai' });
+    const llm1 = turn.startLLM({ model: MODEL, providerName: 'openai' });
     let msg;
     try {
       const resp = await openaiClient.chat.completions.create({
@@ -274,7 +274,7 @@ async function runTurn(history: any[], userMessage: string): Promise<string | nu
     // Execute each requested tool call.
     for (const tc of msg.tool_calls) {
       if (tc.type !== 'function') continue;
-      const tool = weave.startTool({
+      const tool = turn.startTool({
         name: tc.function.name,
         args: tc.function.arguments,
         toolCallId: tc.id,
@@ -289,7 +289,7 @@ async function runTurn(history: any[], userMessage: string): Promise<string | nu
     }
 
     // LLM call 2: synthesize the final answer.
-    const llm2 = weave.startLLM({ model: MODEL, providerName: 'openai' });
+    const llm2 = turn.startLLM({ model: MODEL, providerName: 'openai' });
     try {
       const resp = await openaiClient.chat.completions.create({
         model: MODEL,
diff --git a/weave/guides/tracking/trace-agents-attributes.mdx b/weave/guides/tracking/trace-agents-attributes.mdx
index 025874aff0..fcb525ce83 100644
--- a/weave/guides/tracking/trace-agents-attributes.mdx
+++ b/weave/guides/tracking/trace-agents-attributes.mdx
@@ -41,7 +41,7 @@ import * as weave from 'weave';
 await weave.init('[TEAM-NAME]/[PROJECT-NAME]');
 
 const conversation = weave.startConversation({ agentName: 'my-agent' });
-const turn = weave.startTurn({ agentName: 'my-agent' });
+const turn = conversation.startTurn({ agentName: 'my-agent' });
 
 // Stamp attributes on this turn span
 turn.setAttributes({ user_id: '12345', tenant: 'acme', env: 'production' });
diff --git a/weave/guides/tracking/trace-agents.mdx b/weave/guides/tracking/trace-agents.mdx
index e03112c523..3194b397f2 100644
--- a/weave/guides/tracking/trace-agents.mdx
+++ b/weave/guides/tracking/trace-agents.mdx
@@ -390,7 +390,7 @@ try {
   const turn = conversation.startTurn({ agentName: 'weather-bot' });
   try {
     // First LLM call: returns a tool call.
-    const llm = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
+    const llm = turn.startLLM({ model: 'gpt-4o', providerName: 'openai' });
     try {
       llm.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
       llm.think('User wants weather data, I should call get_weather.');
@@ -398,7 +398,7 @@ try {
       llm.usage = { inputTokens: 100, outputTokens: 20 };
 
       // Tool call: child of the LLM call that requested it.
-      const tool = weave.startTool({ name: 'get_weather', args: '{"city":"Tokyo"}' });
+      const tool = llm.startTool({ name: 'get_weather', args: '{"city":"Tokyo"}' });
       try {
         tool.result = await getWeatherApi('Tokyo');  // Returns "24°C, sunny".
       } finally {
@@ -409,7 +409,7 @@ try {
     }
 
     // Second LLM call: synthesizes the final answer.
-    const llm2 = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
+    const llm2 = turn.startLLM({ model: 'gpt-4o', providerName: 'openai' });
     try {
       llm2.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
       llm2.output('It is 24°C and sunny in Tokyo today.');
@@ -467,18 +467,18 @@ conversation.end()
 const conversation = weave.startConversation({ agentName: 'weather-bot' });
 const turn = conversation.startTurn({ agentName: 'weather-bot' });
 
-const llm = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
+const llm = turn.startLLM({ model: 'gpt-4o', providerName: 'openai' });
 llm.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
 llm.output('Let me check.');
 llm.usage = { inputTokens: 100, outputTokens: 20 };
 
-const tool = weave.startTool({ name: 'get_weather', args: '{"city": "Tokyo"}' });
+const tool = llm.startTool({ name: 'get_weather', args: '{"city": "Tokyo"}' });
 tool.result = '24°C, sunny';
 tool.end();  // end() is idempotent: safe to call more than once.
 
 llm.end();
 
-const llm2 = weave.startLLM({ model: 'gpt-4o', providerName: 'openai' });
+const llm2 = turn.startLLM({ model: 'gpt-4o', providerName: 'openai' });
 llm2.output('It is 24°C and sunny in Tokyo.');
 llm2.usage = { inputTokens: 150, outputTokens: 30 };
 llm2.end();