feat: Added tutorial and warnings for langchain orchestration template by BrigittaK307 · Pull Request #572 · SAP/ai-sdk

BrigittaK307 · 2026-07-09T10:51:48Z

Related to https://github.com/orgs/SAP/projects/111/views/1?pane=issue&itemId=141534346&issue=SAP%7Cai-sdk-js-backlog%7C438

davidkna-sap · 2026-07-10T14:32:43Z

+id: langgraph-orchestration-client
+title: Using Orchestration Client in LangGraph Workflows
+sidebar_label: Orchestration Client in LangGraph


Suggested change

id: langgraph-orchestration-client

title: Using Orchestration Client in LangGraph Workflows

sidebar_label: Orchestration Client in LangGraph

id: langgraph-template-orchestration-client

title: Using Orchestration Templates in LangGraph Agents

sidebar_label: Using Orchestration Templates in LangGraph Agents

davidkna-sap · 2026-07-10T14:33:47Z

+  }
+});
+```
+


[pp] As a tutorial, I would prefer if there was something e.g. at the bottom for both that shows how to combine these into an actual LangGraph (or maybe createAgent()...)

…325-438

davidkna-sap · 2026-07-15T15:04:57Z

+:::warning
+When using `template`, its messages are **always prepended** to every `invoke()` or `stream()` call — reusing the same client across multiple turns causes the template to appear on every request.
+When using `template_ref`, any messages passed are **automatically routed to `messages_history`** and cannot be merged into the remotely stored template.
+In both cases, use the **two-client pattern** from the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client): one client with the template for the first turn, a second without it for follow-up turns.
+:::


Suggested change

:::warning

When using `template`, its messages are **always prepended** to every `invoke()` or `stream()` call — reusing the same client across multiple turns causes the template to appear on every request.

When using `template_ref`, any messages passed are **automatically routed to `messages_history`** and cannot be merged into the remotely stored template.

In both cases, use the **two-client pattern** from the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client): one client with the template for the first turn, a second without it for follow-up turns.

:::

When using `template`, its messages are **always prepended** to every `invoke()` or `stream()` call — reusing the same client across multiple turns causes the template to appear on every request.

When using `template_ref`, any messages passed are **automatically routed to `messages_history`** and cannot be merged into the remotely stored template.

In both cases, you can use the **two-client pattern** from the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) to avoid related issues while taking advantage of the prompt registry: one client with the template for the first turn, a second without it for follow-up turns.

davidkna-sap · 2026-07-15T15:07:00Z

+  .addConditionalEdges(START, routeByTurn, [
+    'firstTurnNode',
+    'conversationNode'
+  ])
+  .addEdge('firstTurnNode', END)
+  .addEdge('conversationNode', END)


[pp] I think there should be edge from START -> firstTurnNode -> conversationNode with a conditional edge from conversationNode to itself or END (in this case perhaps just END).

The graph re-enters from START on every graph.invoke() call. Adapting the firstTurnNode → conversationNode case would cause both nodes to fire on turn 1, making two LLM calls instead of one.

davidkna-sap · 2026-07-15T15:08:09Z

-When using the `template_ref` property, messages passed to the `chatCompletion()` or `stream()` methods are automatically appended to the `messages_history` array as they cannot be merged into the stored prompt template.
-The `messages` property defined in the `template` array are appended after any existing `messagesHistory` entries.
+:::warning
+Messages passed alongside a `template_ref` are **automatically routed to `messages_history`** and cannot be merged into the remotely stored template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows.


Suggested change

Messages passed alongside a `template_ref` are **automatically routed to `messages_history`** and cannot be merged into the remotely stored template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows.

Messages passed alongside a `template_ref` are **automatically routed to `messages_history`** and cannot be merged into the remotely stored template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows with template references.

davidkna-sap · 2026-07-15T15:08:41Z

-When initializing the client with an orchestration configuration reference, any messages passed to the `chatCompletion()` or `stream()` methods are automatically appended to the `messages_history` array as they cannot be merged into the stored configuration's prompt template.
-The `messages` property defined in the `template` array are appended after any existing `messagesHistory` entries.
+:::warning
+Messages passed alongside a configuration reference are **automatically routed to `messages_history`** and cannot be merged into the remotely stored configuration's prompt template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows.


Suggested change

Messages passed alongside a configuration reference are **automatically routed to `messages_history`** and cannot be merged into the remotely stored configuration's prompt template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows.

Messages passed alongside a configuration reference are **automatically routed to `messages_history`** and cannot be merged into the remotely stored configuration's prompt template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows with configuration references.

davidkna-sap · 2026-07-15T15:09:03Z

-The `promptTemplating.prompt.template` messages defined in the client configuration are static - they are always included in every `chatCompletion()` request.
-For more dynamic prompts, i.e., you want to vary the full message list per request without re-initializing the client, use the `messages` property instead.
+:::warning
+Template messages are **always prepended** to every request. Reusing the same client across multiple turns will include the template on every call. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for how to avoid duplication in multi-turn workflows.


Suggested change

Template messages are **always prepended** to every request. Reusing the same client across multiple turns will include the template on every call. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for how to avoid duplication in multi-turn workflows.

Template messages are **always prepended** to every request. Reusing the same client across multiple turns will include the template on every call. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for how to avoid duplication in multi-turn workflows with prompt templates.

davidkna-sap · 2026-07-20T06:52:23Z

+const agent = createAgent({
+  model: clientWithTemplate,
+  tools: [],
+  checkpointSaver: new MemorySaver()


Suggested change

checkpointSaver: new MemorySaver()

checkpointer: new MemorySaver()

BrigittaK307 and others added 2 commits July 9, 2026 13:50

Added tutorial and warnings for langchaing orchestration client usage

d870bdd

fix: Changes from lint

d0040ed

davidkna-sap reviewed Jul 10, 2026

View reviewed changes

BrigittaK307 and others added 4 commits July 13, 2026 14:10

Added tutorial with createAgent() and StateGraph

1361a7d

Merge branch 'I753325-438' of https://github.com/SAP/ai-sdk into I753…

b03bd89

…325-438

fix: Changes from lint

75828b5

Merge branch 'main' into I753325-438

79ad09f

davidkna-sap reviewed Jul 15, 2026

View reviewed changes

davidkna-sap reviewed Jul 20, 2026

View reviewed changes

BrigittaK307 and others added 3 commits August 5, 2026 10:18

Merge branch 'main' into I753325-438

c1ff041

Fixed PR comments and added windows support for docs config

1f607ba

fix: Changes from lint

ecbbc6d

BrigittaK307 requested a review from davidkna-sap August 5, 2026 08:48

Navigation Menu

Uh oh!

feat: Added tutorial and warnings for langchain orchestration template - #572

feat: Added tutorial and warnings for langchain orchestration template#572
BrigittaK307 wants to merge 9 commits into
mainfrom
I753325-438

BrigittaK307 commented Jul 9, 2026 •

edited

Loading

Uh oh!

davidkna-sap Jul 10, 2026

Uh oh!

davidkna-sap Jul 10, 2026

Uh oh!

davidkna-sap Jul 15, 2026

Uh oh!

davidkna-sap Jul 15, 2026

Uh oh!

BrigittaK307 Aug 5, 2026

Uh oh!

davidkna-sap Jul 15, 2026

Uh oh!

davidkna-sap Jul 15, 2026

Uh oh!

davidkna-sap Jul 15, 2026

Uh oh!

davidkna-sap Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	Messages passed alongside a `template_ref` are automatically routed to `messages_history` and cannot be merged into the remotely stored template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows.
	Messages passed alongside a `template_ref` are automatically routed to `messages_history` and cannot be merged into the remotely stored template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows with template references.

	Messages passed alongside a configuration reference are automatically routed to `messages_history` and cannot be merged into the remotely stored configuration's prompt template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows.
	Messages passed alongside a configuration reference are automatically routed to `messages_history` and cannot be merged into the remotely stored configuration's prompt template. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for the recommended two-client pattern in multi-turn workflows with configuration references.

	Template messages are always prepended to every request. Reusing the same client across multiple turns will include the template on every call. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for how to avoid duplication in multi-turn workflows.
	Template messages are always prepended to every request. Reusing the same client across multiple turns will include the template on every call. See the [LangGraph tutorial](../tutorials/langgraph-template-orchestration-client) for how to avoid duplication in multi-turn workflows with prompt templates.

	checkpointSaver: new MemorySaver()
	checkpointer: new MemorySaver()

Uh oh!

Conversation

BrigittaK307 commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

BrigittaK307 commented Jul 9, 2026 •

edited

Loading