Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
AI and LLM integration

ChatPromptTemplate is missing the variable agent_scratchpad

ErrorInput to ChatPromptTemplate is missing variables {'agent_scratchpad'}

Short answer

A tool-calling agent keeps its tool calls and tool results in a prompt slot named agent_scratchpad. If your ChatPromptTemplate has no such placeholder, or you call the prompt by hand without it, LangChain reports missing variables. Add a placeholder for agent_scratchpad, or move to create_agent, which needs no scratchpad in the prompt.

  • Applies to Python 3.12, langchain 1.x, langchain-classic 1.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the variables your prompt expects, then compare them with the keys you pass. agent_scratchpad should come from the agent, never from your own dictionary.

    python -c "from my_agent import prompt; print(prompt.input_variables, prompt.optional_variables)"
  2. 2Match what you see, then jump to its fix

    1. 1The prompt list holds only system and human messagesThe prompt has no placeholder for the scratchpadFix
    2. 2The code builds a prompt only to satisfy create_react_agent or a similar helperUsing the old agent builders on LangChain 1.xFix

What does the error look like?

  • Input to ChatPromptTemplate is missing variables {'agent_scratchpad'}
  • Expected: ['agent_scratchpad', 'input']

Cause 1 of 2

The prompt has no placeholder for the scratchpad

1Check

The reference for create_tool_calling_agent says the prompt must include an agent_scratchpad key and that it must be a MessagesPlaceholder. Intermediate actions and tool output are passed through it.

grep -n "agent_scratchpad" *.py

2Fix

Add the placeholder as the last message, after the human input.

from langchain_core.prompts import ChatPromptTemplate

prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a helpful assistant"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])

3Verify

Run the agent through an executor. The executor fills the scratchpad on every step.

from langchain_classic.agents import AgentExecutor, create_tool_calling_agent
agent = create_tool_calling_agent(llm, tools, prompt)
print(AgentExecutor(agent=agent, tools=tools).invoke({"input": "hello"}))

Confirmed by reference.langchain.com

Did this fix it?

Cause 2 of 2

Using the old agent builders on LangChain 1.x

1Check

The v1 migration guide says create_react_agent is replaced by create_agent, and that the prompt= argument is renamed system_prompt=.

python -m pip list | grep -i langchain

2Fix

Use create_agent with a plain system prompt. You pass messages instead of an input key, so no prompt template and no scratchpad variable exist.

from langchain.agents import create_agent

agent = create_agent(
    model=llm,
    tools=tools,
    system_prompt="You are a helpful assistant.",
)
result = agent.invoke({"messages": [{"role": "user", "content": "hello"}]})

3Verify

The last message in the result holds the answer.

print(result['messages'][-1].content)

Confirmed by docs.langchain.com

Did this fix it?

How do I stop it coming back?

  • Keep the scratchpad placeholder as the last item of any prompt used by a tool-calling agent.
  • Never put agent_scratchpad in the dictionary you pass to invoke; the executor supplies it.
  • For new projects start with create_agent, since the older agent builders now live in langchain-classic.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

AI

LangChain says it could not import the chromadb package

ImportError: Could not import chromadb python package. Please install it with `pip install chromadb`.

The message comes from LangChain's old Chroma class, which cannot import chromadb in the Python that runs your code.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.