update

Author: npentrel

src/code-samples/langchain/tool-update-state.py

@@ -0,0 +1,57 @@
+# :snippet-start: tool-update-state-py
+from langchain.agents import AgentState
+from langchain.messages import ToolMessage
+from langchain.tools import ToolRuntime, tool
+from langgraph.types import Command
+
+
+class CustomState(AgentState):
+    user_name: str
+
+
+@tool
+def set_user_name(new_name: str, runtime: ToolRuntime[None, CustomState]) -> Command:
+    """Set the user's name in the conversation state."""
+    return Command(
+        update={
+            "user_name": new_name,
+            "messages": [
+                ToolMessage(
+                    content=f"User name set to {new_name}.",
+                    tool_call_id=runtime.tool_call_id,
+                )
+            ],
+        }
+    )
+
+
+# :snippet-end:
+
+# :remove-start:
+if __name__ == "__main__":
+    from langchain.agents import create_agent
+    from langchain_anthropic import ChatAnthropic
+
+    model = ChatAnthropic(model_name="claude-sonnet-4-6", timeout=None)
+
+    agent = create_agent(
+        model,
+        tools=[set_user_name],
+        state_schema=CustomState,
+        system_prompt=(
+            "You are a test harness. Always call the `set_user_name` tool when asked to "
+            "set the user's name. Reply with a brief confirmation."
+        ),
+    )
+    result = agent.invoke(
+        {"messages": [{"role": "user", "content": "Set my name to Alice."}]}
+    )
+
+    assert result["user_name"] == "Alice"
+    tool_messages = [m for m in result["messages"] if isinstance(m, ToolMessage)]
+    assert len(tool_messages) == 1
+    assert tool_messages[0].content == "User name set to Alice."
+    assert tool_messages[0].tool_call_id, "expected tool_call_id to be set"
+
+    print("✓ Tool works as expected")
+# :remove-end:

src/oss/langchain/tools.mdx

@@ -8,6 +8,7 @@ import ToolReturnObjectPy from '/snippets/code-samples/tool-return-object-py.mdx
 import ToolReturnObjectJs from '/snippets/code-samples/tool-return-object-js.mdx';
 import ToolReturnCommandPy from '/snippets/code-samples/tool-return-command-py.mdx';
 import ToolReturnCommandJs from '/snippets/code-samples/tool-return-command-js.mdx';
+import ToolUpdateStatePy from '/snippets/code-samples/tool-update-state-py.mdx';
 
 Tools extend what [agents](/oss/langchain/agents) can do—letting them fetch real-time data, execute code, query external databases, and take actions in the world.
 
@@ -279,27 +280,7 @@ def get_user_preference(
 Use @[`Command`] to update the agent's state. This is useful for tools that need to update custom state fields.
 Include a `ToolMessage` in the update so the model can see the result of the tool call:
 
-```python
-from langchain.messages import ToolMessage
-from langchain.tools import ToolRuntime, tool
-from langgraph.types import Command
-
-
-@tool
-def set_user_name(new_name: str, runtime: ToolRuntime) -> Command:
-    """Set the user's name in the conversation state."""
-    return Command(
-        update={
-            "user_name": new_name,
-            "messages": [
-                ToolMessage(
-                    content=f"User name set to {new_name}.",
-                    tool_call_id=runtime.tool_call_id,
-                )
-            ],
-        }
-    )
-```
+<ToolUpdateStatePy />
 
 <Tip>
     When tools update state variables, consider defining a [reducer](/oss/langgraph/graph-api#reducers) for those fields. Since LLMs can call multiple tools in parallel, a reducer determines how to resolve conflicts when the same state field is updated by concurrent tool calls.

src/snippets/code-samples/tool-update-state-py.mdx

@@ -0,0 +1,26 @@
+```python
+from langchain.agents import AgentState
+from langchain.messages import ToolMessage
+from langchain.tools import ToolRuntime, tool
+from langgraph.types import Command
+
+
+class CustomState(AgentState):
+    user_name: str
+
+
+@tool
+def set_user_name(new_name: str, runtime: ToolRuntime[None, CustomState]) -> Command:
+    """Set the user's name in the conversation state."""
+    return Command(
+        update={
+            "user_name": new_name,
+            "messages": [
+                ToolMessage(
+                    content=f"User name set to {new_name}.",
+                    tool_call_id=runtime.tool_call_id,
+                )
+            ],
+        }
+    )
+```