How to make tools store custom variables in Agent's state when using create_deep_agent()?

[Sai Akhilesh Ande (akhil189)]

I have a workflow with 3 tools (SQL tool, Retriever Tool, Report Tool).

Retriever Tool - retrieves context from a vectorstore (List[Document])
SQL Tool - creates a valid SQL query
Report Tool - accepts a SQL query and creates a csv report

Based on user query, the agent has to call one or more tools. The workflow is specified in skills. I need my tools to

1. Store the context in agent's state and
2. Return a ToolMessage to the main agent

I need them in agent's state because:

1. I need the context for highlighting (grounding) on the UI and also logging.
2. If there a filepath, I want to provide a download option on the UI.

from langchain.tools import ToolRuntime, tool
from langgraph.types import Command
from langchain_core.messages import ToolMessage
from langchain.agents import AgentState, create_agent
from typing import Annotated, List
from langchain_core.documents import Document


@tool
def generate_report(self, sql_query: str, runtime: ToolRuntime) -> Command:
    """Takes in a SQL query and generates a csv file with postprocessing

    Args:
        sql_query: A valid SQL query
        runtime: LangChain ToolRuntime providing the tool_call_id for ToolMessage.

    Returns:
        Command updating the agent state with the saved document and a ToolMessage.
    """

    # <Logic to create the csv file>
    path = ...

    return Command(
        update={
            "reports": [path],
            "messages": [
                ToolMessage(
                    content=f"report successfully generated",
                    tool_call_id=runtime.tool_call_id,
                )
            ],
        }
    )

@tool
def context_retriever(query: str, runtime: ToolRuntime) -> Command:
    """Retrieves context from a vectorstore

    Args:
        query: The query to find relevant context.
    """

    # logic to retrieve Documents from a vectorstore
    docs = ...
    formatted = "\n".join([doc.content for doc in docs])

    return Command(
        update={
            "agent_context": docs,
            "messages": [
                ToolMessage(
                    content=formatted,
                    tool_call_id=runtime.tool_call_id,
                )
            ],
        }
    )

class CustomState(AgentState):
    """Extended state that tracks context alongside messages."""

    agent_context: List[Document] # docs from vectorstore
    reports = List[str] # filepaths

### with create_agent()
agent = create_agent(
    model=...,
    system_prompt=...,
    tools=[...],
    state_schema=CustomState
)

### with deep_agent()
agent = create_deep_agent(
    model=...,
    system_prompt=...,
    tools=[...],
    state_schema=CustomState # not accepted
)

How to achieve the same with create_deep_agent()?

[Yokubjon (yakubka)]

Tools in a create_deep_agent() setup do not have direct write access to the agent state by default. The standard pattern to persist values across tool calls is to use a TypedDict state schema with Annotated fields and return a state patch from the tool.

Here is the minimal pattern for your case:

from typing import Annotated, List
from langgraph.graph import add_messages
from langchain_core.documents import Document
import operator

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    retrieved_context: Annotated[List[Document], operator.add]
    sql_query: str

@tool
def retriever_tool(query: str, state: AgentState) -> dict:
    docs = vectorstore.similarity_search(query)
    return {"retrieved_context": docs}

@tool
def sql_tool(question: str, state: AgentState) -> dict:
    query = build_sql(question, state["retrieved_context"])
    return {"sql_query": query}

@tool
def report_tool(state: AgentState) -> str:
    df = run_query(state["sql_query"])
    df.to_csv("report.csv")
    return "report.csv"

The key points: pass state_schema=AgentState to create_deep_agent(), and each tool returns a dict of state keys to update rather than a plain string. LangGraph merges the returned dict into the checkpoint state, so subsequent tools see the values written by earlier ones.