From f101c759ed0e1df8bcf9044a429dc578e0c33b22 Mon Sep 17 00:00:00 2001
From: Bagatur <22008038+baskaryan@users.noreply.github.com>
Date: Fri, 19 Jul 2024 11:36:28 -0700
Subject: [PATCH] docs: how to pass runtime secrets (#24450)

---
 docs/docs/how_to/index.mdx                    |  2 +
 .../how_to/runnable_runtime_secrets.ipynb     | 78 +++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 docs/docs/how_to/runnable_runtime_secrets.ipynb

diff --git a/docs/docs/how_to/index.mdx b/docs/docs/how_to/index.mdx
index 2c9f8d51c6d1c..90d359422a794 100644
--- a/docs/docs/how_to/index.mdx
+++ b/docs/docs/how_to/index.mdx
@@ -44,6 +44,7 @@ This highlights functionality that is core to using LangChain.
 - [How to: inspect runnables](/docs/how_to/inspect)
 - [How to: add fallbacks to a runnable](/docs/how_to/fallbacks)
 - [How to: migrate chains to LCEL](/docs/how_to/migrate_chains)
+- [How to: pass runtime secrets to a runnable](/docs/how_to/runnable_runtime_secrets)
 
 ## Components
 
@@ -199,6 +200,7 @@ LangChain [Tools](/docs/concepts/#tools) contain a description of the tool (to p
 - [How to: return artifacts from a tool](/docs/how_to/tool_artifacts/)
 - [How to: convert Runnables to tools](/docs/how_to/convert_runnable_to_tool)
 - [How to: add ad-hoc tool calling capability to models](/docs/how_to/tools_prompting)
+- [How to: pass in runtime secrets](/docs/how_to/runnable_runtime_secrets)
 
 ### Multimodal
 
diff --git a/docs/docs/how_to/runnable_runtime_secrets.ipynb b/docs/docs/how_to/runnable_runtime_secrets.ipynb
new file mode 100644
index 0000000000000..819cdf1cbe60c
--- /dev/null
+++ b/docs/docs/how_to/runnable_runtime_secrets.ipynb
@@ -0,0 +1,78 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "6fcd2994-0092-4fa3-9bb1-c9c84babadc5",
+   "metadata": {},
+   "source": [
+    "# How to pass runtime secrets to runnables\n",
+    "\n",
+    ":::info Requires `langchain-core >= 0.2.22`\n",
+    "\n",
+    ":::\n",
+    "\n",
+    "We can pass in secrets to our runnables at runtime using the `RunnableConfig`. Specifically we can pass in secrets with a `__` prefix to the `configurable` field. This will ensure that these secrets aren't traced as part of the invocation:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "92e42e91-c277-49de-aa7a-dfb5c993c817",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "7"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from langchain_core.runnables import RunnableConfig\n",
+    "from langchain_core.tools import tool\n",
+    "\n",
+    "\n",
+    "@tool\n",
+    "def foo(x: int, config: RunnableConfig) -> int:\n",
+    "    \"\"\"Sum x and a secret int\"\"\"\n",
+    "    return x + config[\"configurable\"][\"__top_secret_int\"]\n",
+    "\n",
+    "\n",
+    "foo.invoke({\"x\": 5}, {\"configurable\": {\"__top_secret_int\": 2, \"traced_key\": \"bar\"}})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ae3a4fb9-2ce7-46b2-b654-35dff0ae7197",
+   "metadata": {},
+   "source": [
+    "Looking at the LangSmith trace for this run, we can see that \"traced_key\" was recorded (as part of Metadata) while our secret int was not: https://smith.langchain.com/public/aa7e3289-49ca-422d-a408-f6b927210170/r"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "poetry-venv-311",
+   "language": "python",
+   "name": "poetry-venv-311"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}