Tool access to long-term memory
Tools can read from and write to the store using the runtime.store parameter. This enables tools to retrieve stored information and persist new information to long-term memory.
LangChain · Agents · all subjects
tool calling & structured output
43 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Tool calls in AIMessage
When models make tool calls, they are included in AIMessage. Each tool call contains: name (tool name), args (tool arguments), id (unique call identifier). Access via response.tool_calls iteration.
ToolMessage attributes and structure
ToolMessage contains: content (string, required) - stringified output of tool call; tool_call_id (string, required) - ID of tool call being responded to, must match AIMessage tool_call id; name (string, required) - name of tool that was called; artifact (dict, optional) - additional data not sent to model but accessible programmatically.
ToolMessage artifact field usage
The artifact field stores supplementary data that won't be sent to the model but can be accessed programmatically. Useful for storing raw results, debugging information, or data for downstream processing without cluttering model context. Example: artifact={"document_id": "doc_123", "page": 0}
Tool calling content block types
ToolCall (type: 'tool_call') - function calls with name, args, id; ToolCallChunk (type: 'tool_call_chunk') - streaming tool call fragments with partial args; InvalidToolCall (type: 'invalid_tool_call') - malformed calls with error description.
Server-side tool execution content blocks
ServerToolCall (type: 'server_tool_call') - tool call executed server-side with id, name, args; ServerToolCallChunk (type: 'server_tool_call_chunk') - streaming server-side tool call fragments; ServerToolResult (type: 'server_tool_result') - search results with tool_call_id, status ('success' or 'error'), output.
ToolCall content block structure
ToolCall content block contains: type (required, always 'tool_call'); name (required, tool name); args (required, object with tool arguments); id (required, unique identifier for tool call).
ContentBlock.Tools.ToolCall in TypeScript
ContentBlock.Tools.ToolCall contains: type (required, always 'tool_call'); name (required, tool name); args (required, object with tool arguments); id (required, unique identifier for tool call).
InvalidToolCall content block structure
InvalidToolCall contains: type (required, always 'invalid_tool_call'); name (name of tool that failed to be called); args (string with raw arguments that failed to parse); error (required, description of what went wrong).
ContentBlock.Tools.ToolCallChunk in TypeScript
ContentBlock.Tools.ToolCallChunk contains: type (required, always 'tool_call_chunk'); name (tool name being called); args (string with partial tool arguments, may be incomplete JSON); id (tool call identifier); index (required, position of chunk in stream).
ContentBlock.Tools.InvalidToolCall in TypeScript
ContentBlock.Tools.InvalidToolCall contains: type (required, always 'invalid_tool_call'); name (name of tool that failed); args (string with raw arguments); error (required, description of error); common errors include invalid JSON and missing required fields.
ServerToolCall content block structure
ServerToolCall contains: type (required, always 'server_tool_call'); id (required, identifier associated with tool call); name (required, name of tool to be called); args (required, string with partial tool arguments, may be incomplete JSON).
ServerToolCallChunk content block structure
ServerToolCallChunk contains: type (required, always 'server_tool_call_chunk'); id (identifier associated with tool call); name (name of tool being called); args (string with partial tool arguments, may be incomplete JSON); index (position of chunk in stream).
ServerToolResult content block structure
ServerToolResult contains: type (required, always 'server_tool_result'); tool_call_id (required, identifier of corresponding server tool call); id (identifier associated with server tool result); status (required, execution status: 'success' or 'error'); output (output of executed tool).
Tool message example with tool call correlation
Example shows creating AIMessage with tool_calls array containing tool call with id 'call_123', then creating ToolMessage with tool_call_id='call_123' to correlate the tool result back to the original call. Messages flow: HumanMessage -> AIMessage with tool_calls -> ToolMessage -> model processes result.
Nested structures in structured output
Schemas for structured output can contain nested structures. In Python, this is done with Pydantic BaseModel or TypedDict classes containing list or nested model fields. In JavaScript, this is done with nested z.object() definitions.
Tool definition using tool() function in JavaScript
In JavaScript, tools are created using the tool() function from 'langchain', passing the execution function, name, description, and schema (defined with zod) as parameters.
Server-side tool use with LangChain
Some providers support server-side tool-calling loops where models can interact with web search, code interpreters, and other tools and analyze results in a single conversational turn. When a model invokes a tool server-side, the response message content includes content representing the invocation and result of the tool in a provider-agnostic format.
Server-side tool content blocks format
Server-side tool calls and results are returned as content blocks with the following types: 'server_tool_call' (containing name, args, and id fields) and 'server_tool_result' (containing tool_call_id and status fields). A single conversational turn may contain multiple content blocks including text with annotations. There are no associated ToolMessage objects that need to be passed in as with client-side tool-calling.
Example: Server-side tool use in Python
```python from langchain.chat_models import init_chat_model model = init_chat_model("gpt-5.4-mini") tool = {"type": "web_search"} model_with_tools = model.bind_tools([tool]) response = model_with_tools.invoke("What was a positive news story from today?") print(response.content_blocks) ``` This demonstrates binding a server-side web_search tool and invoking it. The response.content_blocks will contain server_tool_call, server_tool_result, and text content blocks.
Example: Server-side tool use in TypeScript
```typescript import { initChatModel } from "langchain"; const model = await initChatModel("gpt-5.4-mini"); const modelWithTools = model.bindTools([{ type: "web_search" }]) const message = await modelWithTools.invoke("What was a positive news story from today?"); console.log(message.contentBlocks); ``` This demonstrates binding a server-side web_search tool and invoking it in TypeScript.
Example: Configurable model with bind_tools
```python from pydantic import BaseModel, Field class GetWeather(BaseModel): """Get the current weather in a given location""" location: str = Field(description="The city and state, e.g. San Francisco, CA") class GetPopulation(BaseModel): """Get the current population in a given location""" location: str = Field(description="The city and state, e.g. San Francisco, CA") model = init_chat_model(temperature=0) model_with_tools = model.bind_tools([GetWeather, GetPopulation]) model_with_tools.invoke( "what's bigger in 2024 LA or NYC", config={"configurable": {"model": "gpt-5.4-mini"}} ).tool_calls ``` This shows a configurable model with bound tools, then invoked with a specific model configuration.
bind_tools method for Python models
bind_tools() makes tools available to a model by binding them. It takes a list of tools and returns a model instance that can choose to call any of the bound tools. The resulting AIMessage response includes tool_calls that indicate which tools the model wants to execute.
bindTools method for JavaScript models
bindTools() makes tools available to a model by binding them in JavaScript. It takes a list of tools and returns a model instance that can choose to call any of the bound tools. The resulting AIMessage response includes tool_calls that indicate which tools the model wants to execute.
Tool structure in LangChain
Tools are pairings of: (1) a schema including the tool name, description, and/or argument definitions (often a JSON schema), and (2) a function or coroutine to execute.
Tool calling flow with models
The basic tool calling flow: (1) User sends a request to the model, (2) Model analyzes the request and decides which tools are needed, (3) Model makes parallel tool calls if appropriate, (4) Tools execute and return results, (5) Results are passed back to the model, (6) Model processes results and generates final response to user.
ToolMessage correlation with tool calls
Each ToolMessage returned by a tool includes a tool_call_id that matches the original tool call, helping the model correlate results with requests.
Tool execution loop implementation
When a model returns tool calls, you must execute the tools and pass results back to the model. This creates a conversation loop where the model can use tool results to generate a final response. Step 1: Model generates tool calls via invoke(). Step 2: Execute each tool with its generated arguments. Step 3: Pass tool results back to model in messages list for final response generation.
Forcing tool calls with tool_choice parameter
By default, the model can choose which bound tool to use. Set tool_choice='any' to force use of any tool from the list, or tool_choice='tool_1' to force use of a specific tool.
Parallel tool calls support
Many models support calling multiple tools in parallel when appropriate. The model intelligently determines when parallel execution is appropriate based on the independence of requested operations. Most models supporting tool calling enable parallel calls by default. Some providers like OpenAI and Anthropic allow disabling this by setting parallel_tool_calls=False.
Streaming tool calls with ToolCallChunk
When streaming responses with tool calls, tool calls are progressively built through ToolCallChunk objects. This allows viewing tool calls as they're being generated rather than waiting for the complete response.
with_structured_output method for Python
with_structured_output() constrains a model's response to follow a defined schema. It accepts Pydantic models, TypedDict, or JSON Schema. Supported method parameters are: 'json_schema' (uses dedicated provider features), 'function_calling' (derives structured output by forcing a tool call), and 'json_mode' (generates valid JSON with schema in prompt).
withStructuredOutput method for JavaScript
withStructuredOutput() constrains a model's response to follow a defined schema in JavaScript. It accepts Zod schemas, JSON Schema, or Standard Schema objects. Supported method parameters include 'jsonSchema', 'functionCalling', and 'jsonMode'. Set includeRaw: true to get both parsed output and raw AIMessage.
Structured output with include_raw parameter
Setting include_raw=True when calling with_structured_output() in Python (or includeRaw: true in JavaScript) returns both the parsed output and the raw AIMessage object, allowing access to response metadata such as token counts.
Pydantic models for structured output in Python
Pydantic models provide the richest feature set for structured output with field validation, descriptions, and nested structures. Fields can be defined with BaseModel and Field with descriptions.
Zod schemas for structured output in JavaScript
Zod schemas are the preferred method for defining output schemas in JavaScript. When provided, model output is automatically validated against the schema using zod's parse methods.
Built-in tools from model providers
Some model providers offer built-in tools that can be executed server-side, such as web search and code interpreters. These can be enabled via model or invocation parameters. Check the respective provider reference for details.
Tool definition for agents
In Python, define tools with @tool decorator. In TypeScript, use tool() function with name, description, and schema parameters. Example: tool(async ({ city }) => { return `It's 75 degrees...`; }, { name: 'get_weather', description: 'Get weather...', schema: z.object({ city: z.string() }) }).
Tool definition using tool() function in TypeScript
In TypeScript/JavaScript, tools are created using the tool() function from @langchain/core/tools. The function signature is: tool(handler, config) where handler is an async function that executes the tool, and config is an object with: name (string), description (string), and schema (Zod object or JSON schema). The schema defines input validation. Example: tool(async ({url}) => {...}, { name: 'fetch_text_from_url', description: '...', schema: z.object({url: z.string().url()}) })
Tool schema definition with Zod in TypeScript
Zod schemas for tools use z.object() with properties for each parameter. Each property uses Zod type functions like z.string(), z.number(), etc., with optional .describe() for documentation. Example: z.object({ city: z.string().describe('The city to get the weather for') }). Zod schemas are validated at runtime. Alternatively, JSON schemas can be used but won't be validated at runtime.
Fetch URL tool example in Python
Example of implementing a fetch_text_from_url tool in Python: import urllib.error import urllib.request from langchain.tools import tool @tool def fetch_text_from_url(url: str) -> str: """Fetch the document from a URL.""" req = urllib.request.Request( url, headers={"User-Agent": "Mozilla/5.0 (compatible; quickstart-research/1.0)"}, ) try: with urllib.request.urlopen(req, timeout=120) as resp: raw = resp.read() except urllib.error.URLError as e: return f"Fetch failed: {e}" text = raw.decode("utf-8", errors="replace") return text
Tool definition using @tool decorator in Python
In Python, tools are defined using the @tool decorator from langchain.tools. The decorator transforms a function into a tool object. The function's docstring serves as the tool description. Function parameters become the tool's input schema. Example: @tool decorator on a function fetch_text_from_url(url: str) -> str with a docstring creates a tool with name 'fetch_text_from_url' and parameter 'url' of type string. The @tool decorator adds metadata and enables runtime injection with ToolRuntime parameter.
Fetch URL tool example in TypeScript
Example of implementing a fetch_text_from_url tool in TypeScript: import { tool } from "@langchain/core/tools"; import { z } from "zod"; const fetchTextFromUrl = tool( async ({ url }: { url: string }): Promise<string> => { const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 120_000); try { const resp = await fetch(url, { headers: { "User-Agent": "Mozilla/5.0 (compatible; quickstart-research/1.0)", }, signal: controller.signal, }); if (!resp.ok) { return `Fetch failed: HTTP ${resp.status} ${resp.statusText}`; } return await resp.text(); } catch (e) { const msg = e instanceof Error ? e.message : String(e); return `Fetch failed: ${msg}`; } finally { clearTimeout(timeoutId); } }, { name: "fetch_text_from_url", description: "Fetch the document from a URL.", schema: z.object({ url: z.string().url() }), }, );