fix: more info on system prompt for agents (#1736)

Author: sydney-runkle

src/oss/langchain/agents.mdx

@@ -464,10 +464,70 @@ const agent = createAgent({
 
 :::python
 When no @[`system_prompt`] is provided, the agent will infer its task from the messages directly.
+
+The @[`system_prompt`] parameter accepts either a `str` or a @[`SystemMessage`]. Using a `SystemMessage` gives you more control over the prompt structure, which is useful for provider-specific features like [Anthropic's prompt caching](/oss/integrations/chat/anthropic#prompt-caching):
+
+```python wrap
+from langchain.agents import create_agent
+from langchain.messages import SystemMessage, HumanMessage
+
+literary_agent = create_agent(
+    model="anthropic:claude-sonnet-4-5",
+    system_prompt=SystemMessage(
+        content=[
+            {
+                "type": "text",
+                "text": "You are an AI assistant tasked with analyzing literary works.",
+            },
+            {
+                "type": "text",
+                "text": "<the entire contents of 'Pride and Prejudice'>",
+                "cache_control": {"type": "ephemeral"}
+            }
+        ]
+    )
+)
+
+result = literary_agent.invoke(
+    {"messages": [HumanMessage("Analyze the major themes in 'Pride and Prejudice'.")]}
+)
+```
+
+The `cache_control` field with `{"type": "ephemeral"}` tells Anthropic to cache that content block, reducing latency and costs for repeated requests that use the same system prompt.
 :::
 
 :::js
 When no `systemPrompt` is provided, the agent will infer its task from the messages directly.
+
+The `systemPrompt` parameter accepts either a `string` or a `SystemMessage`. Using a `SystemMessage` gives you more control over the prompt structure, which is useful for provider-specific features like [Anthropic's prompt caching](/oss/integrations/chat/anthropic#prompt-caching):
+
+```ts wrap
+import { createAgent } from "langchain";
+import { SystemMessage, HumanMessage } from "@langchain/core/messages";
+
+const literaryAgent = createAgent({
+  model: "anthropic:claude-sonnet-4-5",
+  systemPrompt: new SystemMessage({
+    content: [
+      {
+        type: "text",
+        text: "You are an AI assistant tasked with analyzing literary works.",
+      },
+      {
+        type: "text",
+        text: "<the entire contents of 'Pride and Prejudice'>",
+        cache_control: { type: "ephemeral" }
+      }
+    ]
+  })
+});
+
+const result = await literaryAgent.invoke({
+  messages: [new HumanMessage("Analyze the major themes in 'Pride and Prejudice'.")]
+});
+```
+
+The `cache_control` field with `{ type: "ephemeral" }` tells Anthropic to cache that content block, reducing latency and costs for repeated requests that use the same system prompt.
 :::
 
 #### Dynamic system prompt